Gerenciamento de Releases
O gerenciamento de releases coordena quando e como os serviços Python são enviados: regras de versionamento, trens de release, aprovações de mudança e comunicação. Uma boa higiene de release torna o rollback crível e os stakeholders previsíveis.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
# Release: orders-api v2026.07.09
## Artefatos
- Imagem: `orders-api:sha-9f2a1bc` (Python 3.14.0)
- Wheel (lib interna): `acme-billing==2.4.0`
## Migrações
- alembic `20260709_add_tax_code` (expandir, compatível com versões anteriores)
## Rollback
- `kubectl rollout undo` para `sha-7c1b2aa`
- Pausar workers do `billing` se a profundidade da fila > 5k
## Stakeholders
- #releases, macro de suporte atualizadaQuando usar isso:
- Múltiplos times enviam a mesma plataforma semanalmente
- API voltada para o cliente com compromissos de SLA
- Bibliotecas compartilhadas consumidas por muitos serviços internos
- Conformidade exige registros de mudança
Exemplo de Trabalho
"""version_bump.py - automatiza metadados de versão de serviço para notas de release."""
from __future__ import annotations
import subprocess
from dataclasses import dataclass
from datetime import date
@dataclass(frozen=True)
class ReleaseMetadata:
service: str
git_sha: str
python: str
release_date: date
def git_short_sha() -> str:
return subprocess.check_output(["git", "rev-parse", "--short", "HEAD"], text=True).strip()
def build_release_notes(meta: ReleaseMetadata, changes: list[str]) -> str:
lines = [
f"# Release do {meta.service} {meta.release_date.isoformat()}",
f"- Git: `{meta.git_sha}`",
f"- Python: {meta.python}",
"",
"## Mudanças",
]
lines.extend(f"- {c}" for c in changes)
return "\n".join(lines)
if __name__ == "__main__":
meta = ReleaseMetadata("orders-api", git_short_sha(), "3.14.0", date.today())
print(build_release_notes(meta, ["Adicionar campo de código de imposto (nulo)", "Corrigir backoff de retentativa do Celery"]))O que isso demonstra:
- Notas de release vinculam mudanças visíveis ao cliente ao SHA do git
- Risco de migração explicitamente destacado para operadores
- Passos de rollback ao lado das instruções de deploy forward
- Automação reduz erros de copiar e colar em posts de
#releases
Mergulho Profundo
Como Funciona
- Trens de release - Cadência fixa (ex: Ter/Qui) com corte para merge.
- Semver - Bibliotecas usam MAJOR.MINOR.PATCH; mudanças que quebram o comportamento incrementam o major.
- Gerenciamento de mudanças - Revisão do CAB para migrações destrutivas ou dias de bandeira entre serviços.
- Imutabilidade de artefatos - Construa uma vez, promova através de ambientes.
- Comunicação - Macros de suporte e templates de status atualizados antes da promoção para produção.
Tipos de Release
| Tipo | Cadência | Escopo Típico |
|---|---|---|
| Trem Padrão | Semanal | Funcionalidades atrás de flags |
| Hotfix | Ad hoc | Mitigação de SEV |
| Patch de Biblioteca | Automerge Diário | CVE de Segurança |
| Plataforma Principal | Trimestral | Bump de minor do Python |
Notas de Python
# pyproject.toml - versionamento de biblioteca
[project]
name = "acme-billing"
version = "2.4.0"
requires-python = ">=3.13"Armadilhas
:latestflutuante em produção - Ambiguidade de rollback. Correção: Tags imutáveis com SHA; registrar em anotação de deploy.- Notas de release sem seção de migração - Operadores surpreendidos por bloqueios. Correção: IDs de revisão do Alembic obrigatórios nas notas.
- Trem sem corte - Merges arriscados de última hora. Correção: Congelamento de código 24h antes da produção com processo de exceção.
- Python diferente no worker vs API - Bugs sutis de pickle/esquema. Correção: Política de imagem base única por release.
- Pular notificação de stakeholders - Suporte pego de surpresa. Correção: Post de
#releasesé um portão de release, não opcional.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Deploy Contínuo | Flags fortes + canary | Acoplamento pesado de esquema |
| GitOps (Argo CD) | Frota de K8s | Loja apenas com Lambda manual |
| Dark launches | Trocas de modelo de ML | Divulgação regulamentada necessária |
| Branches de longa duração | Modelo de release legado | Equipe moderna de trunk-based |
FAQs
Com que frequência os serviços Python devem lançar?
Diariamente a semanalmente com flags é comum quando as migrações são expandir-contratar e o CFR é baixo.
As bibliotecas seguem o mesmo trem?
As bibliotecas lançam sob demanda; os serviços fixam versões no lockfile por trem.
O que é um capitão de release?
Engenheiro rotativo é responsável pelo checklist, comunicações e go/no-go para aquele trem.
Como lidar com hotfix durante o congelamento?
IC ou capitão de release aprova; documentar exceção no ticket de mudança.
Cadernos devem ser enviados no trem?
Não - jobs em lote e cadernos têm promoção separada com aprovação do proprietário dos dados.
Como versionar APIs internas?
Versionamento de URL ou cabeçalho documentado no changelog; consumidores fixam o SDK do cliente.
E os monorepos?
Tags e notas de release por serviço; um merge pode acionar múltiplos pipelines de deploy.
Como registrar mudanças para auditoria?
Vincular tickets JIRA/Linear nas notas de release; reter artefatos de build por 90+ dias.
Quando atrasar um trem?
Orçamento de erro esgotado, SEV1 aberto, ou teste de carga de migração falhou no staging.
O uv afeta o gerenciamento de releases?
uv acelera CI; o processo de release ainda é controlado por testes, migrações e canary.
Relacionados
- Estratégias de Rollback - quando os trens dão errado
- Ambientes e Promoção de Configuração - caminho de promoção
- Métricas DORA - medir a saúde da entrega
- Pipelines de CI/CD - automação
- Empacotamento e Publicação - releases de biblioteca
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+.