Plantilla de Release Notes

Usa esta plantilla para comunicar qué cambió, por qué importa y qué deben hacer los usuarios. Combínala con la Plantilla de Changelog para el seguimiento continuo y la Plantilla de Checklist Post-Deploy para la verificación.

Resumen

Las release notes son el canal principal de comunicación entre quienes construyen software y quienes lo usan. He publicado releases donde las notas eran un git log --oneline pegado — los tickets de soporte que llegaron después costaron más tiempo del que habría tomado escribir las notas. Las buenas release notes responden tres preguntas: qué cambió, por qué importa y qué debe hacer el lector. Las malas vuelcan la lista de commits y dejan que el usuario lo averigüe.

Esta plantilla cubre:

1. Secciones estructuradas — highlights, breaking changes, nuevas capacidades, fixes, seguridad
2. Adaptación por audiencia — tonos distintos para usuarios, operadores y desarrolladores
3. Instrucciones de upgrade — pasos explícitos, no suposiciones
4. Issues conocidos — transparencia sobre lo que aún no está arreglado
5. Alineación con semver — notas coherentes con el tipo de version bump

Las release notes y el changelog sirven propósitos distintos: el changelog es el histórico continuo mantenido en el repo, mientras que las release notes son un artefacto orientado al usuario escrito para una versión concreta. La mayoría de equipos escribe primero las release notes y luego las vuelca en CHANGELOG.md.

Plantilla

# Release vX.Y.Z — [Título del Release]

**Fecha de Release:** AAAA-MM-DD
**Estado:** [borrador / publicado / obsoleto]

## Highlights
2-3 oraciones resumiendo los cambios más importantes para usuarios.

## Breaking Changes
- **Cambio:** Descripción de qué cambió
- **Impacto:** Quién está afectado y cómo
- **Migración:** Pasos exactos para adaptarse

## Nuevas Capacidades
- **Nombre de capacidad** — descripción corta y link a docs

## Mejoras
- **Área** — qué mejoró y en cuánto

## Bug Fixes
- **Issue #123** — descripción del bug arreglado

## Seguridad
- **CVE-AAAA-NNNN** — severidad y resumen del fix

## Deprecaciones
- **Capacidad X** — se eliminará en vX.Y+2.0; usa Capacidad Y en su lugar

## Instrucciones de Upgrade
1. Paso 1
2. Paso 2
3. Verificar con: `comando para chequear`

## Issues Conocidos
- **Issue #456** — workaround disponible, fix previsto para el siguiente release

## Changelog Completo
Link al diff completo de commits o al archivo changelog.

Ejemplo Completo

# Release v2.5.0 — Export CSV y Mejoras de Rendimiento

**Fecha de Release:** 2026-07-15
**Estado:** publicado

## Highlights
Añadido export CSV para dashboards de analítica y mejorado el tiempo de
carga del dashboard un 40%. Arreglado un bug donde los rangos de fechas que
cruzaban el límite de mes producían exports vacíos.

## Breaking Changes
- **Cambio:** `/api/v1/reports` ahora retorna un objeto `metadata` en lugar de campos planos
- **Impacto:** Cualquier cliente que parsee la respuesta como JSON plano se romperá
- **Migración:** Actualiza el parsing para leer del objeto `metadata`. Ver guía de migración.

## Nuevas Capacidades
- **Export CSV** — exporta cualquier gráfico del dashboard como CSV. Ver [docs](/es/recipes/export-csv-excel/).
- **Filtros Guardados** — guarda y nombra presets de filtros del dashboard para reutilizar.

## Mejoras
- **Tiempo de carga del dashboard** — reducido de 3,2s a 1,9s (p95) con lazy-loading de gráficos
- **Rate limits de API** — aumentados de 100 a 200 req/min para el tier Pro

## Bug Fixes
- **#234** — el export CSV descargaba un archivo vacío cuando el rango cruzaba el límite de mes
- **#231** — los nombres de filtros guardados se truncaban a 20 caracteres
- **#228** — el dashboard crasheaba al cambiar de tabla a gráfico de barras con 0 filas

## Seguridad
- **CVE-2026-1234** — XSS en el renderizado del tooltip del gráfico (Alta). Arreglado
  escapando la entrada del usuario en las plantillas de tooltip.

## Deprecaciones
- **Formato plano de respuesta de `/api/v1/reports`** — se eliminará en v3.0.0. Usa `metadata`.
  Ver [Aviso de Deprecación de API](/es/docs/api-deprecation-notice-template/).

