Profissionalizando seus projetos no GitHub

O Git é A ferramenta mais usada entre desenvolvedores. O desenvolvedor pode usar Linux, Mac ou Windows, pode usar Apache, NGINX ou algum Static Server, pode usar PHP, Python, Ruby, Go ou JS (NodeJS), mas todos usam GIT.

Gráfico Git vs SVN

E o GitHub é, de longe, a plataforma mais utilizada pelas comunidades de todos os lados do mundo para projetos Open Source, ou até para projetos privados.

Vamos ver algumas dicas aqui para deixar o teu projeto no GitHub mais "profissa" :)

Notem que não há uma receita de bolo, não há uma forma certa ou errada ou A MELHOR forma, mas sim, algumas boas práticas.

README.md

Tenha um arquivo README.md na raiz do seu projeto. Isso fará com que usuários tenham um acesso rápido a um conteúdo relevante sobre como utilizar seu projeto.

Aproveite esse espaço também para acrescentar um TL;DR para aqueles que querem apenas ter uma visão rápida sobre o projeto.

Além disso, pode colocar também uma F.A.Q. e links para demos ou uma documentação mais extensa.

Licença

É fundamental ter uma licença em seu projeto. Muitos desenvolvedores que poderiam influenciar positivamente no teu projeto ou na divulgação do mesmo, ou empresas e outros desenvolvedores que poderiam passar a usá-lo, poderão perder um pouco do interesse ao perceber que você não adotou uma licença oficialmente. Saber escolher a licença também é importante, para isso existe o site choose a license, que vai te ajudar a decidir. Vale ressaltar que algumas licenças, como a GPL/LGPL, exigem que todos os que usarem seu projeto como parte de algo maior, e devem oferecer seu produto usando a mesma licença. Isso pode ser desencorajador para algumas empresas ou pessoas.

Ah...mais uma coisa. Ao usar uma licença, o próprio GitHub vai mostrar um pequeno ícone com ela no topo do projeto.

Licença no GitHub

Como colocar uma licença no seu projeto

Crie um arquivo com o nome LICENSE na raiz do seu projeto e cole no seu conteúdo exatamente o conteúdo da licença. Exceto em casos em que a licença indica espaços a serem preenchidos com seus dados, não altere nada no conteúdo. Caso contrário, o GitHub não identificará seu projeto como licenciado. É o que acontece com vários projetos. Veja o gráfico abaixo com o número de projetos licenciados no GitHub. Parece que os novos projetos não estão dando tanta atenção às licenças.

Gráfico de projetos com licença no GitHub

Também é legal dar uma olhada na lista das licenças mais usadas:

Tabela de licenças mais usadas no GitHub

GH-Pages

Use o gh-pages a seu favor. Trata-se de um servidor para páginas estáticas, disponível para seu projeto.

E a boa notícia é que agora está ainda mais fácil usar o gh-pages. Até pouco tempo, éramos obrigados a usar ferramentas de build ou tasks para gerenciarmos o conteúdo de nossas páginas na branch gh-pages.

Agora podemos simplesmente criar um diretório na própria branch master com todo o conteúdo de nossa página de documentação:

Criando um diretório para usar como documentação

E então apontar na página de configurações do projeto, qual o diretório correspondente à gh-pages.

Definindo o diretório para a gh-pages

Uma abordagem interessante para a gh-pages é utilizá-la para centralizar alguns demos ou exemplos documentados. Mas sinta-se à vontade para acrescentar a documentação necessária.

Wiki

Ativar a opção de wiki pode ser uma boa opção para seu projeto, mas cuidado, utilizar ambas wiki e gh-pages para documentação pode ser um tiro no pé!

Aconselharia a apostar mais no gh-pages e, caso seu projeto tenha uma documentação realmente muito grande ou com uma API que precisa ser bem detalhada e organizada em um índice, então invista em montar uma wiki.

Selos

Uma coisa bem legal e que dá um ar mais sério ao projeto, é a utilização de selos ou badges.

Selos do projeto

O projeto shields.io oferece uma coleção de selos parametrizáveis para você adicionar ao seu projeto.

Issues e labels

Crie e gerencie as labels do seu projeto e tenha o costume de usá-las para demarcar cada issue.

Labels nas issues

Gerenciando Labels

Issues marcadas com labels

Milestones

Qualquer projeto grande precisa ser bem organizado, e os milestones estão aí para te ajudar.

Milestones

Além de organizar tarefas, eles agrupam metas do projeto, informam sobre atrasos e podem ser utilizados para uma melhor visualização de quanto falta para uma determinada meta ser atingida.

Arquivos de configuração

Mais uma dica útil relacionada ao seu código. Arquivos de configuração como os .*rc, ajudam a manter a ordem e até a disciplina entre os desenvolvedores no projeto.

Os principais seriam os arquivos de lint (como .eslintrc ou .stylintrc), .editorconfig e é claro, o .gitignore.

Testes Unitários

Testes unitários demonstram a seriedade do seu projeto e passam confiança para novas atualizações. Existem "n" opções de ferramentas para testes unitários. Não se esqueça de acrescentar em seu readme informações sobre como o desenvolvedor pode rodar os testes.

