Melhores Práticas do Git

Um resumo condensado das 25 práticas Git mais importantes para equipes Python - histórico limpo, commits revisáveis e hooks alinhados com CI.

1. main é sempre a verdade da integração: Cada PR mesclado passa ruff, pytest e typecheck; nunca deixe main quebrado durante a noite (Comandos Essenciais do Git).

2. Commit do lockfile: uv.lock (ou poetry.lock) necessário para uv sync --frozen reproduzível em CI - nunca o ignore no git.

3. IDs de ticket em cada commit: feat(billing): tax line [BILL-42] - cherry-picks para release/* dependem de mensagens rastreáveis.

4. Squash merge de features para main: Um ticket, um commit no branch de integração quando a política da equipe permite.

5. Branches de feature de curta duração: Alvo de 1-3 dias; rebase main diariamente para evitar conflitos de lockfile e Alembic.

6. Corte de release/x.y para trens coordenados: API + worker + migração enviam juntos; novas features entram em main até a tag.

7. Branch de release aceita apenas correções de bugs: Aplique com proteção de branch durante janelas de congelamento.

8. Cherry-pick para release/*, nunca mescle main em release/*: Mesclar puxa features não verificadas para o candidato a release.

9. Tag de release/* após aprovação de staging: v2.6.0 aciona o pipeline de release; a mensagem da tag lista os implantáveis.

10. Mesclar release/* de volta para main após o rollout: Preservar o limite do trem; excluir o branch de release quando concluído.

11. Branches de hotfix de tags de produção: git checkout -b hotfix/2.5.1 v2.5.0 - não de main quando ele está à frente da produção.

12. Backport de cada hotfix: Cherry-pick o SHA da correção para main e abra release/* se ainda estiver ativo.

13. Nunca force-push em branches compartilhados: O histórico de main, release/*, hotfix/* é evidência de auditoria.

14. pre-commit espelha CI: ruff check, ruff format, pytest rápido - os mesmos comandos do GitHub Actions (Configuração do Git).

15. Modelo de PR exige nota de migração: Revisões Alembic precisam de plano de rollback ou estratégia de expandir-contrair.

16. Proteção de branch exige verificações de status: A política supera o sistema de honra para fluxos de trabalho necessários.

17. Nunca comite .env ou segredos: Apenas .env.example; produção via injeção de segredo da plataforma.

18. Não comite .venv/, __pycache__/ ou dist/: Artefatos pertencem a CI/CD, não ao git.

19. Commits convencionais para automação de changelog: Emparelhe com semantic-release ou script de changelog personalizado se adotado.

20. Criação de tags restrita: Tags acionam a produção - regras ou função de gerente de release.

21. Monorepo: documente a estratégia de tags: Uma tag de monorepo vs tags por serviço - escolha uma e documente.

22. Mudanças de esquema de API + worker vinculadas: A derivação do contrato de evento quebra fluxos assíncronos - um PR ou PRs explicitamente vinculados.

23. Revise diffs de lockfile em PRs de dependência: Novas dependências transitivas inesperadas são sinais vermelhos na cadeia de suprimentos.

24. Documente o rollback nas notas de release: Digeitos de imagem, plano de rollback de migração, chave de desativação de feature flag.

25. Rebase interativo apenas em feat/* privado: --force-with-lease antes da revisão do PR; nunca em branches compartilhados.

FAQs

Relacionados

• Branching & Merging - estratégias
• Checklist de Resolução de Conflitos de Merge - processo de conflito
• GitHub CLI - automação de PR
• Pipelines de CI/CD - portões de fluxo de trabalho

Versões da 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+.