Ejemplos de notas de versión para cada tipo de cambio
8 min de lectura
Los mejores ejemplos de notas de versión son cortos, nombran a quién afectan y dicen qué hacer a continuación. Abajo hay un ejemplo por cada tipo de cambio que vas a publicar, con la razón por la que funciona, para que copies la forma y pongas tus propios datos.
Todos los ejemplos son inventados, para una app de facturación ficticia llamada Tidepool.
¿Qué tienen en común los buenos ejemplos de notas de versión?
Cuentan a los usuarios qué cambió y qué deben hacer al respecto, si es que deben hacer algo, con las palabras de los usuarios. Cada tipo de cambio tiene un trabajo distinto, así que la forma varía entre ellos.
| Tipo de cambio | La entrada debe decir | Dónde va |
|---|---|---|
| Función nueva | Qué puede hacer ahora el lector y quién la recibe | Arriba de las notas |
| Mejora | Qué se volvió más rápido o más fácil, con una cifra si la tienes | Después de las funciones |
| Corrección de error | El síntoma que vio el lector, y que ya está corregido | Después de las mejoras |
| Cambio incompatible | A quién afecta, la fecha, la migración | Primero, siempre |
| Corrección de seguridad | Qué estuvo expuesto, si se explotó, qué hacer | Primero |
| Deprecación | Qué desaparece, la fecha final, el reemplazo | Cerca de arriba |
| Nota de tienda de apps | Una frase sencilla por cambio, dentro del límite de caracteres | Ficha de la tienda |
| Nota interna | Qué cambió y qué decir a los clientes | Canales de soporte y ventas |
¿Cómo es una buena nota de función nueva?
Una buena nota de función abre con lo que el lector puede hacer ahora y nombra los planes o roles que la reciben. Se salta la implementación.
Envía facturas en el idioma del cliente. Ahora puedes elegir un idioma para cada cliente, y sus facturas, recordatorios y página de pago lo siguen. Francés, alemán, español y portugués están disponibles en todos los planes. Configúralo en la página del cliente, en Preferencias de facturación.
El titular es una frase que el lector diría en voz alta, y el cuerpo da el alcance y el lugar. Un lector que solo ojea la línea en negrita igualmente sabe qué se entregó. El método completo está en cómo escribir notas de versión.
¿Cómo es una buena nota de mejora?
Una nota de mejora describe un cambio que el lector notará, y le pone una cifra medida cuando existe. Sin cifra, di qué ya no tiene que hacer el lector.
La lista de facturas carga unas tres veces más rápido. Las cuentas con más de 5.000 facturas esperaban unos nueve segundos para ver la lista. Ahora se abre en unos tres. No requiere ninguna acción.
“Mejoras de rendimiento” no le dice nada al lector, mientras que nueve segundos frente a tres es una afirmación que puede comprobar el lunes por la mañana. El cierre “No requiere ninguna acción” responde a la pregunta que se hace todo lector.
¿Cómo es una buena nota de corrección de error?
Una nota de corrección describe el síntoma que vio el usuario, no la causa en el código, y dice si tiene que rehacer algo. Las correcciones que nadie notó pueden ir en la lista del final.
Corregido: correos de recordatorio enviados dos veces el día del vencimiento. Algunos clientes recibieron dos recordatorios idénticos si su factura vencía el último día de un mes. Ya está corregido. Los recordatorios ya enviados no se ven afectados, y nadie necesita reenviar nada.
El titular empieza por “Corregido” para que quien ojea pueda clasificarlo de un vistazo, y la condición real (el último día del mes) viene enseguida.
¿Cómo se escriben las notas de versión de un cambio incompatible?
La nota de un cambio incompatible empieza con la fecha y el grupo afectado, y luego da la migración en la misma entrada. Va primero en las notas de versión, porque es la única entrada que el lector no puede perderse.
Las firmas de webhook serán obligatorias el 1 de diciembre de 2026. A partir de esa fecha, Tidepool dejará de enviar payloads de webhook sin firmar. Afecta a quien reciba webhooks sin comprobar el encabezado
Tidepool-Signature. Para migrar, verifica el encabezado con el secreto que está en Ajustes, Desarrolladores. Si ya verificas las firmas, no requiere ninguna acción.
La fecha está en el titular, así que sobrevive a una lectura rápida. El grupo afectado se nombra por lo que hace, y la última frase libera a quienes ya están bien, lo que reduce la carga de soporte. La guía sobre breaking changes explica cómo decidir si un cambio cuenta.
¿Cómo es una nota de corrección de seguridad?
Una nota de seguridad dice qué estuvo expuesto, si alguien lo explotó, a quién afecta y qué deben hacer. Mantenla factual y tranquila.
Seguridad: los enlaces de restablecimiento de contraseña podían reutilizarse. Entre el 3 y el 17 de septiembre de 2026, un enlace de restablecimiento de contraseña seguía siendo válido después de usarse una vez. No encontramos señales de que se explotara. Ya está corregido, y todos los enlaces de restablecimiento pendientes se han invalidado. Si pediste un restablecimiento en ese periodo, solicita un enlace nuevo.
La ventana exacta permite al lector juzgar su propia exposición, y la frase sobre la explotación responde la primera pregunta que todos hacen. “Un posible problema” suena a encubrimiento, así que di lo que sabes.
¿Cómo se escribe un aviso de deprecación?
Un aviso de deprecación nombra lo que se retira, da una fecha final firme y señala el reemplazo.
El endpoint v1 de facturas queda deprecado y termina el 1 de marzo de 2027.
GET /v1/invoicessigue funcionando hasta el 1 de marzo de 2027, y después devuelve410 Gone. UsaGET /v2/invoices, que devuelve los mismos campos máscurrency. Las respuestas de v1 ahora incluyen un encabezadoSunsetcon la fecha final. Hay una guía de migración lado a lado en la documentación.
El nombre del endpoint está en el titular, porque los afectados lo buscan, y el reemplazo queda junto a la retirada. El encabezado Sunset indica a los desarrolladores qué llamadas siguen usando la versión antigua. El tratamiento más largo está en deprecar una API.
¿Cómo es una nota de versión para una tienda de apps?
Una nota de tienda son dos o tres frases sencillas, porque la mayoría solo lee la primera línea. Empieza con el cambio que un usuario notaría.
Escanea un recibo en papel y Tidepool rellena el importe, la fecha y el proveedor. El modo oscuro ahora sigue el ajuste de tu teléfono. También corregimos un cierre inesperado al abrir una factura desde una notificación.
El cambio más útil va primero, y la corrección nombra la situación que fallaba. No hay número de versión ni “corrección de errores y mejoras”. Notas de versión para apps móviles cubre las reglas propias de cada tienda.
¿Qué debe incluir una nota de versión interna?
Una nota interna es la versión para soporte y ventas. Añade lo que la nota pública omite: qué decir y qué evitar prometer.
Las facturas multilingües se publicaron hoy (todos los planes). Soporte: los clientes configuran el idioma en Preferencias de facturación, y las facturas existentes conservan su idioma original. El italiano aún no está disponible. Ventas: está abierto a todos los planes, así que no lo presentéis como una mejora de plan.
Cada audiencia tiene su propia línea etiquetada, y la nota marca el límite (“El italiano aún no está disponible”) antes de que un cliente pregunte. El artículo sobre notas de release internas cubre el formato y los canales.
¿Cómo es una mala nota de versión, reescrita?
Una mala nota lista lo que hizo el equipo en vez de lo que recibe el lector. Se arregla poniendo el resultado al frente y eliminando el vocabulario interno.
Antes:
v3.8.1 Se refactorizó el planificador de recordatorios. Se corrigió una condición de carrera en
ReminderJob. Se actualizóbulla 4.12. Mejoras varias.
Después:
Los correos de recordatorio ya no salen dos veces. Los clientes con una factura que vencía el último día de un mes podían recibir dos recordatorios. Eso está corregido, y los recordatorios ya enviados no hace falta reenviarlos. No requiere ninguna acción.
También en 3.8.1:
bullactualizado a 4.12.
La subida de dependencia pasó a una línea del pie, y la condición de carrera se convirtió en un síntoma que un cliente reconocería.
¿Cómo mantienes la coherencia de las notas de versión entre lanzamientos?
Redacta cada entrada cuando el cambio se fusiona, y haz que una persona la apruebe antes de publicarla.
Changeloop funciona así: redacta una entrada a partir de cada pull request fusionado con IA y la retiene hasta que una persona la apruebe. El paso de aprobación es donde un editor aplica las reglas de arriba. Para fijar primero el formato, parte de la plantilla de notas de versión, y mira los ejemplos de changelog para ver cómo son las páginas terminadas.
FAQ
¿Qué son las notas de versión nuevas? Las notas de versión nuevas son el mensaje que se publica con el último lanzamiento de un producto, y describen qué cambió y qué deben hacer los usuarios. Cubren funciones, mejoras, correcciones y cambios incompatibles.
¿Cuál es la diferencia entre una nota de versión y un changelog? El changelog lo guarda todo, para quien quiera el historial entero. Una nota de versión elige de ahí: un lanzamiento, escrito para los lectores que deciden si les importa. La comparación completa está en changelog vs. notas de versión.
¿Qué significa notas de versión? Las notas de versión cuentan a los usuarios qué cambió en un lanzamiento. La expresión abarca cualquier texto que explique qué se entregó, desde el texto de “Novedades” de una tienda de apps hasta una página en el sitio web de una empresa.
¿Cuánto debe durar cada entrada de las notas de versión? De dos a cuatro frases bastan para la mayoría de las entradas: el resultado, a quién afecta y qué hacer. Un cambio incompatible o una corrección de seguridad pueden ser más largos porque necesitan una fecha o una migració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.