Plantilla de release notes

La plantilla

Todo lo que está entre corchetes es un marcador de posición. Todo lo demás merece conservarse, incluido el orden: quien lee busca lo que le afecta, así que los cambios importantes van primero y el trabajo interno no aparece.

## [Producto] [versión] - [fecha]

[Una frase sobre para qué sirve este release. Omítela en releases rutinarios.]

### Cambios importantes
- [Qué deja de funcionar, qué hacer en su lugar y para cuándo.
  Enlaza los pasos de migración.]

### Nuevo
- [Capacidad, descrita como resultado. "Fija un filtro y reutilízalo",
  no "modelo SavedView añadido".]

### Mejorado
- [Qué es más rápido, más claro o más fiable, y aproximadamente cuánto.]

### Corregido
- [El síntoma que vio el usuario, no la causa en el código.]

Si una sección queda vacía, borra el encabezado. Una sección Corregido vacía se lee como si no se hubiera corregido nada, y un encabezado sin contenido hace pensar que la página no ha cargado bien.

La misma plantilla, rellena

Así se ve con contenido real. Fíjate en que ninguna entrada nombra un archivo, una rama, un número de ticket ni una persona, y el cambio importante empieza con la acción que debe tomar quien lee.

## Acme API 4.2 - 20 de agosto de 2026

La paginación ahora usa cursor en todos los endpoints de listado.

### Cambios importantes
- `?page=` se elimina en todos los endpoints de listado. Usa el valor
  `nextCursor` de la respuesta anterior. `?page=` devolverá 400 a
  partir del 1 de octubre de 2026. Pasos de migración:
  acme.example/docs/pagination

### Nuevo
- Vistas guardadas en la bandeja. Fija un filtro una vez y reutilízalo
  desde el lateral.
- Los webhooks ahora pueden limitarse a un solo proyecto.

### Mejorado
- Los endpoints de listado responden unas cuatro veces más rápido en
  cuentas grandes.
- El job de exportación informa del progreso en lugar de parecer colgado.

### Corregido
- Los miembros invitados ya no ven un dashboard vacío antes de su
  primer inicio de sesión.
- Las marcas de tiempo en las exportaciones respetan la zona horaria
  de la cuenta.

Qué va en cada sección

Cambios importantes

La única sección con fecha límite. Di qué deja de funcionar, qué hacer en su lugar y a partir de qué fecha. Si aún no has decidido la fecha, no publiques la sección todavía: un cambio importante sin fecha se lee como urgente, y una racha de urgencia falsa es lo que enseña a la gente a ignorar tus release notes.

Nuevo

Describe el resultado, no lo que construiste. La prueba es si la línea sigue teniendo sentido para alguien que nunca ha visto tu código. «Vistas guardadas en la bandeja» la pasa. «Modelo SavedView y su migración añadidos» no.

Mejorado

Cuantifica cuando puedas hacerlo con honestidad. «Más rápido» casi no vale nada y se descuenta; «unas cuatro veces más rápido en cuentas grandes» merece leerse y marca una expectativa de la que se te puede pedir cuentas. Si no puedes medirlo, di qué es mejor de forma comprobable.

Corregido

Escribe el síntoma, no la causa. La gente busca en estas notas lo que le pasó, así que «los miembros invitados veían un dashboard vacío» es localizable y «corregida una condición de carrera en la caché de membresía» no.

Variantes

Las cuatro secciones sirven para la mayoría de los releases. Tres casos piden un cambio:

• Releases de apps móviles. Las tiendas de apps muestran un campo corto de novedades, así que empieza con una frase legible en la ficha de la tienda y enlaza luego a las notas completas. La revisión de la tienda también puede retrasar un release días, así que fecha las notas por fecha de publicación, no de fusión.
• Releases de API. Versiona las notas igual que versionas la API, y pon la ventana de deprecación en las propias notas, no solo en la documentación. Quien consume una API lee las notas precisamente para saber cuánto tiempo le queda.
• Herramientas internas o de administración. Elimina la sección Mejorado y fusiónala con Corregido. A los usuarios internos les importa si cambió su flujo de trabajo, y una sección larga de Mejorado lo entierra.

Cuatro reglas que las mantienen legibles

1. Escribe para alguien que no conoce tu código. Sin nombres de archivo, sin nombres de rama, sin ids de ticket, sin nombres de servicio, sin nombres en clave internos.
2. Omite todo lo que no tenga efecto visible para el usuario. Los cambios de dependencias, los refactors, los cambios de CI y las correcciones de erratas van en el historial de commits, no en las release notes. La forma más común en que mueren las release notes es llenándose de trabajo que nadie fuera del equipo puede ver.
3. Una entrada, un cambio. Si una línea necesita la palabra «y» dos veces, probablemente son dos entradas.
4. Publica con un ritmo en el que la gente pueda confiar, aunque el ritmo sea «cada vez que publicamos». Unas notas que aparecen cuatro veces en una semana y luego no aparecen en dos meses se toman como ruido.

Formato de las release notes: las partes, en orden

El formato importa menos que el orden. Sea cual sea el estilo de encabezados que uses, quien escanea unas release notes busca las mismas cuatro cosas en la misma secuencia, y todo formato popular es una variación de eso.

1. Un titular que diga qué ha cambiado para quien lee, no el número de versión. La versión va en una línea más pequeña debajo, con la fecha en formato ISO (2026-08-29) para que se lea igual en cualquier idioma.
2. Los cambios importantes y cualquier cosa con fecha límite, primero, aunque sean pequeños. Si alguien deja de leer tras un párrafo, este es el que necesitaba.
3. Qué hay de nuevo, un punto por párrafo, con el resultado en la primera frase y la acción necesaria, incluido «no hace falta ninguna acción», siempre indicada.
4. Correcciones y mejoras, y luego todo lo demás como una lista de una línea al final. Los cambios de dependencias y el trabajo interno se quedan, porque la única persona que los busca de verdad los necesita.

En Markdown eso es un titular H2, una línea atenuada con versión y fecha, y luego secciones H3 para cambios importantes, nuevo, mejorado y corregido. En un correo es el mismo orden con el titular como asunto. En un widget de changelog son el titular y el primer párrafo, con el resto tras un enlace. La plantilla de arriba es esa forma, escrita.

Sobre la redacción en sí, más que sobre la forma, mira Cómo escribir notas de versión que la gente realmente lea y Buenas prácticas de notas de versión que valen la pena en el blog.

Preguntas frecuentes

¿Cuánto deberían medir las release notes?

Lo que midan los cambios que afectan a los usuarios, y ni una línea más. Un release con una corrección de errores se lleva dos líneas. Rellenar un release pequeño para que parezca importante enseña a la gente a pasar por alto los grandes.

¿Cuál es la diferencia entre release notes y un changelog?

En la práctica los términos se usan indistintamente. Donde los equipos sí los distinguen, las release notes describen un único release y se escriben para los usuarios, mientras que un changelog es la lista continua de todos los releases a lo largo del tiempo. Esta plantilla cubre un release; un changelog es lo que obtienes al apilarlos, el más nuevo primero.

¿Deberían las release notes llevar un número de versión?

Solo si tus usuarios pueden verlo. Los números de versión son útiles en APIs, librerías y software instalado, donde alguien necesita saber en qué versión está. En una app web de despliegue continuo, la fecha es más útil, porque es lo que el usuario puede comparar con lo que vivió.

¿Quién debería escribirlas?

Quien sepa qué cambió, que suele ser la persona que lo fusionó, editado por quien cuida el tono. El fallo típico de dárselas por completo a alguien ajeno al trabajo son notas que describen el ticket en vez del cambio.