--- name: release-notes description: Redacta notas de versión para clientes a partir de una lista de cambios integrados, pull requests o tickets, agrupadas en Nuevo, Mejorado y Corregido, con cada línea empezando por lo que gana el usuario, sin jerga interna ni IDs de ticket. También redacta un changelog interno para el equipo. Úsala cuando alguien pega PRs integrados, un export de Jira o Linear o la lista de un sprint y pide notas de versión, un changelog, un “qué hay de nuevo” o una actualización de producto. --- # Notas de versión Los clientes leen las notas de versión para responder una sola pregunta: ¿qué puedo hacer ahora que antes no podía? Empieza cada línea con esa respuesta, en sus palabras. Deja fuera lo que no ven y nunca les hagas descifrar el título de un ticket. ## Cuándo usarla - Después de una versión, a partir de una lista de PRs integrados, tickets o mensajes de commit. - Para una página de “Novedades”, un changelog dentro de la app o un correo mensual de novedades del producto. - Cuando el equipo también necesita un changelog interno con IDs de ticket para soporte y ventas. - No para anunciar el lanzamiento de una sola función grande: usa launch-announcement. ## Qué necesitas - La lista de cambios: títulos de PR, títulos y descripciones de tickets o mensajes de commit. - El nombre o la fecha de la versión. Si falta, pregunta una vez y luego escribe “[fecha de la versión]”. - Quiénes son los clientes, para elegir sus palabras. Si no lo sabes, escribe para un usuario no técnico. - Opcional: enlaces a artículos de ayuda de las funciones nuevas. ## Pasos 1. **Quita lo que los clientes no ven.** Refactorizaciones, actualizaciones de dependencias, cambios de tests, CI, herramientas internas y logs van solo a la versión interna. Si un cambio no tiene efecto visible, no es una nota de versión. 2. **Clasifica en Nuevo, Mejorado y Corregido.** Nuevo = algo que los usuarios no podían hacer antes. Mejorado = algo que ya podían hacer y ahora es más rápido, más claro o más amplio. Corregido = algo que fallaba y ahora funciona. Si un ticket no está claro, ponlo en la lista interna con “[comprobar: ¿qué cambió para los usuarios?]” en lugar de suponer. 3. **Reescribe cada línea empezando por el beneficio.** Empieza por lo que el usuario ya puede hacer y luego cómo. “Exporta tus facturas a CSV desde la página Facturas”, no “Se añadió un endpoint de exportación CSV”. Usa los nombres de pantallas y botones del producto, no los nombres del código. 4. **Describe las correcciones para que los usuarios reconozcan el fallo.** Cuenta el síntoma que vieron: “Las fechas ya no se desplazan un día para los usuarios en zonas horarias de Asia”. Sin culpar a nadie y sin pedir perdón de más. Omite las correcciones de fallos que nunca llegaron a los clientes. 5. **Ordena por impacto.** El cambio más usado o más pedido va primero en cada grupo. Junta en una línea varios tickets que para el usuario son un solo cambio. 6. **Recorta.** Una línea por cambio, 20 palabras o menos (el valor por defecto de esta skill; la recomendación habitual es una o dos frases). Añade una introducción de 1 frase solo si un cambio domina la versión. Enlaza un artículo de ayuda cuando una función nueva requiere configuración. 7. **Redacta la versión interna.** Usa los tipos de Keep a Changelog: Añadido, Cambiado, Obsoleto, Eliminado, Corregido, Seguridad (Added, Changed, Deprecated, Removed, Fixed, Security), con la versión más reciente primero y su fecha. Añade los IDs de ticket, un grupo “Interno” para el trabajo invisible y todo lo que soporte deba saber (comportamiento que cambió, problemas conocidos, pasos de migración). ## Formato de salida ```markdown ## [Nombre o fecha de la versión] [Opcional: 1 frase sobre el cambio más grande.] ### Nuevo - [Lo que los usuarios ya pueden hacer, y dónde.] [Enlace si requiere configuración] ### Mejorado - [Lo que mejoró, en palabras del usuario.] ### Corregido - [El síntoma que vio el usuario, ya corregido.] --- ## Changelog interno — [nombre o fecha de la versión] ### Añadido - [Descripción sencilla] ([ID de ticket], [responsable]) ### Cambiado - [Descripción sencilla] ([ID de ticket]) ### Obsoleto / Eliminado - [Descripción sencilla, o quita esta sección] ([ID de ticket]) ### Corregido - [Descripción sencilla] ([ID de ticket]) ### Seguridad - [Descripción sencilla, o quita esta sección] ([ID de ticket]) ### Interno - [Refactorizaciones, actualizaciones de dependencias, herramientas] ([ID de ticket]) ### Soporte debe saber - [Comportamiento que cambió, problemas conocidos o “nada”] ``` ## Ejemplo **Entrada:** > LIN-412 Add CSV export to invoices list > LIN-418 Fix timezone offset bug in due date picker (UTC+8 and later) > LIN-420 Bump stripe-node to 14.2 > LIN-421 Invoice list pagination now 50 instead of 20 > LIN-425 Refactor PDF renderer > LIN-426 Reminder emails: add customer's company name to subject **Salida:** ```markdown ## Versión del 12 de marzo ### Nuevo - Exporta tus facturas a un archivo CSV desde la página Facturas, listo para tu hoja de cálculo o tu contador. ### Mejorado - La página Facturas ahora muestra 50 facturas a la vez, así que te desplazas menos. - Los correos de recordatorio ahora incluyen el nombre de la empresa de tu cliente en el asunto, para que destaquen en la bandeja de entrada. ### Corregido - Las fechas de vencimiento ya no retroceden un día para los usuarios en zonas horarias de Asia y Australia. --- ## Changelog interno — 12 de marzo ### Añadido - Exportación CSV en la lista de facturas (LIN-412) ### Cambiado - Tamaño de página de la lista de facturas de 20 a 50 (LIN-421) - Nombre de la empresa del cliente en el asunto del recordatorio (LIN-426) ### Corregido - Desfase del selector de fecha de vencimiento en UTC+8 y posteriores (LIN-418) ### Interno - stripe-node 14.2 (LIN-420) - Refactorización del generador de PDF (LIN-425) ### Soporte debe saber - Los clientes que filtran los correos de recordatorio por asunto quizá tengan que actualizar su filtro (LIN-426). ``` ## Comprobaciones antes de enviar - [ ] La sección para clientes no tiene IDs de ticket, nombres de código ni palabras como “endpoint”, “refactorización” o “bump”. - [ ] Cada línea empieza por lo que el usuario puede hacer o lo que va a notar. - [ ] Cada cambio aparece en un solo grupo. - [ ] Ningún cambio se describe más allá de lo que dice el ticket; los que no están claros llevan “[comprobar: ...]” en la lista interna. - [ ] Cada línea tiene 20 palabras o menos. ## Errores comunes - Copiar los títulos de los tickets con retoques. “Fix timezone offset bug” no le dice nada a un cliente; describe el síntoma. - Listar trabajo invisible para que la versión parezca más grande. Entierra los cambios que a la gente le importan. - Prometer lo que viene en las notas de versión. Limítate a lo que ya salió.