Changelog vs. notas de versión: ¿cuál es la diferencia?

Un changelog es un registro continuo y acumulativo de todo lo que cambió, escrito para alguien que busca algo. Las notas de versión son un mensaje curado sobre un lanzamiento, escrito para alguien que decide si le importa. La diferencia es de audiencia, no de formato, y la mayoría de los equipos necesitan ambos: uno como referencia, otro como anuncio, derivados de las mismas entradas.

La mayoría de los equipos terminan con uno de estos por accidente y el otro por petición. Empiezas con un changelog porque una desarrolladora quiere un registro de lo que se lanzó. Meses después alguien de soporte pregunta por qué los clientes no sabían de una función que lleva viva desde abril, y ahora necesitas notas de versión.

Changelog vs. notas de versión, lado a lado

¿Qué es un changelog?

Un changelog es un registro cronológico, casi completo, de lo que cambió, más reciente primero, con cada entrada tipada (added, changed, deprecated, removed, fixed, security) y fechada. Su lector ya decidió que le importa. Está buscando algo: cuándo cambió un comportamiento, si un error está corregido, qué versión introdujo un flag. La completitud es todo el valor, por lo que la convención Keep a Changelog dedica la mayor parte de su única página a la estructura y casi nada a la prosa.

¿Qué son las notas de versión?

Las notas de versión son un mensaje selectivo, escrito en prosa, sobre un lanzamiento. Su lector aún no ha decidido nada. Está decidiendo si este lanzamiento le importa, y si tiene que hacer algo al respecto. La selección es todo el valor: una nota de versión que lista todo es un changelog con párrafos, y falla al lector de la misma forma en que un changelog que omite cosas falla al suyo. Cómo escribir notas de versión trata sobre la selección y la redacción.

¿Necesitas un changelog y notas de versión?

Necesitas ambos en cuanto tus dos audiencias quieren cosas distintas; hasta entonces, un solo artefacto haciendo ambos trabajos es correcto. Los equipos pequeños publican una sola página /changelog con un párrafo corto encima de cada entrada, y durante un tiempo eso sirve por igual a una desarrolladora buscando una corrección y a una clienta ojeando novedades. Dividir demasiado pronto te da dos cosas que mantener y una de ellas se pudrirá.

La división vale la pena cuando empieza a pasar esto:

• Tus entradas de changelog han crecido párrafos explicativos que las desarrolladoras se saltan.
• O lo contrario: tus anuncios de lanzamiento han empezado a listar actualizaciones de dependencias.
• Soporte está copiando entradas en correos y reescribiéndolas por el camino.
• Alguien pide “solo los cambios que rompen algo” y no puedes filtrarlos.

Ese último es la señal real. Si nadie puede responder “qué cambió que me afecte” sin leerlo todo, tienes un artefacto haciendo dos trabajos mal.

Una fuente, dos vistas

El error es tratarlos como dos documentos. Son dos vistas sobre el mismo conjunto de cambios.

Escribe el changelog sobre la marcha, una entrada por cambio significativo, cada una etiquetada con lo que es: fixed, added, changed, removed, deprecated, security. Mantén las entradas lo bastante cortas para que escribir una no sea una decisión. Luego, en el momento del lanzamiento, las notas de versión son una selección y una reescritura: toma las entradas que le importan a una persona, agrúpalas por lo que le permiten hacer, y pon el motivo arriba.

Esto tiene una consecuencia práctica. Si el changelog es la fuente, necesita ser datos estructurados, no una página mantenida a mano. Una entrada necesita un tipo, una fecha, una versión, y una forma de decir para quién es. Una vez que tiene eso, la página pública, el widget en la app y el feed RSS o JSON son tres representaciones de una sola cosa, y nadie reescribe nada por el camino hasta llegar a una clienta. Un correo de notas de versión puede citar la misma entrada, desde cualquier herramienta que envíe tu correo. Automatización de changelog trata sobre cuál de esos pasos debería poseer una máquina. Ese es todo el argumento para tratar un changelog como un feed en vez de una página. También es, con toda transparencia, lo que construimos, así que léelo como un interés y no como una encuesta neutral.

Si solo tienes tiempo para uno

Escribe el changelog. Es más barato por entrada, es útil el día que lo escribes, y las notas de versión pueden derivarse de él después. Lo contrario no es cierto: no puedes reconstruir un año de cambios a partir de doce correos de anuncio, y la gente te lo va a pedir.

Mantenlo en un formato fijo para que la derivación siga siendo posible. Nuestra página de ejemplos de changelog recopila entradas de equipos que hacen esto bien, y la plantilla de notas de versión es la forma que usamos al convertir un conjunto de entradas en algo que valga la pena enviar.

Una nota sobre los nombres

Nada de esto está estandarizado, y encontrarás “notas de versión” usado para una lista continua y “changelog” usado para un anuncio trimestral. No vale la pena discutir sobre las palabras. Decide cuál de los dos trabajos hace cada uno de tus artefactos, llámalo como ya lo llame tu equipo, y asegúrate de que ninguno esté haciendo los dos en silencio.

En qué superficie acaba el resultado es una decisión aparte, cubierta en cómo construir una página de changelog.

FAQ

¿Es un changelog lo mismo que las notas de versión? No. Un changelog es el registro completo, leído por gente que busca algo; las notas de versión son el anuncio seleccionado, leído por gente que decide si le importa. El mismo cambio aparece en ambos, redactado de forma distinta para cada lector.

¿Se pueden generar notas de versión a partir de un changelog? Sí, y esa es la dirección correcta. Selecciona las entradas que le importarían a una persona, agrúpalas por resultado, reescribe el titular. Lo contrario, reconstruir un changelog a partir de anuncios, pierde todo lo que los anuncios dejaron fuera.

¿Dónde debería vivir un changelog? En algún lugar permanente y enlazable al que el lector pueda llegar sin un repositorio: una página /changelog, un sitio de docs, o un feed que se renderiza en varios sitios. Un CHANGELOG.md solo llega a colaboradores, no a clientes.

¿Debería un changelog incluir cambios internos? Sí, al final, una línea cada uno. El changelog es el registro completo. Las notas de versión también pueden incluirlos, en una breve sección final, siempre que los cambios que un lector notará vayan primero.

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, Plantilla de release notes