Keep a Changelog, implementado de verdad
6 min de lectura actualizado el
Keep a Changelog es una convención de una página para un CHANGELOG.md: la versión más reciente
primero, una sección por versión con un número y una fecha ISO, entradas agrupadas bajo seis tipos
(Added, Changed, Deprecated, Removed, Fixed, Security), y una sección Unreleased arriba para
entradas entre lanzamientos. La mayoría de los equipos que la citan implementan unos dos tercios de
ella, y el tercio que dejan caer es el que protege a sus usuarios.
Olivier Lacan publicó Keep a Changelog en 2014 con una frase que ha envejecido mejor que la mayoría de la prosa de software: don’t let your friends dump git logs into changelogs. Diez años después es lo más parecido a un estándar que tiene este rincón del software. Vale la pena leer la fuente en vez de un resumen; esto trata sobre las partes que se dejan caer.
¿Qué pide Keep a Changelog?
Un CHANGELOG.md en la raíz del repo, más reciente primero, con una sección por versión. Cada
versión lleva un número y una fecha ISO, y agrupa sus entradas bajo seis tipos:
| Tipo | Para | Lo que cuesta dejarlo caer |
|---|---|---|
| Added | Funciones nuevas | Nada; nadie deja caer este |
| Changed | Cambios en comportamiento existente | Los lectores descubren un cambio de comportamiento por un error |
| Deprecated | Funciones a punto de eliminarse | Una eliminación se vuelve un incidente en vez de un evento planeado |
| Removed | Funciones eliminadas en este lanzamiento | Nadie distingue una eliminación de un error |
| Fixed | Correcciones de errores | Nada; nadie deja caer este tampoco |
| Security | Vulnerabilidades | La única lectora que lo buscaba no lo encuentra |
Más una sección Unreleased arriba, para que haya dónde poner una entrada en el momento en que se
mergea, y para que cualquiera pueda ver qué viene.
Eso es casi todo. El resto es el razonamiento: las entradas son para humanos, una entrada por cambio, y el archivo es un documento, no un log.
¿Qué partes de Keep a Changelog se dejan caer?
La sección Unreleased, luego cuatro de los seis tipos, Security entre ellos, en ese orden.
Unreleased desaparece primero. Es la sección sin plazo, así que es la que deja de mantenerse,
y una vez que se va, las entradas se escriben en el momento del lanzamiento a partir del historial
de commits. Eso es exactamente el volcado de git log contra el que advierte la especificación desde
el principio, alcanzado gradualmente. Automatización de changelog
trata sobre todo de mantener viva esta sección sin que nadie tenga que recordarlo.
Los seis tipos colapsan en dos. La mayoría de los changelogs reales terminan con Added y Fixed, porque Changed y Deprecated requieren un juicio sobre en qué confiaba alguien. Ese juicio es la parte valiosa. Deprecated en particular es el único tipo que es una promesa sobre el futuro, y dejarlo caer es cómo una eliminación se convierte en un incidente; la mecánica para mantener esa promesa está en cómo deprecar una API.
Security deja de ser separado. Una corrección de seguridad archivada bajo Fixed es invisible para la única lectora que la estaba buscando. Mantenla distinta incluso cuando la corrección sea trivial, y especialmente cuando prefieras no llamar la atención sobre ella.
¿Qué no responde la especificación?
Es un formato de archivo. No dice nada sobre las preguntas que surgen justo después de adoptarla:
- ¿Cómo se entera alguien? Un archivo en un repo llega a colaboradores. No llega a una clienta que nunca ha abierto GitHub.
- ¿Y los productos sin versiones? Un servicio desplegado continuamente no tiene un v4.2.0 para agrupar. La mayoría de los equipos sustituyen con fechas, lo cual funciona, y la especificación ni lo bendice ni lo prohíbe.
- ¿Quién escribe la entrada? La especificación asume que un humano lo hace. No dice cuándo.
- ¿Y las audiencias múltiples? Un archivo sirve a desarrolladores. No sirve el mismo contenido a una administradora no técnica, y reformatearlo a mano para ella es donde empieza la duplicación. Changelog vs. notas de versión es la división que la especificación te deja hacer a ti.
Common Changelog, un fork más estricto de la idea, endurece parte de esto: prohíbe ciertas redacciones de entrada, exige un enlace al cambio, y tiene una opinión clara sobre quién es el lector. Vale la pena leerlo si las partes sueltas de Keep a Changelog son sobre lo que tu equipo sigue discutiendo.
¿Se puede automatizar Keep a Changelog sin volcar git logs?
Sí: deriva el borrador de commits estructurados, ponlo en Unreleased con su tipo prerrellenado, y exige que un humano edite la redacción antes de cortar un lanzamiento. La advertencia de la especificación es sobre el resultado, no sobre la herramienta. Derivar un borrador de commits está bien. Publicar ese borrador sin editar es a lo que se opone.
La máquina se encarga de la recolección y el formato, en lo que es buena. El humano se encarga de la selección y la redacción, en lo que no lo es. Conventional commits cubre la división en dos capas de la que depende esto, y qué tipos de commit se mapean a cuál de las seis categorías de arriba. Nuestra recopilación de herramientas de changelog cubre lo que existe para la mitad de recolección.
¿Dónde deja de ser suficiente Keep a Changelog?
Se detiene en la distribución. Keep a Changelog es una buena respuesta a “cómo debería verse este archivo”. No es una respuesta a “cómo se enteran nuestros usuarios de qué cambió”, porque un archivo Markdown en un repo es una estrategia de distribución que solo funciona si tus usuarios son colaboradores.
Ese es el segundo obstáculo que golpea a la mayoría de los equipos: el archivo está bien, y nadie fuera del equipo lo lee. Resolverlo significa que las entradas tienen que convertirse en datos que se puedan renderizar en otro sitio, lo cual es un problema distinto de formatear un archivo, y la razón por la que ejemplos de changelog recopila páginas públicas de changelog en vez de archivos de repositorio. Cómo convertir esas entradas en algo a lo que la gente vuelve se cubre en cómo construir una página de changelog.
Adopta la especificación de todos modos. Cuesta una tarde, hace tratable el segundo problema, y sigue siendo la mejor página que se ha escrito sobre esto.
FAQ
¿Es Keep a Changelog un estándar? Es una convención de adopción amplia, no la especificación de un organismo de estandarización. Las herramientas (scripts de lanzamiento, linters, parsers) asumen su forma con la frecuencia suficiente como para que seguirla compre compatibilidad.
¿Qué va en la sección Unreleased? Cada entrada de un cambio que se ha mergeado pero no se ha lanzado en una versión numerada. Cuando se corta un lanzamiento, la sección se renombra a la versión y fecha, y una sección Unreleased vacía y nueva va encima.
¿Debería un changelog usar versionado semántico? Keep a Changelog lo recomienda y no lo exige. Las bibliotecas y APIs se benefician; un servicio desplegado continuamente suele sustituir con fechas, algo que el formato acomoda.
¿Deberían las correcciones de seguridad estar en el changelog antes de ser públicas? Añade la entrada cuando se lanza la corrección, con suficiente detalle para que una operadora actúe y no más. Retrasar la entrada hasta una fecha de divulgación coordinada es normal; omitirla no lo es.
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.