Diretrizes de Contribuição
As diretrizes de contribuição definem como as alterações entram nos repositórios de serviço Python e nesta base de conhecimento SME: nomenclatura de branches, expectativas de PR, regras de revisão e CODEOWNERS - para que a manutenção escale além de um único autor.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
## Modelo de pull request
### Intenção
### Risco (migração/segurança/desempenho)
### Evidência de teste (`uv run pytest path`)
### Plano de rollback
### Links (RFC, ADR, ticket)# CODEOWNERS
/src/billing/ @billing-team
/docs/runbooks/ @sre-oncall
/alembic/ @billing-team @dba-reviewQuando usar isso:
- Open-sourcing de biblioteca interna
- Contribuições externas para o cookbook SME
- Novos engenheiros perguntando "como faço um PR?"
- Auditoria de controle de alterações
Exemplo de Trabalho
# Fluxo de trabalho do contribuidor (interno)
git checkout -b feat/ENG-550-billing-retry
uv sync
uv run pytest tests/billing -q
uv run ruff check .
git commit -m "feat(billing): backoff exponencial em erros transitórios de DB"
git push -u origin feat/ENG-550-billing-retry
# Abrir PR; preencher modelo; solicitar revisão de CODEOWNERS## Contribuição para o cookbook SME (site/python/)
- Um artigo por PR, quando possível
- Frontmatter: tags únicas, slug de seção correto
- Executar `npx tsx scripts/lint-docs.ts`
- Sem travessão; rodapé da pilha na última linha
- Apenas links relativos para páginas existentesO que isso demonstra:
- Portas de qualidade locais antes do PR
- Mensagem de commit vincula o domínio para ferramentas de changelog
- CODEOWNERS solicita automaticamente cobrança + DBA para migrações
- Contribuições de documentação têm etapa de lint explícita
Mergulho Profundo
Como Funciona
- Nomenclatura de branches -
feat/,fix/,chore/+ ID do ticket. - Política de revisão - Aprovação padrão de um; duas para segurança/migrações.
- CI obrigatório - pytest, ruff, pyright (caminhos alterados), build de imagem opcional.
- Estratégia de merge - Squash merge para histórico linear; SHA marcado na implantação.
- Contribuidores externos - Fork PR; bot CLA se open source.
Tipos de Contribuição
| Tipo | Requisito extra |
|---|---|
| Funcionalidade | Link da especificação se M/L |
| Migração | Revisão expandir-contrair |
| Dependência | pip-audit limpo |
| Apenas docs | lint-docs verde |
Notas Python
# Trecho de .github/workflows/ci.yml
- run: uv sync --frozen
- run: uv run pytest
- run: uv run ruff check .Armadilhas
- Merge sem revisão de CODEOWNER - Ignora a expertise. Correção: Regras de proteção de branch.
- PRs gigantes de última hora - Impossíveis de revisar. Correção: Dividir por fatia vertical.
- Pular testes "apenas docs" - Links quebrados são enviados. Correção:
lint-docsobrigatório. - Push direto para main - Aumento do CFR. Correção: Proteger
main; lançar a partir de tags. - Sem nota de rollback - Plantão travado. Correção: Campo de modelo obrigatório para
feat/fixem serviços.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Commit em par baseado em trunk | Equipe sênior pequena | Separação regulamentada de funções |
| Fork mesmo para internos | Estilo open source | Cultura de confiança em monorepo privado |
| Branches de release | Versões de suporte longo | Implantação contínua em main |
| Sem CODEOWNERS | Mantenedor solo | Monorepo multi-equipe |
FAQs
Quem pode aprovar migrações?
CODEOWNER do serviço + grupo de revisores DBA por política.
PRs do Dependabot?
Auto-merge de patch se CI verde; minor revisado semanalmente.
Processo de hotfix?
Branch a partir da tag; PR com DoD reduzido; backport para main.
Contribuir para o cookbook?
Seguir formas de artigos/listas do sme-content; manifestar categoria python.
Commits assinados?
Opcional; obrigatório se a política da organização exigir.
Issue antes do PR?
Encorajado para trabalhos grandes; pequenos correções OK apenas com PR.
Licença para libs OSS?
Apache-2.0 ou MIT por jurídico; arquivo LICENSE obrigatório.
Commits co-autores?
Crédito de pareamento encorajado; ambos revisaram o PR.
Política de PRs obsoletos?
Fechar após 30 dias inativo; autor reabrir quando pronto.
Divulgações de segurança?
Canal privado conforme SECURITY.md; sem issue público para vulnerabilidades.
Relacionados
- Cultura de Revisão de Código - normas de revisão
- Convenções de Documentação - PRs de docs
- Governança de Dependências e Cadeia de Suprimentos - PRs de dependências
- Padrões de Codificação e Guias de Estilo - padrões de CI
- Git & GitHub - fluxo de trabalho git
Versões da pilha: 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+.