Ferramentas conectadas ao GitHub

O GitHub permite a utilização de diversas ferramentas que podem ser conectadas a ele por meio de suas APIs.

São exemplos o travisci, que rodará as tasks de build de sua aplicação e tentará passar seus testes unitários, linters, etc.

Outra ferramenta muito útil é o codacy, que validará a qualidade do código no seu projeto e inclusive oferecerá um selo com a nota final.

Codacy

Existem várias ferramentas que poderão oferecer uma cobertura de testes, avaliação de código, acessibilidade, performance, etc.

Branches

Não existe uma regra de qual o melhor formato, mas o que estou mais acostumado é o padrão em que a branch master é o equivalente ao projeto em produção, a branch development é a branch utilizada para desenvolver o projeto em si, trabalhar com atualizações e correções, e também merges, enquanto outras branches (geradas a partir da branch development) terão como nome, o nome da nova feature a ser desenvolvida, como por exemplo uma branch com o nome push-notification para desenvolver esta feature especificamente. Quando finalizo essa feature, costumo fazer o merge dela na branch development, para garantir compatibilidade com qualquer outra atualização em andamento nessa branch.

Uma boa prática é excluir sua branch assim que a feature nova for acrescentada à master. Dessa forma, evitamos "sujeira" com uma lista enorme de branches, e mantemos as branches development e master com seus objetivos.

Versões, releases e tags

É cada vez mais importante usar com inteligência o versionamento de nossos projetos.

Por padrão, os números de versão seguem o formato x.y.z, onde:

• x: Major, uma alteração grande, uma virada de versão que não é 100% compatível com a versão x-1.

• y: Minor, uma alteração importante com uma nova funcionalidade ou correção. Deve funcionar com a versão y-1, mas algo na API pode ter sido alterado ou acrescentado.

• z: Patch, um update pontual para corrigir algum bug ou melhorar alguma performance. Normalmente, não oferece riscos à compatibilidade do projeto

Com isto em mente, lembre-se de gerar uma nova tag no GitHub para cada atualização (incluindo patches). Normalmente criamos tags com nomes relacionados à versão:

git tag -a v1.4.0 -m "my update" 

O comando git tag -a v1.4.0 criará a tag "v1.4.0", enquanto o parâmetro -m "my update" acrescentará uma mensagem a sua tag.

Já um release, no GitHub, está mais relacionado a alguma alteração maior, como uma atualização no minor ou no major.

Releases no GitHub

Templates

O GitHub também oferece suporte a templates para quem for abrir uma nova issue, ou fazer uma pull request. Para tal, crie um arquivo chamado ISSUE_TEMPLATE.md ou PULL_REQUEST_TEMPLATE.md respectivamente.

É interessante criar também um CONTRIBUTING.md instruindo aqueles que pretendem contribuir com seu projeto.

Caso a raiz do projeto esteja muito "bagunçada", cheia de arquivos de configurações, você também pode criar um diretório .GitHub/ e colocar esses arquivos dentro dele.

Uma coisa útil é que o próprio GitHub indica estas configurações para os interessados.

Template para Contribuição

Template para Issues

Confira nestes artigos mais umas dicas de como utilizar templates no GitHub.

Projects

Agora, o GitHub oferece também suporte para criação de projects. É bom para melhorar a forma como sua organização funciona dentro do GitHub e permite trabalhar com um sistema muito parecido com Kanban, vinculando suas issues e milestones. Muito útil.

GitHub Projects kanban

Commits

Novamente, não há uma regra para isto, mas existem algumas boas práticas. Algumas delas podem ser encontradas neste post (em inglês).

Uma das dicas é sempre ter uma linha inicial com até 50 caracteres, mesmo quando fazendo um commit no terminal. É bom deixar uma linha em branco entre essa primeira informação (resumo) e uma descrição mais completa.

git commit -am "Fix the important problem X > X is a very annoying problem that has been with us for a long time. And now it is fixed :)" 

Outra dica legal é começarmos as frases com a primeira letra maiúscula. E para a primeira linha, não finalize com um "." ou "...".

A linguagem para a primeira linha da mensagem do commit (o que seria o resumo do mesmo) deve ser mais imperativa ou informativa, como dizendo o que acontece graças a este commit. Para não ter dúvidas, imagine que está completando a frase "Este commit irá..." (this commit will):

• Fix the problem x

• Add feature y

Outra coisa interessante é não ultrapassar 72 caracteres por linha na parte principal da mensagem (afinal, ela também poderá ser visualizada no terminal).

É muito útil vincular as atividades no github aos seus commits. Para tal, utilize #id. Por exemplo Fix issue #123. Dessa forma, seu commit fica vinculado a issue.

---

Uma última dica seria...conheça o Git antes de se aprofundar realmente no GitHub. Conheça a ferramenta que você usa. O livro Pro Git (free), pode ajudá-lo!

Então, o que achou? Alguma melhoria que gostaria de sugerir? Deixe nos comentários!