Formatos de archivo de changelog: JSON, YAML o solo Markdown
6 min de lectura
La mayoría de equipos empieza un changelog como archivo Markdown porque es el camino de menor resistencia: legible en el diff de un pull request, legible en GitHub sin renderizar nada, y familiar para cualquiera que haya escrito alguna vez un README. Esa elección funciona bien hasta que algo distinto de una persona necesita leer el archivo, una página, un widget, un resumen por email, y entonces el formato deja de ser gratis. Automatización de changelog cubre el requisito estructural en general, un tipo, una fecha, un cuerpo y un enlace; esto trata de qué formato de archivo entrega realmente esa estructura y qué cuesta llegar ahí con cada uno.
¿Qué tiene de malo un changelog en Markdown simple?
Nada, hasta que algo necesita volver a parsearlo en campos. Un encabezado, una fecha y una lista debajo es trivial de leer para una persona y genuinamente difícil de parsear con fiabilidad, porque Markdown no tiene esquema: la fecha podría estar en el encabezado, en negrita en la primera línea, o directamente ausente en una entrada antigua, y cada una de esas variantes es Markdown válido que una persona lee correctamente y un parser no. Los equipos que automatizan un changelog en Markdown suelen acabar escribiendo un parser a medida basado en regex que se rompe la primera vez que el formato de una entrada se desvía aunque sea ligeramente, lo cual es frecuente, porque nada obliga a la consistencia al escribir.
¿Qué aporta realmente un formato estructurado?
Una garantía de que cada entrada tiene la misma forma, comprobada al escribir la entrada en lugar de adivinada al leerla. Un archivo JSON o YAML con un esquema definido, tipo, fecha, versión, audiencia, cuerpo, enlace, falla de forma ruidosa si falta un campo obligatorio, igual que lo haría una respuesta de API estricta; un archivo Markdown simplemente renderiza lo que haya, correcto o no. Esa diferencia es invisible hasta el día en que un script necesita la fecha de cada entrada para ordenar un feed, y la mitad de las entradas la tienen en un sitio distinto.
# CHANGELOG.yml
- date: 2026-09-05
type: breaking
version: v2
audience: api
body: "POST /invoices now rejects a currency mismatch instead of silently converting."
link: /blog/api-changelog/¿Eso significa que el archivo legible por humanos tiene que desaparecer?
No, e intentar que un archivo YAML o JSON sirva a la vez como lo que una persona lee en un pull request suele ser un error en la dirección contraria: revisar un diff de JSON anidado es peor que revisar una frase en prosa, y una revisora que tiene que parsear mentalmente una estructura de datos para detectar un error de redacción es una revisora que acabará dejando de detectar errores de redacción. Los dos formatos pueden coexistir: los datos estructurados son la fuente de verdad que lee una pipeline de automatización, y un renderizado generado en Markdown o HTML es lo que una persona realmente revisa y lee, producido a partir del archivo estructurado en lugar de mantenido a mano en paralelo.
| Formato | Legible por humanos tal cual | Parseable por máquina sin código a medida | Fallo habitual |
|---|---|---|---|
| Markdown | Sí | No | Forma inconsistente de las entradas rompe parsers ingenuos |
| JSON | Pobre | Sí | Verboso; fácil de editar a mano hacia JSON inválido |
| YAML | Aceptable | Sí | Sensible a espacios; una mala indentación es un error de parseo silencioso, no ruidoso |
¿Qué formato estructurado es realmente más fácil de editar a mano, JSON o YAML?
YAML, para quien escribe entradas a mano en lugar de mediante un generador, porque elimina el comillado y el emparejamiento de llaves que JSON exige para cada cadena y objeto anidado. La contrapartida es que la sensibilidad de YAML a los espacios falla en silencio de una forma en que los desajustes de llaves de JSON normalmente no lo hacen: un parser JSON rechaza directamente una entrada malformada, mientras que un parser YAML puede aceptar un archivo mal indentado y simplemente parsearlo en la estructura equivocada, lo cual es un fallo peor porque nada os dice que ha pasado. Si las entradas solo las escribe siempre un script, esta contrapartida prácticamente desaparece y el parseo más estricto de JSON se convierte en la opción por defecto más segura.
¿Una página de changelog necesita su propio formato estructurado, separado del archivo que la alimenta?
No uno separado, el mismo renderizado de otra forma. Una página de changelog cubre cómo hacer la página misma legible por máquinas mediante un feed JSON y marcado schema.org; ese feed es salida generada, no una segunda fuente de verdad que mantener sincronizada con el archivo subyacente. Mantener datos estructurados a mano en dos sitios, un archivo fuente y el feed de una página, es como los dos acaban divergiendo, así que la decisión de formato de archivo que se toma aquí debería ser la única cosa de la que todo lo demás, página, widget, email, se genera, nunca se copia a mano.
¿Merece la pena el coste de migrar un changelog en Markdown existente a un formato estructurado?
Normalmente solo una vez que la automatización es el objetivo real, no antes. Un proyecto de una sola persona que publica un archivo Markdown en un README de GitHub no tiene una necesidad real de automatización, y convertirlo a YAML no compra nada más que ceremonia. La conversión se paga sola en el momento en que más de un consumidor final, una página, un email de resumen, un feed público, necesita leer los mismos datos, porque ese es exactamente el punto en el que las inconsistencias de un parser de Markdown empiezan a producir salida visiblemente equivocada en lugar de solo ser molestas de mantener.
FAQ
¿Se puede hacer parseable un changelog en Markdown sin cambiar de formato por completo? Parcialmente, con frontmatter: un pequeño bloque YAML al principio de cada entrada (fecha, tipo, versión) junto a un cuerpo en Markdown para la prosa. Esto consigue los campos estructurados que necesita un parser sin forzar toda la entrada a JSON o YAML, y es un término medio razonable para un equipo que aún no está listo para una migración completa.
¿Importa el formato del archivo para el SEO o para cómo posiciona una página de changelog? No directamente. Los buscadores leen la página renderizada, no el archivo fuente, así que el formato del archivo les es invisible; lo que importa para la página en sí es si es legible por máquinas por derecho propio, lo cual es un asunto separado de qué la genera.
¿Debería pasar cada entrada de changelog por el mismo archivo, o se pueden repartir los tipos en varios archivos? Un solo archivo es más simple hasta que el volumen de entradas lo hace incómodo de diferenciar o revisar; dividir por año o por categoría es una válvula de escape razonable en cuanto los diffs de un único archivo se vuelven demasiado grandes para revisar con sensatez, pero añade un paso de fusión antes de que nada, aguas abajo, pueda leer “todas las entradas” como una sola lista.
¿Existe un formato estándar de archivo de changelog, como existe un estándar para RSS? No uno ampliamente adoptado. Keep a Changelog propone una convención en Markdown, y varias herramientas tienen el suyo; un changeset es un archivo Markdown con frontmatter YAML que nombra el paquete y el salto de versión, que es el patrón de frontmatter descrito arriba. Ninguno es un formato que otras herramientas lean de fábrica como los lectores de RSS entienden RSS universalmente.
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.