guides

Un changelog es un archivo que lista los cambios notables realizados en un proyecto, organizados por versión. Su función es responder a una pregunta sencilla para cualquiera que use tu software o dependa de él: qué cambió entre la versión que tenía y la versión a la que me estoy pasando. Como está escrito para personas y no para máquinas, un buen changelog destaca lo que de verdad importa a los usuarios y deja fuera el ruido.

Conviene aclarar lo que un changelog no es. No es la salida en bruto de tu historial de control de versiones. Un git log lista cada commit, incluidos pequeños refactorizados, correcciones de erratas y commits de fusión, en el orden en que se hicieron y con la redacción que eligió el autor. Un changelog es un resumen curado y escrito por una persona que agrupa el trabajo relacionado, descarta los detalles triviales y describe cada cambio en función de su efecto sobre quien lo lee.

La convención más seguida para escribir uno se llama Keep a Changelog. Establece un formato sencillo basado en Markdown, normalmente en un archivo llamado CHANGELOG.md en la raíz del repositorio. La idea es que una estructura coherente y predecible hace que el archivo sea fácil de ojear, ya sea el lector una persona navegando en un alojamiento de código o una herramienta que analiza las entradas.

El formato Keep a Changelog

Según esa convención, cada versión publicada tiene su propia sección, encabezada por el número de versión y la fecha en que se publicó. Dentro de una versión, los cambios se agrupan bajo un pequeño conjunto de encabezados estándar para que los lectores encuentren rápido lo que les interesa. Los grupos recomendados son Added para nuevas funciones, Changed para cambios de comportamiento existente, Deprecated para funciones en vías de desaparición, Removed para las que ya no están, Fixed para correcciones de errores y Security para todo lo relacionado con vulnerabilidades.

Las versiones en sí suelen seguir el versionado semántico, de modo que una versión se lee MAYOR.MENOR.PARCHE, como 2.4.1. Esto vincula el changelog con el número de versión de forma útil: un lector puede mirar el salto de una versión a la siguiente y hacerse una idea. Un cambio en el número mayor indica que algo puede romperse, mientras que una subida de parche sugiere solo correcciones. El changelog explica luego, con palabras, qué hay exactamente detrás de ese número.

Orden, fechas y la sección Unreleased

Un changelog se mantiene normalmente en orden cronológico inverso, con la versión más reciente arriba, de modo que la información más relevante sea lo primero que ve el lector. Cada entrada está fechada, lo que permite situar una publicación en el tiempo y entender cuán reciente es una corrección o una función. Mantener el orden y las fechas coherentes es parte de lo que hace que el archivo resulte fiable de un vistazo.

• Un changelog es un archivo que lista los cambios notables de cada versión, escrito para personas, no el git log en bruto.
• Keep a Changelog es la convención habitual, normalmente un CHANGELOG.md en Markdown en la raíz del repositorio.
• Grupos de cambios estándar: Added, Changed, Deprecated, Removed, Fixed y Security.
• Las versiones suelen seguir el versionado semántico (MAYOR.MENOR.PARCHE), cada una con su fecha de publicación.
• Las entradas van en orden cronológico inverso, a menudo con una sección Unreleased arriba.
• Puedes generar las entradas desde los commits (por ejemplo Conventional Commits), pero un changelog escrito a mano suele ser más claro.

Una adición común y práctica es una sección Unreleased en la parte superior. Ahí es donde registras los cambios a medida que los haces, antes de que estén ligados a un número de versión. Cuando estás listo para publicar una versión, renombras esa sección con el nuevo número, le pones una fecha e inicias un nuevo bloque Unreleased. Este hábito hace que el changelog se escriba mientras el trabajo está fresco, en lugar de reconstruirlo de memoria en el último momento.

Escribir buenas entradas y generarlas

Escribir buenas entradas consiste sobre todo en tener presente al lector. Cada cambio notable debería tener su propia entrada, redactada para que alguien que no conoce las interioridades entienda igualmente el efecto. Conviene describir el resultado para el usuario en lugar de la mecánica del código, evitar la jerga interna y agrupar las ediciones relacionadas en una sola línea clara en vez de una entrada por commit. Los cambios triviales o puramente internos pueden omitirse por completo.

Es posible generar un changelog automáticamente a partir de tu historial de commits, y muchos equipos lo hacen. Enfoques como Conventional Commits piden escribir los mensajes de commit de forma estructurada, por ejemplo prefijándolos con feat o fix, para que una herramienta pueda ordenarlos en los grupos correctos y montar un borrador. Esto puede ahorrar tiempo e imponer coherencia, pero el resultado tiende a leerse como una lista de commits. Un changelog escrito o al menos revisado a mano suele ser más claro, porque una persona puede decidir qué merece mencionarse y redactarlo para su público.

En resumen

En resumen, un changelog es un registro legible de lo que cambió en cada versión de un proyecto, mantenido para las personas que lo usan. La convención Keep a Changelog le da una forma predecible, el versionado semántico da sentido a sus números de versión, y un poco de disciplina, como una sección Unreleased y una entrada por cambio notable, lo mantiene exacto. Ya sea escrito a mano o generado a partir de commits, su valor viene de ser claro, actual y centrado en lo que el lector realmente necesita saber.