Contribuindo com Projetos Open Source

Para quem está começando à descobrir o incrível mundo do código aberto (open source), quer ser relevante e contribuir de alguma forma mas, não sabe por onde começar.

Neste tutorial, eu tento passar de forma simples os mecanismos básicos para um bom PR (pull request).

Alguns pontos importantes devem ser levados em consideração:

Ambiente Git;
Conta no Github;
Conhecer e curtir a proposta do projeto;
Fork Clone Branch Add Commit Push PR;
Sincronizar o fork.

Este tutorial vai ser focado nos pontos 3, 4 e 5. Os dois primeiros são pré requisitos para os seguintes, mas não serão os pontos-chave.

Conhecer e curtir a proposta do projeto

Antes de tudo, é legal se identificar com a ideia do projeto, gosto de pensar que "sempre curti utilizar as ferramentas A, B ou C. Vi que elas têm código aberto, vai ser massa contribuir!". Até nos repositórios mais simples, é sempre bom estar em harmonia com a finalidade do projeto e gostar de ajudar.

Outro ponto importantíssimo é ler a documentação e os guias de contribuição, cada repositório tem seus guidelines, how do I contribute?, contributing.md... Então, antes de sair abrindo PRs, é essencial consultar como o pull request deve ser feito.

Aqui vamos tratar apenas do fluxo básico (caminho feliz).

Fork Clone Branch Add Commit Push PR

Estas são as etapas básicas para trabalhar com repositórios, que vai desde a duplicação, modificação até a solicitação de alterações no código original.

Fork

Escolhido o repositório, é hora de fazer o seu Fork!

Um fork/bifurcação nada mais é que uma cópia de um repositório, logo é possível trabalhar e fazer alterações em um repositório bifurcado ("forkado" hahahaha), sem que estas mudanças altere o repo original diretamente.

Feito o fork, haverá um novo repositório criado a partir do original.

É hora de clonar este novo repo!

Clone

Para trabalhar localmente no projeto, é necessário cloná-lo para o seu ambiente (É possível fazer alterações diretamente no browser pelo github, na maioria das vezes não é tão recomendado).

Dentre as opções, dá para clonar via HTTP, SSH ou GitHub CLI. Escrevi um outro material sobre como criar e vincular chaves ssh com o github.

Clone via ssh:

gustavo@linux:~$ git clone <link-repo-fork>

gustavo@linux:~$ git clone git@github.com:gfda/gfda.git

Branch

Geralmente, em projetos compartilhados, alterações de código não são feitas diretamente na branch principal (main). Então, uma boa prática é criar uma branch(ramificação) específica para receber as mudanças. Cada projeto tem suas regras para criação, padrões de nomenclatura, uso de branchs... Isto reforça a necessidade de estar em sincronia com os guias do repo.

Para entender mais sobre branches, fica o link da documentação do git.

Criando a branch:

gustavo@linux:~$ git branch <nome-da-nova-branch>

Mudando para branch:

gustavo@linux:~$ git chcekout <nome-da-nova-branch>

Dica:
É possível combinar os dois comandos acima em um único comando git.

gustavo@linux:~$ git checkout -b <nome-da-nova-branch>

Add -> Commit -> Push -> PULL REQUEST

Já na nova branch, é hora de trabalhar no código!

Cada repositório tem suas regras de commits (ressalto a importância de ler a documentação), mas não é uma boa prática ter grandes mudanças em um único commit/PR. Muitos projetos adotam um pull request por commit, então se houver a necessidade de grande alteração de código, quebrar em commits menores (separando por lógica) facilita para quem vai revisar e aumenta as chances de ser aceito.

Após a inserção do novo código, deve ser feita a sequência para aplicar tais mudanças.

Adicionar o(s) arquivo(s) modificado(s) (Add), Commit com mensagem que sintetize, de forma clara, a mudança.
Por último, é hora de enviar as alterações para o repo remoto (push).

gustavo@linux:~$ git add <arquivo(s) alterado(s)>

gustavo@linux:~$ git commit -m <Mensagem da mudança>

gustavo@linux:~$ git push origin <nome-da-nova-branch>

Já no GitHub, a alteração será reconhecida e irá trazer a opção de comparar e abrir o PR (pull request).

Para mais detalhes sobre o Pull Request.

Sincronizar o fork

Agora que já fez o pull request (e ele foi aceito! :D), sabendo que já curtiu a proposta do projeto, é interessante manter o fork sincronizado com as atualizações do repositório principal.

O primeiro passo é adicionar o repo principal, com um nome diferente do fork (após clonar o fork com git clone, o repositório remoto é nomeado de origin), é comum nomear como upstream.

gustavo@linux:~$ git remote add upstream <link-repo-principal>

Então, basta sincronizar o repo local/fork com o principal:

gustavo@linux:~$ git fetch upstream

E, por fim, fazer o merge entre as branchs:

gustavo@linux:~$ git merge upstream/<branch-principal>

É ISTO!

Dica

Já tá rolando a contagem regressiva para o hacktoberfest 2021.

Autor

Gustavo Dias A.

Blog