Cómo escribir notas de versión que la gente realmente lea
6 min de lectura actualizado el
Para escribir notas de versión que la gente lea, responde una pregunta por entrada: qué puede hacer ahora el lector que antes no podía, y qué tiene que hacer al respecto. Pon primero cualquier cosa con fecha límite, nombra a quién afecta, di “no requiere ninguna acción” cuando sea cierto, y omite los lanzamientos que no tienen nada que decir. Todo lo demás en esta página es esa regla aplicada.
Corrección de errores y mejoras de rendimiento.
Todo producto ha publicado esto alguna vez. La causa rara vez es pereza: esto es lo que resulta cuando las notas de versión se escriben desde dentro, por alguien que ha pasado dos semanas metido en el diff y ya no puede ver qué partes le importarían a un desconocido. Un mejor tono no lo arreglará; responder la pregunta sí.
¿Qué deben incluir las notas de versión?
Las notas de versión deben incluir, por cada cambio que merezca mención: qué puede hacer ahora el lector, a quién aplica, qué debe hacer al respecto (incluido “nada”), y cuándo entra en vigor cualquier cosa con fecha límite. No deben incluir números de ticket internos, nombres de componentes que solo usa el equipo, ni un número de versión como único titular.
| Incluir | Dejar fuera |
|---|---|
| El resultado, en los términos del lector | La implementación, en los términos del equipo |
| A quién afecta, por plan, rol o versión de API | “Algunos usuarios” |
| La acción requerida, o “no requiere ninguna acción” | Silencio, que el lector llena con el peor caso |
| Una fecha para cualquier cosa con fecha límite | Un número de versión haciendo de fecha |
| Un enlace a la doc que lo explica | Un enlace al pull request |
| Errores que reportó la gente, y el límite que se subió | Ids de tickets internos |
| La sección aburrida, una línea cada una, al final | La sección aburrida mezclada con las novedades |
La división entre una nota de versión y una entrada de changelog es lo que hace posible esta lista: el changelog lo guarda todo, así que las notas pueden dejar cosas fuera. Los ejemplos de notas de versión reúnen muestras anotadas de cada tipo de entrada.
La pregunta que responde cada entrada
¿Qué puede hacer ahora el lector que antes no podía, y qué tiene que hacer al respecto?
Si una entrada no puede responder eso, pertenece al changelog y no a las notas de versión. Las dos mitades importan. La primera mitad es el valor. La segunda mitad es la que los equipos olvidan, y es la que genera tickets de soporte cuando falta.
Dos ejemplos de la segunda mitad haciendo trabajo real:
- “Los webhooks existentes seguirán funcionando hasta el 1 de noviembre. Después de esa fecha, se rechazarán los payloads sin firmar.”
- “No requiere ninguna acción. Las exportaciones existentes se recodifican automáticamente la próxima vez que las abras.”
La segunda dice “no requiere ninguna acción” explícitamente. Esa frase vale la pena escribirla siempre, porque un lector que no la encuentra asume lo peor.
¿Cómo se deben ordenar las notas de versión?
Ordénalas por consecuencia para el lector, nunca por la parte del sistema que cambió. Agrupar por API, panel, móvil e infraestructura es tu organigrama, no el problema del lector.
- Cambios que rompen algo y cualquier cosa con fecha límite. Primero, siempre, aunque sea pequeño. Si un lector deja de leer tras una línea, esta es la línea que debía haber leído. Si la fecha límite es un sunset, la entrada debería sonar como un aviso de deprecación.
- Lo nuevo que van a querer. Uno por párrafo, con el resultado en la primera cláusula.
- Lo que mejoró. Errores que se reportaron, límites que se subieron, cosas que iban lentas.
- Todo lo demás, como lista. Actualizaciones de dependencias, refactors internos, copy menor. Una línea cada una. Nadie lee esta sección, y aun así debe estar, porque quien la busca realmente la necesita.
La reescritura
Antes:
v4.2.0 Se corrigió un problema donde el endpoint
POST /exportsdevolvía intermitentemente 500 bajo carga. Se refactorizó el worker de exportación. Se subiónode-pga 8.11. Se mejoró el manejo de errores en el serializador de CSV.
Después:
Las exportaciones ya no fallan en cuentas grandes. Las cuentas con más de unas 50.000 filas podían recibir un 500 al iniciar una exportación, más a menudo a fin de mes. Eso está corregido, y las exportaciones de cualquier tamaño ahora se reintentan solas en lugar de fallar. No requiere ninguna acción, y cualquier exportación que falló la última semana puede simplemente volver a ejecutarse.
También en 4.2.0:
node-pg8.11, errores más claros en el serializador de CSV.
Mismo lanzamiento. La segunda nombra la cuenta afectada, el momento en que fue peor, qué cambió, y qué hacer. La actualización de dependencia no desapareció, solo dejó de ser el titular. El artículo buenas prácticas de notas de versión tiene el resto de las reglas que sigue esta reescritura, cada una con lo que cuesta saltársela.
Cosas que vale la pena eliminar
- “Estamos emocionados de anunciar.” El lector aún no está emocionado. Gánatelo en la frase siguiente.
- Números de ticket internos.
PROJ-4471no significa nada fuera de tu tracker. Si la entrada necesita una referencia, enlaza la página de docs. - Nombres de componentes que solo usa tu equipo. Si renombraste el “pipeline de ingesta”, di “importaciones”.
- Un número de versión como único titular.
v4.2.0es una etiqueta de archivo, no un resumen. - Capturas de una página de ajustes que nadie ha visitado. Muestra lo que cambió, en uso.
¿Con qué frecuencia se deben publicar notas de versión?
Publica cuando algo pasó, no según un calendario. Las notas que llegan en cada lanzamiento entrenan a todos a ignorarlas. Las notas que llegan cuando algo pasó se abren. Está bien, y suele ser correcto, publicar un lanzamiento sin ninguna nota y volcar sus entradas en el siguiente conjunto que tenga un titular que valga la pena leer.
El changelog sigue registrándolo todo. Esa es la división del trabajo: el changelog es completo, las notas son selectivas. Si mantienes el changelog estructurado sobre la marcha, escribir las notas es selección y reescritura, no arqueología.
La plantilla de notas de versión es la forma que usamos para el paso de selección, y ejemplos de changelog recopila entradas de equipos cuyo changelog es lo bastante bueno como para derivar notas de él.
Todo esto asume una página que se controla por completo, sin límite de longitud y con enlaces que funcionan. Notas de versión para apps móviles cubre qué cambia cuando la superficie es un listado de App Store o Play Store. Notas de versión de emergencia cubre la otra excepción: qué cambia cuando no queda tiempo para seguir el proceso normal de redacción en absoluto.
Una prueba antes de publicar
Lee las notas como alguien que ha estado de vacaciones dos semanas y tiene 40 segundos. Si en ese tiempo no puede saber si se requiere algo de él, las notas no están terminadas, por muy precisas que sean.
FAQ
¿Cuánto deben durar las notas de versión? Lo que necesiten los cambios con consecuencias, y ni una línea más. Un lanzamiento con un cambio que rompe algo y dos mejoras son tres párrafos. Rellenar un lanzamiento tranquilo para que parezca sustancial es cómo los lectores aprenden a saltarse las notas.
¿Quién debería escribir las notas de versión? La persona que entiende el cambio, editada por alguien que no. La ingeniera sabe qué cambió; la editora sabe qué malinterpretará un desconocido. Escribir la entrada en el momento del merge, mientras la ingeniera aún lo recuerda, es la práctica que hace esto barato.
¿Deben incluir las notas de versión correcciones de errores? Sí, las que alguien reportó o sufrió. Indica el síntoma que vio el lector, no la causa. “Las exportaciones de más de 50.000 filas fallaban” es una corrección que un lector reconoce; “se corrigió una condición de carrera en el worker de exportación” es un mensaje de commit.
¿Cuál es la diferencia entre notas de versión y un changelog? El changelog es el registro completo y continuo; las notas de versión son el mensaje curado sobre un lanzamiento, escrito para gente que aún no ha decidido si le importa. La respuesta más larga está en changelog vs. notas de versión.
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.