Changelog: qué es, con un ejemplo de entrada

Un changelog es el registro fechado de lo que cambió en un producto, escrito para las personas a quienes afecta el cambio, no para el equipo que lo lanzó. Cada entrada nombra un cambio, dice cuándo entró en vigor y dice qué debe hacer la lectora al respecto, que en la mayoría de las entradas es nada. Esa última parte es lo que separa un changelog de un registro de commits: un registro de commits es para quienes escribieron el código, y un changelog es para quienes lo usan.

¿Qué es un changelog, exactamente?

Una lista de entradas fechadas, la más reciente primero, cada una describe un solo cambio en términos que la lectora puede comprobar. No lo que el equipo construyó, sino lo que ahora es distinto. “Refactorizado el servicio de facturación” es un mensaje de commit. “Las facturas ahora muestran el impuesto como una línea separada” es una entrada de changelog, porque le dice a la lectora algo que puede verificar en su propia cuenta.

El formato es antiguo y deliberadamente sencillo: un encabezado por lanzamiento o por día, una lista corta debajo, a veces una etiqueta de categoría. Keep a Changelog es la especificación más citada para esta forma, y existe porque la mayoría de los proyectos que se saltan una especificación acaban volcando su historial de commits en su lugar, lo que responde a una pregunta distinta de la que trajo la lectora.

Los cinco se solapan en la práctica, pero no son el mismo documento, y la diferencia está en quién lo tiene en la mano cuando lo lee. Un changelog es el que está construido para buscarse y enlazarse después, por lo que sus entradas necesitan fechas y URLs estables más que los otros.

¿Qué contiene realmente una entrada de changelog?

Cuatro cosas, en este orden: qué cambió, expresado en términos de lo que la usuaria o el cliente que llama notaría; cuándo entró en vigor; a qué categoría pertenece (added, fixed, changed, removed son las cuatro habituales); y, cuando importa, qué tiene que hacer la lectora al respecto. Un enlace a más detalle es bienvenido. Un párrafo de justificación interna no lo es, porque la lectora no preguntó por qué, preguntó qué.

## 2026-09-07

### Added
- Las facturas ahora muestran el impuesto como una línea separada, en la
  moneda de la cuenta del cliente.

### Fixed
- Exportar un informe como CSV ya no descarta la última fila cuando el
  informe supera las 10.000 filas.

Esa forma escala desde una actualización de dos líneas hasta cien entradas en un lanzamiento sin cambiar de estructura, y esa es la verdadera prueba de si un formato funciona: si se lee igual en una semana cargada que en una tranquila.

¿Quién escribe un changelog, y cuándo?

Quien hizo el cambio, en el momento de lanzarlo, no una redactora técnica reconstruyéndolo a partir de tickets una semana después. Quien tocó el código sabe qué cambió realmente para la usuaria; un resumen escrito después tiende a describir el ticket en lugar de lo que realmente se lanzó, y eso suele ser más amplio o más estrecho que el alcance real. Algunos equipos añaden un paso de revisión antes de publicar una entrada, sobre todo para atrapar lenguaje interno que se haya colado, y esa revisión debería ser lo bastante rápida como para que la entrada se publique el mismo día.

¿Dónde debería vivir un changelog?

En su propia página, con una URL estable, distribuido como feed. Enterrado en un menú de configuración o en una etiqueta de release en un alojador de código, solo llega a quienes ya sabían dónde buscar. Una página pública se puede enlazar desde un ticket de soporte, citar en una reseña o suscribir. El feed importa tanto como la página: una lectora que revisa el changelog de un producto una vez al mes es rara, una que se suscribe no lo es, y solo el feed atiende a la segunda.

¿En qué se diferencia de las notas de la versión?

Se confunden constantemente y son lo bastante distintos como para que mezclarlos produzca un documento que no sirve bien a ninguna de las dos lectoras. Changelog vs notas de la versión recorre la distinción completa; en resumen, un changelog es el registro completo y cronológico, y las notas de la versión son un subconjunto curado, escrito para que una actualización suene digna de tener. Un producto suele necesitar ambos, dirigidos a momentos distintos del día de la lectora.

¿Qué hace que un changelog merezca la pena leerse?

Especificidad y honestidad sobre su propio alcance. “Varios arreglos” es la frase que enseña a una lectora a dejar de abrir la página, porque no promete nada que pueda comprobar. Una entrada que nombra el comportamiento exacto que cambió, incluso en un fix pequeño, es la que mantiene una suscripción viva. Esa disciplina también se aplica a lo que se omite: un changelog que solo anuncia logros y nunca un arreglo para algo que estaba roto se lee como marketing disfrazado de changelog, y las lectoras lo notan.

La disciplina de versionado también cuenta. Semantic versioning y tu changelog explica cómo deberían coincidir el número de versión y la entrada, para que una lectora que recorre el historial de versiones reciba la misma señal dos veces en vez de dos distintas.

¿Cómo se generan los changelogs?

De dos formas, y la mayoría de las configuraciones reales son una mezcla. La generación automatizada lee mensajes de commit, normalmente en formato Conventional Commits, y los convierte en entradas sin que nadie toque la salida; de conventional commits a changelog cubre esa canalización. La generación curada significa que alguien escribe o edita cada entrada a mano. La salida automatizada es más rápida y nunca se pierde un pull request fusionado, pero hereda cada mensaje de commit vago tal cual, así que la mayoría de los equipos que automatizan igual mantienen un repaso ligero antes de publicar en lugar de mostrar la salida en bruto.

FAQ

¿Todo producto necesita un changelog? Cualquier producto con usuarias afectadas por el cambio lo necesita, ya sea una app SaaS, una herramienta interna o una API pública. La forma se ajusta (un changelog de API se lee distinto al de una app de consumo), pero la necesidad no.

¿Qué es un changelog en términos de software? La misma definición de arriba: una lista fechada y cronológica de lo que cambió en el software, escrita para quienes lo usan, no para quienes lo construyeron.

¿Se puede generar un changelog automáticamente a partir de commits? Sí, y muchos equipos hacen exactamente eso, normalmente a partir de mensajes en formato Conventional Commits. La contrapartida es que una entrada generada es tan clara como el mensaje de commit del que proviene, así que un repaso antes de publicar atrapa las que necesitan reformularse.

¿Es un changelog lo mismo que un historial de versiones? Lo bastante parecido como para que los términos se usen indistintamente. Un historial de versiones a veces solo es una lista de números y fechas sin descripción; un changelog siempre incluye qué cambió.

Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.

Relacionado en changeloop: Ejemplos de changelog, Documentación para desarrolladores