Git Pull Request: Como Contribuir para Qualquer Projeto Open Source

Imagem: Pexels
Você encontrou um erro de digitação no README de uma biblioteca que usa todo dia. Ou escreveu uma função que resolve um problema que o projeto já tinha aberto há meses. O caminho entre "eu conserto isso" e "a correção está no repositório oficial" se chama pull request, e a maioria dos devs nunca aprendeu a usá-lo de forma que o projeto aceite. Este guia cobre o fluxo completo na ordem em que você deve executar: fork, branch, commit, envio e revisão.
1. Leia o CONTRIBUTING antes de escrever uma linha de código
Quase todo projeto sério tem um arquivo CONTRIBUTING.md na raiz. Ele diz coisas que mudam o resultado do seu PR: estilo de commit, se o projeto usa rebase ou merge, quais testes precisam passar, se aceitam PRs de documentação sem issue prévia. Ignorar esse arquivo é o motivo número um de PR fechado sem merge. Leia também as issues abertas: se já existe uma issue discutindo o problema, comente nela antes de codar. Em alguns projetos, PR sem issue correspondente é fechado automaticamente.
2. Fork e clone: por que você não commita no main
O fluxo começa no botão Fork no GitHub, que cria uma cópia do repositório na sua conta. Depois você clona a sua cópia, não a original:
git clone https://github.com/SEU-USUARIO/projeto.git
cd projeto
git remote add upstream https://github.com/ORIGINAL/projeto.git
O remoto upstream aponta para o repositório original e é o que você usa para manter sua cópia atualizada antes de cada contribuição. Nunca trabalhe na branch main do seu fork: crie uma branch com nome descritivo a cada contribuição, como fix-typo-readme ou add-timeout-retry. Branch é descartável; main é para manter limpa.
3. Commits pequenos contam uma história que o revisor consegue ler
Um bom commit do projeto resolve uma coisa só. Mensagens no formato imperativo ("add timeout to fetch") são o padrão da maioria dos projetos open source. Antes de enviar, rode os testes do projeto localmente — não dependa do CI do GitHub para descobrir o óbvio. Se o projeto tem lint, rode o lint. E confira o diff completo com git diff main antes do push: é comum esquecer um print de debug ou um arquivo de configuração pessoal no commit.
4. A descrição do PR é metade do trabalho
Revisores de open source recebem dezenas de PRs por semana. A descrição decide quanto tempo eles dedicam ao seu. Uma estrutura que funciona:
- O que o PR faz: uma frase objetiva ("corrige o cálculo de total quando o carrinho está vazio").
- Por quê: o problema real, com link para a issue se existir.
- Como testei: comandos executados, cenarios cobertos.
- Prints ou trechos: quando a mudança é visual ou muda comportamento visível.
Se a mudança for grande, divida em PRs menores. Um PR de 15 arquivos raramente é revisado de uma vez; três PRs de 5 arquivos têm muito mais chance de entrar.
5. O que acontece depois do envio (e como responder à revisão)
Após o git push, você abre o pull request pela página do repositório e escolhe a branch de destino (normalmente a main do projeto original). O CI do projeto roda automaticamente; se ficar vermelho, corrija antes de chamar a atenção de ninguém. Comentários de revisão aparecem na aba Files changed. Responda cada comentário, mesmo que seja só "feito". Quando pedirem ajustes, faça novos commits na mesma branch e dê git push de novo — não recrie o PR.
6. Erros de iniciante que atrasam ou matam o PR
- Enviar o PR com a branch desatualizada em relação ao upstream: atualize com git fetch upstream e git rebase upstream/main antes do push final.
- Commits de merge poluídos no histórico: prefira rebase na sua branch de contribuição.
- Mexer em formatação junto com mudança funcional: o diff fica gigante e impossível de revisar.
- Desistir na primeira revisão: muitos PRs levam dias para serem revisados; responder cortesmente mantém a conversa viva.
Comece pequeno: documentação, correção de erro de digitação, testes para função sem cobertura. Cada PR aceito é um item de portfólio com link público e prova de que você colabora bem com código de outras pessoas. Se quiser continuar daqui, pratique atualizando sua branch do upstream toda semana, mesmo sem contribuir — o hábito deixa o próximo PR com um diff de duas linhas em vez de duzentas.