Contribuindo para projetos open source: guia completo

1. Preparação do ambiente e escolha do projeto

Antes de qualquer contribuição, configure o Git corretamente. Defina seu nome e email globalmente:

git config --global user.name "Seu Nome"
git config --global user.email "seu.email@exemplo.com"

Para autenticação segura, gere uma chave SSH:

ssh-keygen -t ed25519 -C "seu.email@exemplo.com"

Adicione a chave pública ao GitHub/GitLab. Para assinar commits com GPG:

gpg --full-generate-key
git config --global user.signingkey <ID_DA_CHAVE>
git config --global commit.gpgsign true

Ao escolher um projeto, verifique:
- Licença (MIT, Apache, GPL)
- Atividade recente (commits dos últimos meses)
- Issues marcadas como good first issue ou help wanted
- Existência de CONTRIBUTING.md e CODE_OF_CONDUCT.md

Faça o fork do repositório desejado e clone localmente:

git clone git@github.com:seu-usuario/nome-do-projeto.git
cd nome-do-projeto

2. Compreendendo o fluxo de trabalho do projeto

Leia atentamente o CONTRIBUTING.md. Ele contém instruções específicas sobre:
- Branch base (geralmente main ou develop)
- Política de branches (feature branches, hotfixes)
- Convenções de commit
- Processo de Pull Request

Identifique a branch principal e configure o remote upstream:

git remote add upstream git@github.com:projeto-original/nome-do-projeto.git
git remote -v

Sincronize seu fork com o repositório original:

git fetch upstream
git checkout main
git rebase upstream/main
git push origin main

3. Criando uma branch de feature a partir da branch base

Crie uma branch descritiva a partir da branch base atualizada:

git checkout -b fix/issue-123 main

Boas práticas de nomenclatura:
- fix/issue-123 — correção de bug
- feat/user-auth — nova funcionalidade
- docs/readme-update — documentação
- refactor/api-endpoint — refatoração

Commits atômicos: cada commit deve representar uma única mudança lógica.

Para trabalhar em múltiplas contribuições simultâneas, use git worktree:

git worktree add ../projeto-feature2 feat/nova-funcionalidade

Isso cria um diretório separado com a branch feat/nova-funcionalidade, permitindo alternar entre contextos sem stashes.

4. Desenvolvimento e versionamento da contribuição

Faça commits frequentes com mensagens claras seguindo a convenção Conventional Commits:

git add arquivo-modificado.py
git commit -m "fix: corrige cálculo de imposto na função calcular_total"

Tipos comuns: feat, fix, docs, style, refactor, test, chore.

Use git add -p para commits parciais:

git add -p

Isso permite revisar cada alteração (hunk) e decidir se adiciona ou não ao staging, garantindo commits focados.

Antes do Pull Request, organize o histórico com rebase interativo:

git rebase -i HEAD~5

No editor, reordene, squash ou edite commits para manter um histórico limpo.

5. Sincronização com o repositório upstream

Mantenha sua branch atualizada com o upstream:

git fetch upstream
git rebase upstream/main

Isso aplica seus commits sobre a versão mais recente do projeto, evitando conflitos no PR.

Se houver conflitos durante o rebase:

git status  # identifica arquivos conflitantes
# Resolva manualmente os conflitos nos arquivos
git add arquivo-resolvido.py
git rebase --continue

Use git mergetool para abrir ferramentas visuais como vimdiff ou meld:

git mergetool

Após resolver, faça push com segurança:

git push --force-with-lease origin fix/issue-123

--force-with-lease protege contra sobrescrita acidental de commits de outros colaboradores.

6. Criação e gerenciamento do Pull Request

Um bom PR contém:
- Título claro seguindo o padrão do projeto (ex: Fix: corrige cálculo de imposto (#123))
- Descrição detalhada: o que foi feito, como testar, referência à issue
- Checklist de tarefas (se o projeto usar templates)

Exemplo de descrição:

## Descrição
Corrige o cálculo de imposto na função calcular_total, que estava ignorando o desconto progressivo.

## Como testar
1. Execute `npm test`
2. Verifique o cenário de imposto com renda acima de R$ 5.000

## Issue relacionada
Closes #123

Adicione revisores e labels apropriados (bug, needs-review).

Ao receber feedback, faça novos commits na mesma branch:

git add correcao.py
git commit -m "fix: ajusta validação conforme revisão"
git push origin fix/issue-123

Para squash antes do merge:

git rebase -i HEAD~3
# Marque os commits como "squash"
git push --force-with-lease origin fix/issue-123

7. Ciclo de revisão e merge

Durante revisões, use git commit --fixup para commits de correção:

git add arquivo-corrigido.py
git commit --fixup <hash-do-commit-original>

Depois, organize tudo com autosquash:

git rebase -i --autosquash HEAD~5

Isso automaticamente marca os fixup commits para serem squashados nos commits originais.

Estratégias de merge comuns:
- Squash merge: Projetos que preferem histórico linear (um commit por PR)
- Rebase merge: Mantém commits individuais sem merge commit
- Merge commit: Preserva todo o histórico de branches

Consulte o CONTRIBUTING.md para saber qual estratégia o projeto utiliza.

8. Manutenção pós-contribuição e boas práticas contínuas

Após o merge do PR, sincronize seu fork:

git checkout main
git fetch upstream
git rebase upstream/main
git push origin main

Limpe branches locais e remotas já mescladas:

git branch -d fix/issue-123
git push origin --delete fix/issue-123

Para limpeza global:

git branch --merged | grep -v "\*" | xargs -n 1 git branch -d
git remote prune origin

Mantenha um histórico organizado:
- Sempre trabalhe em branches separadas
- Nunca commite diretamente em main
- Mantenha seu fork sincronizado semanalmente
- Use git stash para mudanças temporárias

Com essas práticas, você estará preparado para contribuir de forma profissional e consistente em qualquer projeto open source.

Referências