Notas de versión de corrección de errores: cómo escribirlas
8 min de lectura
Unas buenas notas de versión de corrección de errores describen lo que el usuario vio fallar, no lo que hizo mal el código. Cada entrada dice a quién afectó, desde cuándo, si la corrección es completa y si el lector tiene que hacer algo, aunque sea solo “no requiere ninguna acción”.
La mayoría de los equipos copia una línea del mensaje de commit. La tabla muestra seis reescrituras, y las secciones siguientes explican las reglas.
| Antes (el mensaje de commit) | Después (el síntoma) |
|---|---|
| Fixed null pointer in export handler | Las exportaciones ya no fallan con “Algo salió mal” cuando un proyecto no tiene etiquetas. Vuelve a ejecutar cualquier exportación que haya fallado desde el 3 de septiembre. |
| Resolved race condition in sync worker | Las ediciones hechas en dos dispositivos con pocos segundos de diferencia ya no se sobrescriben entre sí. No hay nada que hacer. |
| Fix timezone bug | Los informes programados ahora se ejecutan a la hora que fijas. Las cuentas al este de UTC veían informes hasta un día antes desde el 12 de agosto. No requiere ningún cambio. |
| Patched XSS in comment renderer | Corrección de seguridad: un comentario manipulado podía ejecutar un script en el navegador de otro usuario. Actualiza hoy a la 4.2.1. No vimos explotación en nuestros registros. |
| Fixed regression from 4.1.0 | La búsqueda vuelve a funcionar con consultas que contienen un guion. Falló en la 4.1.0 y está corregido en la 4.1.1. |
| Bug fixes and performance improvements | Di cuáles. Mira la última sección. |
¿Cómo se escribe una entrada de corrección de error en las notas de versión?
Empieza con el síntoma en las palabras del usuario, luego a quién afectó y desde cuándo, luego el estado de la corrección y, por último, la acción. Una o dos frases suelen bastar. La causa en el código pertenece al pull request, donde un ingeniero la buscará.
El lector busca una sola cosa: “¿era yo?”. Cuatro partes cubren casi cualquier entrada:
- El síntoma. Lo que apareció en pantalla, en la respuesta de la API o en la factura. Cita el texto del error si lo hubo, porque la gente lo busca.
- El alcance. Qué plan, plataforma, versión de API o forma de los datos. “Cuentas con más de 50.000 filas” se puede comprobar. “Algunos usuarios” no.
- El periodo. Desde qué versión o fecha, para que el lector decida si el resultado raro de ayer fue el error.
- La acción. Volver a ejecutar, volver a sincronizar, actualizar, quitar un workaround, o nada en absoluto.
Si los usuarios construyeron un workaround, la línea de acción es donde les dices que pueden eliminarlo.
¿Cuál es la diferencia entre una nota de versión y un changelog?
Un changelog es el registro completo y continuo de los cambios. Las notas de versión son un mensaje seleccionado y reescrito sobre un lanzamiento, para quien decide si le importa. En cuanto a las correcciones, el changelog lista todas y las notas abren con las que un lector pudo notar.
Una errata en un tooltip pertenece solo al changelog. Un tipo de impuesto equivocado en las facturas pertenece a ambos. La división completa está en changelog vs. notas de versión, y la forma de un buen conjunto de notas está en cómo escribir notas de versión.
Keep a Changelog es una convención útil para el lado del registro. Reserva “Fixed” para cualquier corrección de errores y un encabezado “Security” aparte para las vulnerabilidades, que es la misma división que hace este artículo de cara al lector.
¿Una corrección de error es una actualización?
Sí. Una corrección de error cambia el producto, así que publicar una es una actualización. Bajo el versionado semántico, una corrección compatible hacia atrás es una versión de parche, por ejemplo de la 4.2.0 a la 4.2.1.
Si el lector tiene que hacer algo es otra pregunta, y la nota debe responderla. Una corrección que cambia lo que observa un llamante correcto se acerca a un cambio incompatible, y breaking changes explica dónde está esa línea.
¿Cuándo merece una corrección su propia entrada y cuándo es una corrección menor?
Da a una corrección su propia entrada cuando un usuario pudo notar el error, perder tiempo o datos por su culpa, o construir un workaround a su alrededor. Agrúpala en una lista breve de “Correcciones menores” cuando nadie fuera de tu equipo pudo verla. Júzgala por la experiencia del lector, sea cual sea el tamaño del diff.
| Tiene su propia entrada | Va en la lista de correcciones menores |
|---|---|
| Reportada por un cliente o sufrida por muchos | Fallo cosmético en una pantalla que casi nadie abre |
| Causó resultados erróneos, trabajos fallidos o trabajo perdido | Errata, espaciado, un icono desalineado |
| Requiere una acción del lector | Corrección en una herramienta interna o página de admin |
| Una regresión de un lanzamiento reciente | Fallo visto solo en un entorno de pruebas |
| Afecta a facturación, permisos o datos | Redacción de logs, subidas de dependencias sin efecto para el usuario |
Cada línea del grupo debe seguir diciendo algo: “Se corrigieron algunos problemas de interfaz” es un marcador de posición.
¿Cómo se escribe sobre una regresión?
Nombra la versión que la introdujo, llámala regresión y da la versión que la corrige. Quienes sufrieron el error ya saben que falló, así que una admisión breve y directa les sirve más que una redacción vaga.
Por ejemplo: “Los resultados de búsqueda para consultas con un guion salían vacíos en la 4.1.0. Está corregido en la 4.1.1. Si cambiaste tus consultas para evitar los guiones, puedes volver a las originales.”
“Mayor fiabilidad de la búsqueda” suena a evasiva para quien perdió una tarde por el error. Si la causa aún se está confirmando, dilo, como indica la guía sobre notas de versión de emergencia: que la nota nunca suene más segura de lo que está el equipo.
¿Cómo se anuncia una corrección de seguridad?
Indica la gravedad con claridad, nombra las versiones afectadas y la versión que las corrige, di cuán urgente es actualizar e incluye el identificador CVE si existe. Publica los detalles solo cuando los usuarios puedan actuar sobre una corrección, siguiendo un proceso de divulgación coordinada cuando intervino quien lo reportó.
La secuencia importa: quien lo reporta te avisa en privado, tú publicas la corrección y la nota pública sale cuando los usuarios pueden protegerse. CISA’s coordinated vulnerability disclosure process coordina el reporte, el análisis y la divulgación pública de vulnerabilidades. Las CVE Numbering Authority rules rigen cómo se asignan y publican los registros CVE, y en GitHub un repository security advisory te permite redactar el aviso en privado y solicitar un identificador.
Una entrada de seguridad suele llevar cuatro datos:
- Qué podría hacer un atacante, en una frase y sin una prueba de concepto.
- Las versiones afectadas y la versión que lo corrige.
- Cuán urgente es: “actualiza hoy” o “actualiza en tu próxima versión”.
- Si has visto explotación, y el crédito a quien lo reportó si estuvo de acuerdo.
Deja fuera los pasos del exploit.
¿Qué debe decir una nota sobre la corrección de una pérdida de datos?
Di qué datos se vieron afectados, cómo saber si los tuyos lo estuvieron y si se pueden recuperar. “No requiere ninguna acción” rara vez es cierto aquí, y la primera pregunta del lector es “se han perdido mis datos”.
Una entrada útil da la condición que perdió datos (“borrar una carpeta mientras se ejecutaba una sincronización”), el periodo en el que era posible, una forma de comprobarlo (“abre la Papelera y busca elementos fechados entre el 3 y el 9 de septiembre”) y el camino de recuperación. Si los datos no se pueden recuperar, dilo. Contacta también directamente con los clientes afectados, porque la nota de versión no debería ser el único sitio donde alguien se entera de que sus datos se vieron afectados.
¿Por qué “Corrección de errores y mejoras de rendimiento” es una mala nota?
No le da al lector nada sobre lo que actuar y oculta las correcciones que alguien esperaba. Un cliente que reportó un cierre inesperado no puede saber si está corregido, y uno con un workaround no puede saber si debe quitarlo.
Hay dos alternativas honestas. Si un lanzamiento no tiene nada que un lector pudiera notar, no publiques notas para él y deja que el changelog guarde el registro. Si tiene correcciones, lístalas en los términos del lector:
Antes:
Corrección de errores y mejoras de rendimiento.
Después:
Corregido: la exportación CSV fallaba en proyectos sin etiquetas.
Corregido: el modo oscuro ocultaba el cursor en el cuadro de
comentarios.
Más rápido: el panel abre antes en espacios con más de 100
proyectos.¿De dónde salen las notas de corrección de errores?
Salen del pull request que corrigió el error y del reporte que lo originó. Si las palabras de quien reportó viajan con la corrección, la mitad del síntoma ya está escrita.
Solicitud de función vs bug explica por qué etiquetar bien un reporte decide quién se hace cargo. En Changeloop, un error reportado a través del widget se convierte en un issue de GitHub con la etiqueta bug, y la entrada del changelog se redacta a partir del pull request fusionado y se retiene hasta que una persona la apruebe antes de publicarla. La plantilla de notas de versión te da la misma forma de entrada para escribir a mano: síntoma, alcance, periodo, acción.
FAQ
¿Qué deben incluir las notas de versión de corrección de errores? Cada entrada debe nombrar el síntoma que vio el usuario, a quién afectó, desde qué versión o fecha, si la corrección es completa y qué tiene que hacer el lector, incluido “nada”.
¿Se debe listar cada corrección de error en las notas de versión? No. Lista las que un usuario pudo notar, por las que perdió tiempo o que rodeó con un workaround, y agrupa las correcciones cosméticas o internas en una lista breve de “Correcciones menores”. El changelog conserva cada corrección para quien necesite consultarla.
¿Cómo se escriben las notas de versión de un error que introdujiste tú? Di que fue una regresión, nombra la versión que la introdujo y la que la corrige, e indica a los lectores si pueden quitar algún workaround. Una declaración directa se lee mejor que una redacción suavizada.
¿Cómo se consultan las notas de versión de un producto que usas? Busca una página de changelog o de notas de versión enlazada desde el menú de ayuda, el pie de página o la documentación del producto, o en la pestaña de releases del repositorio en los proyectos de código abierto.
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.