Buenas prácticas de notas de versión que valen la pena

Las buenas prácticas de notas de versión que importan son las que llevan una consecuencia adjunta: escribe la entrada en el momento del merge, nombra a quién afecta, indica la acción requerida aunque sea ninguna, pon fecha a los cambios que rompen algo, mantén una entrada permanente por cambio, agrupa por resultado, y conserva la sección aburrida. Cada una cambia lo que hace el lector. La mayoría del resto de consejos sobre este tema cambian cómo se ven las notas.

Busca buenas prácticas de notas de versión y obtienes consejos de estilo: sé claro, sé conciso, usa lenguaje llano, añade capturas. Nada de eso está mal y nada de eso cambia algo, porque ningún equipo se ha sentado nunca con la intención de ser poco claro. Las prácticas de abajo van acompañadas de lo que cuesta saltárselas, porque una práctica sin un modo de fallo adjunto es solo una preferencia.

¿Cuáles son las buenas prácticas para notas de versión?

Escribe la entrada cuando haces merge, no cuando lanzas. Costo de saltárselo: quien reconstruye el lanzamiento a partir del historial de commits no es quien hizo el cambio, y adivinará la intención. Las entradas escritas dos semanas después son las que dicen “varias mejoras”.

Di a quién afecta, por nombre. “Equipos en el plan Business”, “cualquiera que use la API de exportación v1”, “instalaciones autoalojadas sobre Postgres 14”. Costo de saltárselo: cada lector tiene que averiguar si le aplica, y la mayoría decidirá que no.

Indica la acción requerida, incluido cuando es ninguna. Costo de saltárselo: soporte responde la misma pregunta cuarenta veces, y los lectores que no preguntaron asumen que se requiere algo y lo posponen.

Pon fecha a los cambios que rompen algo, no un número de versión. “Eliminado en v5” no significa nada para quien no sabe cuándo llega v5. “Deja de funcionar el 1 de noviembre” es una fecha que puede anotar en un calendario. Costo de saltárselo: el plazo se descubre después de pasar. Qué cuenta como uno, y la lista de verificación para publicarlo, está en qué es un cambio que rompe algo.

Mantén una entrada permanente y enlazable por cambio. Un correo no es un archivo y un mensaje de Slack no es una referencia. Costo de saltárselo: nadie puede responder “cuándo cambió esto” seis meses después, ni siquiera tú. El correo igual tiene un trabajo, cubierto en la plantilla de email de novedades; apunta a la entrada en vez de reemplazarla.

Agrupa por resultado, no por sistema. Costo de saltárselo: el lector tiene que tener tu arquitectura en la cabeza para saber qué sección le importa. El orden que se sigue de esto está en cómo escribir notas de versión.

Conserva la sección aburrida. Las actualizaciones de dependencias y los cambios internos se quedan, al final, una línea cada una. Costo de saltárselo: el equipo de seguridad, quien revisa cumplimiento y quien depura un desajuste de versión pierden su única fuente. Las entradas que más a menudo se hacen mal son las correcciones; notas de versión de corrección de errores muestra cómo escribirlas para que el lector sepa si debe actuar.

¿Cuáles son las buenas prácticas de changelog, y en qué se diferencian?

Un changelog es una referencia, así que sus prácticas tratan de completitud y estructura, no de persuasión. Las cuatro que importan:

• Un tipo de entrada fijo por línea. Added, Changed, Deprecated, Removed, Fixed, Security. No es un estilo de casa, es un filtro: es lo que permite pedir “solo los cambios que rompen algo”. La convención Keep a Changelog es la fuente habitual.
• Una sección sin publicar. Donde viven las entradas entre el merge y el lanzamiento. Su ausencia es la razón por la que los equipos escriben entradas tarde.
• Fechas ISO. 2026-08-28, no 28/08/26, que significa dos días distintos según el lector.
• Una entrada por cambio, no por commit. Tres commits que corrigen un error son una entrada.

Los dos artefactos se comparan a fondo en changelog vs. notas de versión; la versión corta es que las prácticas del changelog protegen la completitud y las de las notas de versión protegen la atención. Notas de versión privadas para clientas enterprise cubre una versión de esto que solo aparece cuando tus clientas dejan de estar todas en el mismo build: los mismos objetivos de completitud y atención, pero ajustados por cuenta en vez de enviados a todas a la vez.

Tres que son puro culto a la forma

Emojis como tipos de entrada. Un cohete y una llave inglesa no son una taxonomía. Se ven ordenados y no se pueden filtrar, ordenar, ni leer con un lector de pantalla de forma útil. Usa palabras, y si quieres el emoji, ponlo después de la palabra.

Números de versión semántica como titulares para un producto alojado. Semver es una promesa sobre compatibilidad de API. Para un producto SaaS donde nadie elige su versión, un número de versión en el titular es archivo interno disfrazado de noticia. Mantén semver en el changelog y fuera del anuncio.

Publicar en un calendario sin importar el contenido. Notas mensuales sin nada dentro enseñan a la gente que tus notas son ruido. Publica cuando hay algo que decir. El changelog cubre el resto.

La que en verdad es difícil

Mantener el changelog y el anuncio en sincronía, sin escribirlo todo dos veces.

La mayoría de los equipos empiezan con una sola página, la dividen cuando las audiencias divergen, y luego dejan que una de las dos se pudra en silencio, normalmente el changelog, porque es el que no tiene un plazo adjunto. La salida es estructural, no disciplinaria: mantén las entradas como datos con un tipo, una fecha y una audiencia, y trata ambas superficies como representaciones de eso. Nuestra recopilación de herramientas de changelog cubre lo disponible para eso, incluidas las herramientas con las que competimos, y la página alternativa a Beamer es la comparación honesta contra el widget del que parten la mayoría de los equipos.

La plantilla de notas de versión es donde vive el paso de selección una vez que las entradas existen.

Si adoptas una sola cosa

Escribe la entrada en el momento del merge, en un formato fijo, con un tipo. Todas las demás prácticas de esta página se vuelven más fáciles una vez que esa está en su sitio, y ninguna sobrevive sin ella.

FAQ

¿Deben las notas de versión tener capturas de pantalla? Solo de lo que cambió, en uso. Una captura de una página de ajustes que nadie ha visitado añade scroll, no información. Un texto que nombre el resultado y el lector afectado supera a una imagen que no muestra ninguno de los dos.

¿Cómo se escriben notas de versión para un cambio que rompe algo? Primero la fecha, segundo los llamantes afectados, tercero la acción requerida, cuarto la migración. Nunca empieces por el número de versión. La forma completa, con una entrada de ejemplo, está en qué es un cambio que rompe algo.

¿Deberían escribir las notas de versión ingeniería o marketing? Redactadas por quien hizo el cambio, en el momento del merge, y editadas por alguien que las lee como una desconocida. Ninguno de los dos por separado produce notas sobre las que un cliente pueda actuar.

¿Cuál es el formato ideal de notas de versión? Primero los elementos con plazo, luego las capacidades nuevas, luego las mejoras, luego una lista de una línea cada una con el resto. La plantilla de notas de versión es ese formato como página para rellenar.

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: Plantilla de release notes, Herramientas de changelog comparadas