## Instrucciones de Upgrade
1. Actualiza el SDK: `npm install @stackpractices/sdk@2.5.0`
2. Si usas `/api/v1/reports`, actualiza el parsing de respuesta (ver guía de migración)
3. Verifica: `curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/reports | jq .metadata`

## Issues Conocidos
- **#240** — el export CSV falla con gráficos de más de 10.000 filas.
  Workaround: acota el rango de fechas. Fix previsto para v2.5.1.

## Métricas del Release
- Commits: 47 · Contribuidores: 6 · Issues cerrados: 12 · PRs mergeados: 31

## Changelog Completo
https://github.com/example/repo/compare/v2.4.1...v2.5.0

Versiones por Audiencia

Audiencia	Enfoque	Tono
Usuarios finales	Nuevas capacidades y bug fixes que afectan su flujo	Amigable, orientado a beneficios
Operadores	Breaking changes, pasos de upgrade, fixes de seguridad	Preciso, orientado a la acción
Desarrolladores	Cambios de API, deprecaciones, actualizaciones de librerías	Técnico, detallado

No necesitas tres documentos — una sola nota puede servir a las tres audiencias si ordenas las secciones para que cada una encuentre su parte primero. Los breaking changes y las instrucciones de upgrade van delante; los detalles solo para desarrolladores (bumps de dependencias, refactorizaciones internas) pueden quedarse en el changelog enlazado.

El mismo cambio, tres voces

Toma un breaking change — el cambio de formato de respuesta de /api/v1/reports — y fíjate en cómo el mismo hecho aterriza distinto según la audiencia:

• Usuario final: “Los informes ahora incluyen metadatos como la fecha de creación y los filtros usados. No necesitas hacer nada — tus exports siguen funcionando.”
• Operador: “/api/v1/reports retorna un objeto metadata en lugar de campos planos. Actualiza el parsing de respuesta antes de v3.0.0; formato antiguo deprecado, fecha de eliminación abajo.”
• Desarrollador: “GET /api/v1/reports — esquema de respuesta modificado. El objeto metadata envuelve created_at, filters, row_count. Campos planos eliminados en v3.0.0. Guía de migración enlazada.”

Mismo cambio, mismo release — tres puntos de entrada al mismo documento.

Alineación con Semver

Version bump	Cuándo usar	Foco de las release notes
MAJOR (X.0.0)	Breaking changes	Guía de migración, breaking changes primero
MINOR (X.Y.0)	Nueva funcionalidad, backward-compatible	Nuevas capacidades, mejoras
PATCH (X.Y.Z)	Bug fixes, backward-compatible	Bug fixes, parches de seguridad

Un desajuste entre el bump y las notas erosiona la confianza rápido. Si tus notas listan un breaking change, la versión debe ser una MAJOR — publicarlo como PATCH enseña a los usuarios a temer cada actualización.

Lo Que Funciona

• Escribe las release notes antes del release — son un forcing function para la revisión final. Yo he detectado breaking changes sin documentar solo intentando escribir el párrafo de highlights.
• Destaca los breaking changes primero — los usuarios escanean buscando lo que podría romperles.
• Incluye instrucciones de upgrade — incluso para releases “sin acción requerida”, dilo explícitamente.
• Enlaza a documentación — cada nueva capacidad debería tener su página de docs. Usa la Plantilla de Documentación de API como referencia.
• Incluye comandos de verificación — da a los usuarios una forma de confirmar que el upgrade funcionó.
• Fecha cada release — formato ISO 8601 (AAAA-MM-DD) por consistencia.
• Enlaza al diff completo — deja que los desarrolladores profundicen en los commits si quieren.
• Cuantifica las mejoras — “40% más rápido” significa algo; “varias mejoras” no significa nada.
• Mantén un borrador vivo durante el sprint — las entradas escritas al mergear se leen mejor que las reconstruidas en el release.
• Escribe la sección de breaking changes aunque esté vacía — “Ninguno en este release” también es información.

Errores Comunes

• Listar cada commit — a los usuarios no les importa “refactor helper function”.
• Omitir breaking changes — rompe la confianza y causa incidentes. Consulta la Plantilla de Postmortem para los procedimientos de recuperación.
• No dar instrucciones de upgrade — los usuarios pierden tiempo adivinando el camino de migración. Consulta la Plantilla de Guía de Configuración de Entorno para contexto de configuración.
• Saltarse los issues conocidos — la transparencia genera confianza; ocultar problemas la destruye.
• Descripciones vagas como “varias mejoras” — nombra la mejora y cuantifícala.
• Sin enlace a una guía de migración para breaking changes — los usuarios necesitan un camino paso a paso.
• Publicar notas que solo entiende quien las escribió — si la persona de soporte no puede parafrasearlas, reescríbelas.

