Versionado y Changelogs
El versionado semántico comunica los cambios que rompen la compatibilidad a los consumidores. Los changelogs documentan lo que cambió entre lanzamientos.
Receta
[project]
version = "1.2.3" # MAJOR.MINOR.PATCH# CHANGELOG.md
## [1.2.3] - 2026-07-09
### Corregido
- Manejar lista de facturas vacía en la exportaciónCuándo usar esto:
- Al publicar bibliotecas consumidas por otros equipos
- Para comunicar claramente los cambios que rompen la compatibilidad
- Para automatizar lanzamientos a partir de etiquetas git
Ejemplo Funcional
# Versión dinámica a partir de etiquetas 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
## [Sin lanzar]
### Añadido
- Endpoint de exportación de facturas por lotes
## [1.2.0] - 2026-06-15
### Cambiado
- **QUE ROMPE COMPATIBILIDAD:** `Invoice.amount` ahora devuelve Decimal, no float
### Migración
- Reemplazar `float(invoice.amount)` con `invoice.amount` (ya es Decimal)git tag v1.2.0
uv build # la versión se lee de la etiquetaLo que esto demuestra:
- SemVer: breaking = MAJOR, feature = MINOR, fix = PATCH
- El versionado dinámico lee las etiquetas git automáticamente
- El changelog sigue el formato Keep a Changelog
- Los cambios que rompen compatibilidad incluyen notas de migración
Profundización
Reglas de SemVer
| Cambio | Incremento | Ejemplo |
|---|---|---|
| Cambio de API que rompe compatibilidad | MAJOR | 1.0.0 -> 2.0.0 |
| Nueva característica, compatible hacia atrás | MINOR | 1.0.0 -> 1.1.0 |
| Corrección de error | PATCH | 1.0.0 -> 1.0.1 |
| Pre-lanzamiento | sufijo | 1.0.0b1, 1.0.0rc1 |
Errores Comunes
- Cambio que rompe compatibilidad en MINOR - rompe la confianza del consumidor. Solución: incrementar MAJOR para cualquier cambio de API que rompa compatibilidad.
- Sin entrada en el changelog - los consumidores no pueden evaluar el riesgo de actualización. Solución: actualizar CHANGELOG.md con cada lanzamiento.
- Versión codificada en múltiples archivos - inconsistencia. Solución: fuente única en pyproject.toml o dinámica desde VCS.
- Confusión con semver 0.x - 0.y.z puede romper en cualquier momento. Solución: documentar la política de estabilidad; pasar a 1.0 cuando la API sea estable.
- Publicar la misma versión dos veces - PyPI lo rechaza. Solución: incrementar la versión antes de cada publicación.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| CalVer (2026.07.1) | Lanzamientos basados en fecha | Biblioteca con expectativas de semver |
| Solo etiquetas git | Herramientas internas | Bibliotecas públicas |
| semantic-release (bot) | Changelog automatizado | Se prefiere proceso de lanzamiento manual |
Preguntas Frecuentes
¿Cuándo es 1.0.0?
Cuando la API pública es estable y te comprometes con la semántica de semver.
¿Cómo automatizo las versiones?
hatch-vcs, setuptools-scm, o semantic-release a partir de commits convencionales.
¿CHANGELOG o GitHub Releases?
Ambos. CHANGELOG en el repositorio; GitHub Releases para distribución y notificaciones.
¿Qué es un cambio que rompe compatibilidad?
Eliminar una API pública, cambiar firmas de funciones o alterar un comportamiento documentado como estable.
¿Cómo hago una deprecación?
Advertir en la versión N, eliminar en la versión N+1 MAJOR. Documentar en el changelog.
¿Versiones pre-lanzamiento?
1.0.0a1 (alfa), 1.0.0b1 (beta), 1.0.0rc1 (candidato a lanzamiento).
¿Quién mantiene el changelog?
El ingeniero que fusiona el PR añade una entrada bajo [Sin lanzar].
¿Cómo versiono aplicaciones?
Las aplicaciones pueden usar CalVer o semver. Las bibliotecas deben usar semver.
¿Commits convencionales?
Los prefijos feat:, fix:, BREAKING CHANGE: permiten la generación automática de changelogs.
¿Cómo retiro un lanzamiento erróneo?
Yank en PyPI (no eliminar). Los consumidores que ya lo tenían fijado no se ven afectados; las nuevas instalaciones se bloquean.
Relacionado
- Conceptos Básicos de Empaquetado - versión en metadatos
- Publicación en PyPI - flujo de trabajo de lanzamiento
- Mejores Prácticas de Empaquetado - política de lanzamiento
- Entrega Empresarial - proceso de lanzamiento
Versiones de Stack: Esta página fue 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+, y uv 0.6+.