Um Guia que vai te ajudar com o README do GitHub

Um bom README vale mais que mil palavras.

É útil colocar o código e o trabalho técnico em um lugar acessível aos outros. O melhor e mais popular meio para cientistas e desenvolvedores divulgarem seus trabalhos é o GitHub.

GitHub é uma plataforma de hospedagem de código-fonte e arquivos com controle de versão usando o Git. A plataforma permite que programadores, desenvolvedores ou qualquer usuário cadastrado construa seus repositórios, contribuam em projetos privados ou públicos de onde for.

README

Potenciais empregadores e outros programadores da comunidade tentarão entender o projeto através do README. A comunicação clara do README é útil para o usuário e toda a comunidade.

GitHub é uma boa evidência

é necessário de pessoas que se ajustem e se integrem bem às equipes. O GitHub sinaliza essa dinâmica.

introdução

estrutura

O layout se parece com este:

type: O título consiste no tipo de mensagem e assunto.bodyfooter

O tipo está contido no título e pode ser um desses tipos:

  • feat: Um novo recurso
  • fix: Uma correção de bugs
  • docs: Alterações na documentação
  • style: Formatação, falta de semi-cólons, etc; nenhuma mudança de código
  • refactor: Refatorando o código de produção
  • test: Adicionando testes, refatorando o teste; nenhuma mudança de código de produção
  • chore: Atualizando tarefas de compilação, o gerenciador de pacotes configs, etc; nenhuma mudança de código de produção

tópicos

Use um tom imperativo para descrever o que o projeto faz, em vez do que ele fez. Por exemplo, use a mudança; não mudou ou muda.

Nem todos os carregamentos são complexos o suficiente para justificar a descrição de corpo, portanto ele é opcional e só é usado quando um requer um pouco de explicação e contexto sobre o que o esquema se trata. Use o corpo para explicar o quê e por quê, e não como.

Ao escrever um corpo para o esquema, a linha em branco entre o título e o corpo da descrição é necessária e devemos limitar o comprimento de cada linha a não mais do que 72 caracteres.

o rodapé

exemplo genérico

feat: Resumir conteúdo em cerca de 50 caracteres ou menosTexto explicativo mais detalhado, se necessário. 
Embrulhe-o para cerca de 72 caracteres.
Em alguns contextos, a primeira linha é tratada como o assunto do projeto e o resto do texto como o corpo.
A linha em branco separando o resumo do corpo é crítica (a menos que você omita o corpo inteiramente); várias ferramentas como 'log', 'shortlog' e 'rebase' podem ficar confuso se você executar os dois juntos.
Explique o problema que esse projeto está resolvendo.
Concentre-se em porque você está fazendo esse ajuste em oposição a como código estava.
Outros parágrafos vêm depois de linhas em branco.- Tópicos também caem bem.- Tipicamente um hífen ou asterisco é usado para o tópic, precedido
por um único espaço, com linhas em branco no meio, mas convenções
variam aqui
Se você usar um rastreador de problemas, coloque referências a eles na parte inferior,
Assim:
Resolve: #123
Veja também: #456, #789

outros excelentes exemplos

Exemplo 1: Bootstrap

Não só este README tem todas as informações de um bom arquivo README, como também fornece uma tabela de conteúdo para navegar rapidamente! Dependendo do tempo que seu arquivo README é, fornecer uma tabela de conteúdo é uma excelente ideia para ajudar outras pessoas a navegar em sua documentação.

Exemplo 2: Scikit-Learn

Portanto, a descrição limitada de como usar esta biblioteca no README deve-se à enorme quantidade de informações em torno do scikit-learn em outra documentação. Você pode encontrar um exemplo da documentação que o leva através desta extensa biblioteca aqui.

Exemplo 3: Stack Overflow Blog

1. Instalação - Bibliotecas extras que não estão instaladas com a distribuição Anaconda, bem como qual versão de python você está usando devem ser anotadas.

2. Motivação do Projeto - Discuta sobre o que é o seu projeto e o que o interessou em prosseguir com o projeto.

3.Descrições do arquivo - Guie outros através dos arquivos em seu repositório. Você pode não falar sobre cada arquivo aqui, mas você deve deixá-los saber onde eles podem encontrar o trabalho que eles podem achar mais interessante.

4. Como interagir com seu projeto - Quando seu projeto não é feito para ser interativo ou usado para outros projetos, você deve, em vez disso, falar sobre os detalhes técnicos do seu projeto. Quais foram seus resultados? O que você fez para melhorá-los? Que métodos você tentou? O que funcionou? O que não funcionou?

5.Licenciamento, Autores, Reconhecimentos - Você sempre quer dar crédito quando necessário. Reconheça outros colaboradores, colegas úteis, provedores de dados, etc.

*Bônus

publicar trabalhos

Depois de criarmos o repositório, veremos a página com instruções sobre como começar na máquina local. Copiando esta parte aqui ou clicando na parte do README, podemos criar um repositório.

Ao copiar a URL, usando git clone com o URL, podemos clonar o repositório para o nosso local.

alguns comandos úteis

  • git clone - clonar um repositório de qualquer url para sua máquina local
  • git add * - adiciona todos os arquivos do repositório à área de encenação
  • git commit -m 'comment about changes made' - comete alterações e adiciona uma mensagem para as mudanças feitas
  • git push - empurra suas alterações para um repositório remoto

lista de tarefas para configurar repositório GitHub (inglês)

task list

Composing a repository of books (i bought), authors (i follow) & blogs (direct ones) for my own understanding.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store