Fork, pull requests e issues

Git guarda o histórico, mas é o GitHub que transforma isso em trabalho em equipe. Três recursos formam a base da colaboração: issues, pull requests e forks.

Issues: o registro de tarefas e problemas

Uma issue é uma conversa aberta sobre algo do projeto: um bug, uma ideia, uma dúvida. Uma boa issue tem:

um título claro (“Botão de login não responde no celular”);
uma descrição com o que aconteceu, o que era esperado e como reproduzir o problema;
labels (etiquetas como bug e melhoria) para organizar.

Cada issue ganha um número, como #12, que você pode citar em commits e em pull requests.

Pull requests: propondo mudanças

Um pull request (PR) é um pedido para juntar uma branch a outra, normalmente à main. Em vez de dar merge direto, você abre o PR, e outras pessoas revisam o código, comentam e aprovam antes de a mudança entrar.

O fluxo completo, dentro do mesmo repositório:

git switch -c corrige-botao-login
# ... edita e commita ...
git push -u origin corrige-botao-login

Depois do push, o GitHub mostra um botão para abrir o pull request dessa branch. Na descrição, explique o que mudou e por que. Se o PR resolve uma issue, escreva Closes #12 na descrição: quando o PR for aceito, o GitHub fecha a issue sozinho.

Dica

Prefira pull requests pequenos e focados. Um PR que muda três coisas sem relação entre si é difícil de revisar e demora a ser aprovado. Uma branch e um PR para cada assunto.

Fork: contribuindo com projetos que não são seus

Você não pode dar push direto num repositório que não é seu. Para contribuir, você faz um fork: uma cópia do projeto na sua conta.

Clique em Fork na página do projeto.
Clone o seu fork para o computador.
Crie uma branch, faça as mudanças e dê push no seu fork.
Abra um pull request do seu fork para o projeto original.

Com o tempo, o projeto original evolui e o seu fork fica para trás. Para se manter atualizado, cadastre o original como um segundo remoto, tradicionalmente chamado upstream:

git remote add upstream git@github.com:dono-original/projeto.git
git fetch upstream
git switch main
git merge upstream/main

Dica

Quer começar a contribuir com código aberto? Procure nos projetos as issues marcadas como good first issue: são tarefas pensadas para quem está começando. Corrigir um erro de digitação na documentação já é uma contribuição válida e um ótimo primeiro PR.

Revisão de código

Quando alguém revisa o seu PR e pede mudanças, não abra outro PR: apenas faça novos commits na mesma branch e dê push. O pull request se atualiza sozinho. Encare os comentários como uma conversa sobre o código, não como críticas a você.

Atenção

Mesmo trabalhando sozinho, vale usar branches e pull requests nos seus projetos. Você ganha um histórico organizado e um lugar para revisar as próprias mudanças antes de juntá-las à main.

Exercícios

Exercício

1. Aquecimento. No seu repositório, abra uma issue descrevendo uma melhoria para o projeto, com título claro e descrição. Anote o número que ela recebeu.

Exercício

2. Seu primeiro PR. Crie uma branch, faça uma mudança que resolva aquela issue, envie a branch e abra um pull request com Closes #N na descrição (troque N pelo número da issue). Faça o merge pelo GitHub e confira que a issue foi fechada automaticamente.

Exercício

3. Desafio. Faça um fork de um repositório público de treino (por exemplo, o projeto first-contributions, criado justamente para praticar). Siga o fluxo completo: clone do fork, branch, mudança, push e pull request para o projeto original.