Tags de git, lanzamientos y tu changelog
5 min de lectura
Un tag de git, un lanzamiento y una entrada de changelog son tres registros distintos del mismo evento, y confundirlos hace que un changelog se desvíe en silencio de lo que realmente se lanzó. Un tag marca un commit. Un lanzamiento empaqueta ese tag con artefactos y una descripción. Una entrada de changelog explica, en términos que puede usar una lectora fuera del repositorio, qué cambió. Suelen ocurrir muy cerca en el tiempo, y precisamente por eso es fácil tratarlos como un solo paso en vez de tres, y precisamente por eso la brecha solo se hace visible meses después, cuando alguien pregunta “qué se lanzó en v2.4” y la respuesta honesta requiere excavar de verdad.
¿Cuál es la diferencia real entre los tres?
| Registro | Vive en | Escrito para |
|---|---|---|
| Tag de git | El repositorio, como referencia | Quien haga checkout de ese commit exacto |
| Lanzamiento | El hospedador de código (GitHub, GitLab) | Quien descargue un build |
| Entrada de changelog | El propio changelog del producto | Quien use el producto, no solo el repo |
Un tag es el más mecánico de los tres: git tag v2.4.0 y listo, sin ningún requisito de que algo
explique qué contiene. Un lanzamiento añade una descripción y, normalmente, artefactos
descargables, y su audiencia sigue siendo desarrolladoras que saben qué es una página de
lanzamiento. Una entrada de changelog es el único de los tres escrito para una lectora que quizá
nunca abra el repositorio, por lo que es el que necesita más atención editorial y el más propenso
a saltarse bajo presión de plazos.
¿Necesita cada tag de git una entrada de changelog?
No, y tratarlos como uno a uno es un error habitual. Un tag puede marcar un hito interno, un release candidate, o un hotfix que nunca llega a la mayoría de usuarias; ninguno de esos necesariamente necesita una entrada pública. La prueba es la misma que decide si algo pertenece a un changelog: si una usuaria o quien llama lo notaría o le importaría. La mayoría de tags pasan esa prueba. Algunos, como un tag creado solo para disparar una pipeline de CI, nunca.
¿Necesita cada entrada de changelog su propio tag?
No siempre, y aquí es donde divergen los equipos que despliegan continuamente de los que lanzan paquetes versionados. Un producto SaaS que despliega varias veces al día puede agrupar varios despliegues bajo una entrada de changelog datada sin un tag 1:1 por despliegue; una biblioteca publicada en un registro de paquetes suele necesitar un tag por versión publicada. Los módulos de Go y Swift Package Manager resuelven versiones a partir de los propios tags; en npm o PyPI el registro guarda la versión publicada, y el tag es la forma de relacionar esa versión con su código fuente. Un repositorio con varios paquetes versionados de forma independiente necesita decidir esto por paquete, no una sola vez para todo el repo; changelogs de monorepo cubre cómo deberían dividirse los prefijos de tag y el alcance del changelog según los límites de paquete, no de carpeta. Semantic versioning y tu changelog cubre cómo debería mapearse el número de versión a las categorías de changelog; los tags son el mecanismo que hace verificable un número de versión contra el código real.
¿Cómo debería relacionarse la descripción de un lanzamiento con la entrada de changelog?
Pueden ser el mismo texto, pero solo si la audiencia de ambos es realmente la misma, lo cual es más raro de lo que parece. Una página de lanzamiento en un hospedador de código la leen casi exclusivamente desarrolladoras; si un producto también tiene usuarias no técnicas leyendo el changelog, duplicar la descripción del lanzamiento tal cual envía términos internos y una redacción centrada en código a una lectora que necesitaba la versión en lenguaje llano. El patrón más limpio: escribir la entrada de changelog como el artefacto principal orientado a la lectora, y dejar que la descripción del lanzamiento la enlace o mantenga un resumen más corto y técnico para la audiencia que ya está cómoda ahí.
# Lanzamiento v2.4.0 (GitHub, para desarrolladoras)
Sube el pipeline de informes al nuevo motor de agregación. Ver el
changelog para el resumen orientado al cliente:
https://example.com/changelog#v2.4.0
## 2026-09-07 (Changelog, orientado al cliente)
### Added
- Los informes ahora cargan en menos de un segundo, incluso para
cuentas con más de un millón de filas.El mismo lanzamiento, dos documentos, cada uno con su propia redacción para su propia lectora.
¿De dónde sale realmente la entrada de changelog?
De dos puntos de partida, y la mayoría de pipelines reales son una mezcla de ambos. Puede generarse a partir de mensajes de commit en el momento del tag, lo cual es rápido y nunca se pierde un pull request mergeado; de conventional commits a changelog cubre ese pipeline por completo. O puede escribirse a mano, separada del tag por completo, sincronizada con el momento en que una función se considera terminada en vez del momento en que se mergea el código. Las entradas generadas son consistentes pero heredan cada mensaje de commit vago; las escritas a mano son más claras pero necesitan a alguien que las escriba de verdad. La mayoría de equipos que automatizan igual mantienen un repaso ligero de edición sobre el texto generado antes de que se convierta en la entrada pública, la misma disciplina que recomienda Keep a Changelog, en la práctica, sin importar de dónde venga originalmente el texto en bruto.
¿Qué se rompe cuando los tres se desincronizan?
La confianza en el que la lectora haya consultado primero. Un tag que existe sin entrada de changelog correspondiente parece, desde el lado de quien lee el changelog, que esa semana no pasó nada. Una entrada de changelog sin tag o lanzamiento correspondiente hace imposible que alguien depurando un problema en producción haga checkout del código exacto que estaba en vivo cuando se publicó una entrada. La solución no es automatización perfecta, es una única fuente de verdad para la correspondencia: un lugar, aunque sea solo la propia checklist del proceso de lanzamiento, que diga que un cambio publicable recibe los tres, en el mismo commit o pull request que lo introduce.
FAQ
¿Deberían generarse automáticamente las entradas de changelog a partir de tags de git? Pueden ser un punto de partida, pero un tag solo no lleva ninguna descripción orientada a la lectora, solo un rango de commits. La generación automatizada necesita leer los mensajes de commit dentro de ese rango, no solo la existencia del tag, para producir algo utilizable.
¿Y si no etiquetamos cada lanzamiento? Entonces la entrada de changelog se convierte en el registro principal, y aun así debería llevar una fecha y, si el producto tiene uno, un número de versión, para que la entrada siga siendo algo a lo que una lectora pueda referirse después incluso sin un tag correspondiente.
¿Deberían tener entrada de changelog los tags pre-lanzamiento (como v2.4.0-rc.1)?
En general no. Un release candidate es para pruebas internas o beta, y una entrada de changelog
para él entrena a las lectoras a esperar entradas para versiones que quizá nunca se lancen tal
cual. Reserva las entradas para tags que alcanzan disponibilidad general.
¿Puede una sola entrada de changelog cubrir varios tags de git? Sí, y a menudo debería para equipos que etiquetan con frecuencia. Agrupa tags relacionados bajo una entrada datada que describa el cambio neto, en vez de publicar una entrada delgada por tag que fragmenta una función entre varias lecturas.
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.