Diretrizes de Contribuição

Q: Processo de hotfix?

Branch a partir da tag; PR com DoD reduzido; backport para main.

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-review

Quando 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 existentes

O 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-docs obrigató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/fix em 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+.

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-review

Quando 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 existentes

O 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-docs obrigató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/fix em 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+.

Diretrizes de Contribuição

Buscar na documentação

Diretrizes de Contribuição