Del Git Log a la Release Note

Lo difícil no es la plantilla — es convertir commits crudos en algo que le importe al usuario. Así se ve la traducción:

Mensaje de commit	Entrada en release notes
feat(reports): add csv exporter	Export CSV — exporta cualquier gráfico del dashboard como CSV desde el menú de compartir
fix: date boundary bug in export	#234 — el export CSV descargaba un archivo vacío cuando el rango cruzaba el límite de mes
perf: lazy load chart components	Tiempo de carga del dashboard — reducido de 3,2s a 1,9s (p95) con lazy-loading
chore: bump express to 4.21	(omítelo — sin cambio visible para el usuario)
refactor: extract report service	(omítelo — cambio interno)
feat(api)!: wrap response in metadata	Breaking: /api/v1/reports ahora retorna un objeto metadata — actualiza el parsing antes de v3.0.0
fix(security): escape tooltip input	CVE-2026-1234 — XSS en los tooltips del gráfico (Alta); actualiza a v2.5.0

La regla: cada entrada lleva un nombre que el usuario buscaría, un beneficio o síntoma que reconoce, y un número (ID de issue, métrica, versión) que la hace verificable. El trabajo interno se queda en el changelog.

Un triaje práctico: lee el título de cada PR mergeado una vez y etiquétalo como visible para el usuario, interno o requiere migración. Si no puedes decidirlo desde el título, probablemente es interno — o el título del PR necesita reescribirse, lo que es una señal útil para devolver al equipo.

Variantes

Release notes automatizadas (release-please, semantic-release)

Herramientas como release-please y semantic-release generan release notes desde mensajes de commit convencionales. Usa prefijos (feat:, fix:, BREAKING CHANGE:) y la herramienta genera notas categorizadas automáticamente. Revisa y edita el resultado antes de publicar — las notas automatizadas son un punto de partida, no un producto terminado.

Release notes de servicio interno

Para servicios internos, añade contexto de despliegue: qué entornos se actualizaron, procedimiento de rollback, feature flags activados/desactivados y enlaces a dashboards de monitorización. Los operadores necesitan saber qué cambió en su entorno, no solo qué cambió en el código. Una cabecera interna útil añade: Desplegado en: staging 2026-07-14, producción 2026-07-15 · Rollback: revertir image tag a v2.4.1 · Flags: csv-export activado para el tier Pro · Dashboard: enlace al panel de Grafana del release.

Release notes de hotfix

Los hotfix necesitan un formato más corto: “Arreglado [bug] que causaba [síntoma]. Desplegado en [entorno]. Monitorizando [métrica]. Rollback: [comando].” Sin highlights ni nuevas capacidades — solo el fix y el contexto operacional. Uno real suena así: “Arreglado un crash por null-pointer en el checkout cuando un código de descuento expiraba a mitad de sesión. Desplegado en producción a las 14:30 UTC. Monitorizando la tasa de errores del checkout. Rollback: helm rollback checkout 41.”

Cómo Adoptar Esta Plantilla

Empieza pequeño: elige las secciones de la plantilla que aplican a tu próximo release y borra el resto. Una sección “Seguridad” vacía en un patch release no es obligatoria — el esqueleto está pensado para podarse, no para rellenarse a ciegas.

La secuencia que funciona en la práctica:

1. Activa conventional commits en CI (commitlint o un check de título de PR) para que la automatización tenga algo que parsear.
2. Redacta el borrador desde los commits una semana antes del release — release-please lo hace automáticamente; si no, copia el git log y ordena las entradas en las secciones de la plantilla.
3. Asigna un responsable por release: una persona reescribe el borrador para la audiencia objetivo y poda los commits solo internos.
4. Revisa breaking changes y entradas de seguridad con quien posee la superficie afectada — confirman que los pasos de migración realmente funcionan.
5. Publica donde los usuarios miran — GitHub Releases para audiencias de desarrollo, el sitio de docs para operadores, avisos in-app para breaking changes.

Tras dos o tres releases el paso del borrador se colapsa: conventional commits más plantilla hacen que la mayoría de entradas lleguen pre-ordenadas, y el trabajo del responsable se reduce a reescribir highlights y confirmar los pasos de migración.

Un primer mes realista se ve así: semana uno, activa commitlint y copia esta plantilla en el repo; semana dos, publica tus primeras notas con ella — espera que la reescritura lleve una hora; semanas tres y cuatro, ajusta los filtros a medida que se cuelan chore commits y decide qué secciones mantienes.

