Checklist de Resolução de Conflitos de Merge

Um processo calmo e repetível para resolver conflitos de merge e rebase do Git em repositórios Python - especialmente pyproject.toml, uv.lock e migrações Alembic.

Como Usar Este Checklist

• Percorra os itens em ordem durante um conflito ativo - não pule direto para a edição de marcadores.
• Um arquivo totalmente resolvido e testado antes de passar para o próximo, quando os conflitos forem grandes.
• Se ficar preso em um arquivo por mais de 30 minutos, pause e pareie - migrações e lockfiles se beneficiam de um segundo revisor.
• Registre o que causou o conflito na descrição do PR para evitar colisões repetidas.

Fase 1 - Estabilizar

1. Confirme o tipo de operação: Saiba se você está em merge, rebase ou cherry-pick - git status mostra o estado atual.
2. Liste os arquivos em conflito: git diff --name-only --diff-filter=U - espere pyproject.toml, uv.lock, alembic/versions/*.py.
3. Aborte se estiver no branch errado: git merge --abort ou git rebase --abort quando você começou na base incorreta.
4. Faça stash de trabalho não relacionado: git stash push -m "pre-conflito" se edições não commitadas se misturarem com a resolução de conflitos.
5. Busque o último remoto: git fetch origin para que você resolva contra o main atual, não uma cópia local desatualizada.

Fase 2 - Entender

6. Leia ambos os lados: Abra o arquivo em conflito - <<<<<<<, =======, >>>>>>> marcam o seu vs. o recebido.
7. Verifique as mensagens de commit: git log --oneline --left-right HEAD...MERGE_HEAD (merge) ou commits recebidos no rebase.
8. Identifique a intenção semântica: O conflito é cosmético (ordem de importação) ou comportamental (versão da dependência, revisão da migração)?
9. Regra do Lockfile: Para uv.lock / poetry.lock - escolha o lado vencedor do pyproject.toml, delete os marcadores de conflito, execute uv lock.
10. Regra de Migração: Para Alembic - nunca duplique IDs de revisão; pode ser necessário alembic merge heads após a resolução.

Fase 3 - Resolver

11. Resolva um arquivo por vez: Remova todos os marcadores de conflito; deixe sintaxe Python/TOML válida.
12. Prefira a política de dependência upstream: Quando em dúvida sobre a versão da biblioteca, alinhe com main, a menos que o ticket exija um aumento.
13. Execute o formatador em Python tocado: uv run ruff format nos arquivos .py resolvidos.
14. Adicione o arquivo resolvido: git add <arquivo> somente quando os marcadores forem totalmente removidos - git diff --check detecta sobras.
15. Continue a operação: git rebase --continue ou complete o commit de merge após todos os arquivos serem adicionados.

Fase 4 - Verificar

16. Sincronize o ambiente: uv sync --frozen deve ter sucesso após a resolução do lockfile.
17. Execute o linter: uv run ruff check .
18. Verifique tipos (se configurado): uv run mypy src/ ou pyright nos pacotes afetados.
19. Testes: uv run pytest -q - testes do módulo mínimo afetado se a suíte completa for lenta.
20. Migrações: uv run alembic upgrade head no banco de dados local quando os arquivos de migração entrarem em conflito.

Fase 5 - Finalizar

21. Revise o tamanho do diff: git diff origin/main...HEAD - garanta que não haja exclusões acidentais do trabalho de outros.
22. Force push com segurança após rebase: git push --force-with-lease apenas no seu branch de feature.
23. Comentário no PR: Anote os arquivos em conflito e como você escolheu as versões - ajuda os revisores a focar.
24. Prevenção de acompanhamento: Divida o ticket ou faça rebase com mais frequência se os mesmos arquivos entrarem em conflito repetidamente.
25. Feche o ciclo com o autor: Se a mudança recebida foi mal compreendida, sincronize com o autor do commit original antes de fazer o merge.

Aplicando o Checklist em Ordem

• Fases 1-2 (1-10): Entender antes de editar evita merges do lado errado que passam nos testes, mas quebram dependências de produção.
• Fases 3-4 (11-20): Verificações de portão capturam lockfiles que analisam, mas fixam versões incompatíveis.
• Fase 5 (21-25): A comunicação reduz conflitos repetidos em arquivos "quentes" como pyproject.toml.

FAQs

Relacionados

• Branching & Merging - quando os conflitos surgem
• Comandos Essenciais do Git - comandos abort/continue
• Resolução de Dependências e Lockfiles - política de lock
• Alembic - merges de migração

Versões do Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.