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.
//
Busque em todas as páginas da documentação
Um resumo condensado das 25 práticas Git mais importantes para equipes Python - histórico limpo, commits revisáveis e hooks alinhados com CI.
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).
Commit do lockfile: uv.lock (ou poetry.lock) necessário para uv sync --frozen reproduzível em CI - nunca o ignore no git.
IDs de ticket em cada commit: feat(billing): tax line [BILL-42] - cherry-picks para release/* dependem de mensagens rastreáveis.
Squash merge de features para main: Um ticket, um commit no branch de integração quando a política da equipe permite.
Branches de feature de curta duração: Alvo de 1-3 dias; rebase main diariamente para evitar conflitos de lockfile e Alembic.
Corte de release/x.y para trens coordenados: API + worker + migração enviam juntos; novas features entram em main até a tag.
Branch de release aceita apenas correções de bugs: Aplique com proteção de branch durante janelas de congelamento.
Cherry-pick para release/*, nunca mescle main em release/*: Mesclar puxa features não verificadas para o candidato a release.
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.
Mesclar release/* de volta para main após o rollout: Preservar o limite do trem; excluir o branch de release quando concluído.
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.
Backport de cada hotfix: Cherry-pick o SHA da correção para main e abra release/* se ainda estiver ativo.
Nunca force-push em branches compartilhados: O histórico de main, release/*, hotfix/* é evidência de auditoria.
pre-commit espelha CI: ruff check, ruff format, pytest rápido - os mesmos comandos do GitHub Actions (Configuração do Git).
Modelo de PR exige nota de migração: Revisões Alembic precisam de plano de rollback ou estratégia de expandir-contrair.
Proteção de branch exige verificações de status: A política supera o sistema de honra para fluxos de trabalho necessários.
Nunca comite .env ou segredos: Apenas .env.example; produção via injeção de segredo da plataforma.
Não comite .venv/, __pycache__/ ou dist/: Artefatos pertencem a CI/CD, não ao git.
Commits convencionais para automação de changelog: Emparelhe com semantic-release ou script de changelog personalizado se adotado.
Criação de tags restrita: Tags acionam a produção - regras ou função de gerente de release.
Monorepo: documente a estratégia de tags: Uma tag de monorepo vs tags por serviço - escolha uma e documente.
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.
Revise diffs de lockfile em PRs de dependência: Novas dependências transitivas inesperadas são sinais vermelhos na cadeia de suprimentos.
Documente o rollback nas notas de release: Digeitos de imagem, plano de rollback de migração, chave de desativação de feature flag.
Rebase interativo apenas em feat/* privado: --force-with-lease antes da revisão do PR; nunca em branches compartilhados.
A maioria das equipes de serviço Python usa trunk + release/hotfix - mais simples que develop de longa duração, a menos que a organização exija GitFlow.
Aplique o ID do ticket e o modo imperativo; tipo/escopo convencional quando a automação de changelog depende disso.
Auto-merge de atualizações de patch quando CI verde; minor/major precisa de revisão humana do diff do lockfile.
Siga Git para Dados/Notebooks - nbstripout obrigatório.
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+.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026