Versionamento e Changelogs
O versionamento semântico comunica mudanças que quebram a compatibilidade para os consumidores. Changelogs documentam o que mudou entre os lançamentos.
Receita
[project]
version = "1.2.3" # MAJOR.MINOR.PATCH# CHANGELOG.md
## [1.2.3] - 2026-07-09
### Corrigido
- Lidar com lista de faturas vazia na exportaçãoQuando usar isso:
- Publicando bibliotecas consumidas por outras equipes
- Comunicando mudanças que quebram a compatibilidade claramente
- Automatizando lançamentos a partir de tags git
Exemplo Funcional
# Versão dinâmica a partir de tags git (hatchling)
[project]
name = "myapp"
dynamic = ["version"]
[tool.hatch.version]
source = "vcs"
[tool.hatch.build.hooks.vcs]
version-file = "src/myapp/_version.py"# CHANGELOG.md (Formato Keep a Changelog)
# Changelog
## [Unreleased]
### Adicionado
- Endpoint de exportação de faturas em lote
## [1.2.0] - 2026-06-15
### Alterado
- **QUEBRA DE COMPATIBILIDADE:** `Invoice.amount` agora retorna Decimal, não float
### Migração
- Substitua `float(invoice.amount)` por `invoice.amount` (já é Decimal)git tag v1.2.0
uv build # versão lida da tagO que isso demonstra:
- SemVer: quebra de compatibilidade = MAJOR, recurso = MINOR, correção = PATCH
- Versionamento dinâmico lê tags git automaticamente
- Changelog segue o formato Keep a Changelog
- Mudanças que quebram a compatibilidade incluem notas de migração
Mergulho Profundo
Regras do SemVer
| Mudança | Incremento | Exemplo |
|---|---|---|
| Mudança de API que quebra a compatibilidade | MAJOR | 1.0.0 -> 2.0.0 |
| Novo recurso, compatível com versões anteriores | MINOR | 1.0.0 -> 1.1.0 |
| Correção de bug | PATCH | 1.0.0 -> 1.0.1 |
| Pré-lançamento | sufixo | 1.0.0b1, 1.0.0rc1 |
Armadilhas
- Mudança que quebra a compatibilidade em MINOR - quebra a confiança do consumidor. Correção: incremente MAJOR para qualquer mudança de API que quebre a compatibilidade.
- Nenhuma entrada no changelog - os consumidores não conseguem avaliar o risco de atualização. Correção: atualize o CHANGELOG.md a cada lançamento.
- Versão codificada em múltiplos arquivos - divergência. Correção: fonte única em pyproject.toml ou dinâmica a partir do VCS.
- Confusão com semver 0.x - 0.y.z pode quebrar a qualquer momento. Correção: documente a política de estabilidade; mude para 1.0 quando a API estiver estável.
- Publicando a mesma versão duas vezes - PyPI rejeita. Correção: incremente a versão antes de cada publicação.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| CalVer (2026.07.1) | Lançamentos baseados em data | Biblioteca com expectativas de semver |
| Apenas tags git | Ferramentas internas | Bibliotecas públicas |
| semantic-release (bot) | Changelog automatizado | Processo de lançamento manual preferido |
FAQs
Quando será a versão 1.0.0?
Quando a API pública estiver estável e você se comprometer com a semântica do semver.
Como automatizo as versões?
hatch-vcs, setuptools-scm ou semantic-release a partir de commits convencionais.
CHANGELOG ou GitHub Releases?
Ambos. CHANGELOG no repositório; GitHub Releases para distribuição e notificações.
O que é uma mudança que quebra a compatibilidade?
Remover API pública, alterar assinaturas de função ou alterar comportamento documentado como estável.
Como faço para depreciar?
Aviso na versão N, remover na versão MAJOR N+1. Documentar no changelog.
Versões de pré-lançamento?
1.0.0a1 (alpha), 1.0.0b1 (beta), 1.0.0rc1 (release candidate).
Quem mantém o changelog?
O engenheiro que mescla o PR adiciona uma entrada em [Unreleased].
Como versiono aplicações?
Aplicações podem usar CalVer ou semver. Bibliotecas devem usar semver.
Commits convencionais?
Prefixos feat:, fix:, BREAKING CHANGE: permitem a geração automática de changelog.
Como "despublico" um lançamento ruim?
Yank no PyPI (não apagar). Consumidores que já fixaram a versão não são afetados; novas instalações são bloqueadas.
Relacionados
- Noções Básicas de Empacotamento - versão nos metadados
- Publicando no PyPI - fluxo de trabalho de lançamento
- Melhores Práticas de Empacotamento - política de lançamento
- Entrega Corporativa - processo de lançamento
Versões de Stack: Esta página foi escrita para Python 3.14.0, 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+.