Troubleshooting

• Nadie lee las release notes: probablemente están escritas para la audiencia equivocada. Pon primero los breaking changes y lo que el lector debe hacer; baja la lista de features. Revisa también dónde viven — un CHANGELOG.md en el repo no llega a usuarios que nunca abren el repositorio.
• Las release notes se retrasan días respecto al release: redacta desde los commits durante el sprint, no después del tag. Si usas release-please, el PR de borrador ya existe — lo que queda es reescribir highlights, cosa de minutos.
• Las notas y GitHub Releases están desincronizados: elige una sola fuente de verdad. Publica primero en la página de Releases o en el sitio de docs y luego vuelca a CHANGELOG.md — nunca mantengas ambos de forma independiente.
• Las notas automatizadas están llenas de chore commits: endurece las reglas de conventional commits en CI para que el trabajo interno use prefijos chore:/ci:/refactor: que el generador filtra.
• Un breaking change se coló en un patch release: reconócelo de inmediato en las notas y en los issues conocidos, publica el camino de migración y ajusta el proceso para que la comprobación de breaking changes ocurra antes de taguear.
• Las notas suenan a documentación interna: llenas de nombres de servicios, IDs de tickets y jerga que los usuarios no conocen. Reescribe cada entrada en torno a lo que el usuario ve en la UI o en la API, y mueve los detalles internos al enlace del changelog.
• Las traducciones se retrasan respecto a las notas en inglés: publica primero en el idioma principal y marca las notas traducidas con la fecha del release — notas traducidas desfasadas que muestran una versión antigua como “última” erosionan la confianza más rápido que la ausencia de traducción.

Checklist del Día de Release

• Release notes redactadas y revisadas para la audiencia objetivo
• Los breaking changes tienen pasos de migración verificados por quien posee la superficie afectada
• Los fixes de seguridad incluyen números CVE y severidad
• Instrucciones de upgrade probadas en un entorno limpio
• El version bump coincide con el contenido de las notas (check de semver)
• Publicado en el canal que los usuarios realmente leen
• Entradas volcadas en CHANGELOG.md
• Issues conocidos listados con workarounds y versión objetivo de fix

Notas de Producción

• Anuncia los breaking changes por más de un canal — las release notes solas no llegan a usuarios que nunca visitan la página de Releases. Los banners in-app y el email funcionan mejor para migraciones.
• Mantén una línea de “sin acción requerida” para releases rutinarios — el silencio hace sospechar que faltan instrucciones, no que no hacen falta.
• Vigila el volumen de soporte tras publicar — un pico de tickets “cómo actualizo” significa que la sección de instrucciones necesita trabajo, no que los usuarios sean descuidados.
• Rota quién escribe las notas — la misma persona tiende a escribir para sí misma. Rotar el autor mantiene el lenguaje honesto.
• Archiva cada nota publicada — cuando un cliente reporte una regresión tres versiones después, querrás saber exactamente qué se le dijo.

Puntos Clave

• Escribe para la decisión de upgrade del lector: qué cambió, si le afecta y qué debe hacer — en ese orden.
• Cuantifica todo lo que puedas: “de 3,2s a 1,9s” supera a “más rápido”; “47 commits” supera a “mucho trabajo”.
• Automatiza la ordenación, no la redacción: deja que los conventional commits categoricen y que un humano decida qué importa.
• La transparencia sobre issues conocidos sale más barata que los tickets de soporte que llegan cuando los usuarios los descubren solos.

Lectura Adicional

• Keep a Changelog — el formato de referencia detrás de las convenciones de CHANGELOG.md
• Semantic Versioning 2.0.0 — las reglas de versionado con las que tus notas deben alinearse
• Documentación de release-please — generación automática de notas desde conventional commits
• Recursos complementarios — plantilla descargable, ejemplo relleno y formato hotfix

Errores Comunes en Producción

• Dejar secciones requeridas en blanco en lugar de eliminarlas — una sección “Seguridad” vacía parece un bug.
• Escribir las notas una vez y no actualizarlas cuando el alcance del release cambia al final del sprint.
• Guardar las release notes donde los usuarios no miran — una página de wiki que nadie tiene marcada pierde contra la página de Releases siempre.
• Copiar las notas del release anterior y olvidar quitar secciones obsoletas.
• Saltarse la línea de “sin acción requerida”, que hace que los usuarios busquen instrucciones que no existen.
• Publicar sin revisión de quien posee la superficie afectada — pasos de migración que no funcionan son peores que no tenerlos.