changelog

Generar changelog

Resumen

Este skill genera entradas de changelog siguiendo el formato Keep a Changelog (keepachangelog.com). El changelog es el documento que los usuarios consultan para saber qué ha cambiado entre versiones. Está escrito para personas, no para máquinas: el lenguaje debe ser claro y orientado al impacto para el usuario, no a los detalles internos de implementación.

Un buen changelog responde a la pregunta "qué ha cambiado que me afecta" sin requerir que el lector entienda el código.

Nota: este skill genera entradas de changelog individuales. Para el proceso completo de publicación de una release (versionado, changelog, notas, publicación), usar el protocolo release-planning.

Proceso

1. Identificar los cambios a documentar. Revisar el historial de Git desde la última versión publicada:

   • Commits desde el último tag de versión.
   • Pull requests mergeados.
   • Issues cerrados.

   Filtrar los cambios internos (refactoring, actualización de CI) que no afectan al usuario, a menos que sean relevantes (como mejoras de rendimiento).

2. Clasificar cada cambio en su categoría. Keep a Changelog define seis categorías:

   Categoría	Descripción	Ejemplo
   Added	Funcionalidad nueva	"Soporte para autenticación con Google"
   Changed	Cambio en funcionalidad existente	"El límite de subida de archivos pasa de 5MB a 20MB"
   Deprecated	Funcionalidad que se eliminará en una versión futura	"El endpoint /v1/users se sustituirá por /v2/users en la versión 3.0"
   Removed	Funcionalidad eliminada	"Se elimina el soporte para IE11"
   Fixed	Corrección de errores	"Corregido error que impedía guardar formularios con campos vacíos"
   Security	Corrección de vulnerabilidades	"Actualizada dependencia X para corregir CVE-YYYY-NNNN"

3. Redactar cada entrada. Reglas de redacción:

   • Escribir en lenguaje del usuario, no del desarrollador. "Ahora puedes exportar tus datos en CSV" en vez de "Se añade endpoint GET /export?format=csv".
   • Empezar con verbo en infinitivo o participio según la categoría.
   • Ser concreto: evitar "varias mejoras de rendimiento" sin especificar cuáles.
   • Incluir enlace al issue o PR cuando exista, para quien quiera profundizar.

4. Formato del encabezado de versión:

   ## [1.2.0] - 2024-03-15
   
   ### Added
   - Soporte para exportar datos en formato CSV (#42)
   - Nuevo filtro de búsqueda por fecha (#38)
   
   ### Fixed
   - Corregido error al paginar resultados con más de 1000 registros (#45)
   
   ### Security
   - Actualizada dependencia lodash a 4.17.21 para corregir CVE-2021-23337 (#47)
   

5. Mantener la sección [Unreleased]. Los cambios que aún no forman parte de una versión se agrupan bajo [Unreleased] en la parte superior del changelog. Al publicar una nueva versión, estos cambios se mueven bajo el encabezado de la nueva versión.

6. Verificar enlaces. Si el changelog incluye enlaces a issues o PRs, verificar que los enlaces son correctos y accesibles.

7. Ubicación del fichero. El changelog se guarda como CHANGELOG.md en la raíz del proyecto, siguiendo la convención estándar.

Criterios de éxito

• Los cambios están clasificados en las categorías correctas de Keep a Changelog.
• El lenguaje está orientado al usuario, no al desarrollador.
• Cada entrada es concreta y evita generalidades vagas.
• Hay enlaces a issues o PRs cuando están disponibles.
• El formato de versión sigue versionado semántico (MAJOR.MINOR.PATCH).
• La sección [Unreleased] existe para cambios no publicados.