Generador de Registros de Cambios
Genera automáticamente registros de cambios (changelogs) legibles para humanos a partir del historial de git. Sigue el formato Keep a Changelog, pule los mensajes de commit en lenguaje amigable y, opcionalmente, crea Releases en GitHub.
Resolución de Entrada
La entrada principal es un rango de referencias git. Resuelve el argumento (si se proporciona):
- Contiene
...o..-> rango de referencia git (ej.v1.0.0...v1.1.0) - Coincide con una etiqueta/referencia única -> desde esa referencia hasta HEAD
- Coincide con una URL de GitHub o patrón
#\d+-> PR (extraer cambios solo de ese PR). Para entrada de un solo PR: leer el diff y la descripción del PR, categorizar cambios, usar el título del PR como entrada. Omitir el encabezado de versión. Preguntar al usuario si quiere añadir estas entradas a una versión existente del registro o crear una nueva. - Sin argumento -> preguntar: "¿Qué rango debería cubrir el registro de cambios? Puedes proporcionar un rango de referencias git (ej. v1.0.0...v1.1.0), una etiqueta (cambios desde esa etiqueta) o un número de PR."
Flujo de Proceso
digraph changelog {
rankdir=TB;
"Resolve input" [shape=box];
"Phase 1: Gather" [shape=box];
"Phase 2: Categorize" [shape=box];
"Phase 3: Polish" [shape=box];
"Phase 4: Review" [shape=box];
"Approved?" [shape=diamond];
"Phase 5: Output" [shape=box];
"Resolve input" -> "Phase 1: Gather";
"Phase 1: Gather" -> "Phase 2: Categorize";
"Phase 2: Categorize" -> "Phase 3: Polish";
"Phase 3: Polish" -> "Phase 4: Review";
"Phase 4: Review" -> "Approved?";
"Approved?" -> "Phase 3: Polish" [label="revisions"];
"Approved?" -> "Phase 5: Output" [label="yes"];
}
NO omitas fases. Haz preguntas a un ritmo natural. Si el usuario responde varias a la vez, acepta respuestas agrupadas y avanza.
Si el usuario dice "solo usa valores predeterminados" o similar, elige valores predeterminados razonables, indica lo que elegiste y pide una única confirmación.
Fase 1: Recopilar
Paso 1 - Recopilar commits y PRs
Ejecuta git log entre las dos referencias para recopilar todos los commits. Si el repositorio usa PRs, también verifica PRs fusionados en el rango usando gh pr list --state merged.
Para cada commit/PR, extrae:
- Mensaje del commit (asunto + cuerpo)
- Archivos cambiados (para determinar el alcance)
- Título y descripción del PR (si está disponible)
- Cualquier prefijo de tipo de commit convencional (feat, fix, chore, etc.)
Paso 2 - Leer contexto más amplio del producto
Lee si existen: README, package.json (o equivalente). Objetivo: entender qué es el producto para escribir descripciones amigables para el usuario.
Si no se encuentra nada, pregunta: "¿Puedes describir brevemente el producto? Necesito contexto para escribir entradas de registro de cambios amigables."
Paso 3 - Detectar formato existente
Verifica si el repositorio tiene un CHANGELOG.md existente. Si lo tiene:
- Detecta el formato (Keep a Changelog, personalizado, etc.)
- Detecta si usa etiquetas emoji (ej. emojis para Nuevo, Corrección de error, Ruptura) o categorías de texto plano
- Coincide con el estilo existente
Si no hay registro de cambios existente:
- Usa por defecto el formato Keep a Changelog
- Pregunta: "No se encontró un registro de cambios existente. ¿Prefieres etiquetas emoji (ej. para Nuevo, Corrección de error) o categorías de texto plano (Añadido, Corregido, etc.)?"
Fase 2: Categorizar
Ordena todos los cambios en las categorías de Keep a Changelog. Cambios Rupturistas obtienen una sección dedicada en la parte superior:
- Cambios Rupturistas - cualquier cambio que rompa el comportamiento existente, APIs o requiera acción del usuario para actualizar. Incluye notas de migración para cada uno. Detecta a partir de
feat!:,fix!:, pies deBREAKING CHANGE:, o APIs eliminadas/renombradas en el diff. - Añadido - nuevas funcionalidades
- Cambiado - cambios en funcionalidades existentes
- Obsoleto - funcionalidades que serán eliminadas
- Eliminado - funcionalidades que fueron eliminadas
- Corregido - correcciones de errores
- Seguridad - correcciones de vulnerabilidades
Reglas de categorización:
- Si los commits siguen commits convencionales (
feat:,fix:, etc.), usa el tipo para categorizar - Si no, analiza el diff y el mensaje del commit para determinar la categoría
- Omite cambios solo internos (refactorizaciones, adiciones de pruebas, cambios de CI, actualizaciones de dependencias) a menos que afecten el comportamiento para el usuario
- Cuando no estés seguro de si un cambio es visible para el usuario, inclúyelo y deja que el usuario lo elimine en la revisión
- Para rangos con 50+ commits, agrupa cambios relacionados en entradas de alto nivel (ej. en lugar de listar 12 correcciones individuales de API, escribe "Mejora en el manejo de errores de API en múltiples endpoints"). Presenta la versión agrupada y permite al usuario expandir cualquier grupo si quiere detalle.
Presenta la lista categorizada:
"Esto es lo que encontré en este rango:"
Añadido (3)
- Funcionalidad A
- Funcionalidad B
- Funcionalidad C
Corregido (2)
- Corrección de error A
- Corrección de error B
"¿Algo que añadir, eliminar o recategorizar?"
NO continúes hasta que el usuario confirme.
Fase 3: Pulir
Reescribe cada entrada en lenguaje amigable para humanos:
- Comienza con el beneficio para el usuario, no con el detalle de implementación
- "Los informes ahora cargan 3 veces más rápido" no "Plan de ejecución de SQL optimizado para el módulo de informes"
- "Ahora puedes exportar informes a PDF" no "Se añadió funcionalidad de exportación a PDF al servicio de informes"
- Mantén cada entrada en una línea (máximo dos para cambios complejos)
- Incluye referencias a PRs/issues cuando estén disponibles (ej.
(#123))
Encabezado de versión
Formato: ## [versión] - AAAA-MM-DD
Si el límite superior del rango es una etiqueta de versión (ej. v1.2.0), usa esa como versión. Si el límite superior es HEAD o un nombre de rama, pregunta: "¿Qué número de versión debería usar este registro de cambios?"
Usa la fecha del commit más reciente en el rango, en formato ISO (AAAA-MM-DD).
Apéndice técnico
Después de generar el registro de cambios amigable, pregunta:
"¿Quieres que también genere un apéndice técnico con detalles de implementación? (útil para documentación orientada a desarrolladores)"
Si la respuesta es sí, genera una sección más detallada con especificaciones técnicas, guías de migración por cambios rupturistas y cambios en APIs.
Reglas de escritura
- Nunca uses guiones largos en el contenido generado. Sin caracteres "---". Usa comas, dos puntos, puntos o paréntesis en su lugar.
- Lenguaje amigable por defecto (sin jerga, sin nombres internos de funcionalidades)
- Una línea por entrada, máximo dos para cambios complejos
- Tiempo verbal consistente (pasado: "Añadido", "Corregido", "Eliminado")
- Incluye referencias a PRs/issues cuando estén disponibles
Fase 4: Revisar
Presenta la entrada completa del registro de cambios:
"Aquí está el registro de cambios:"
## [1.2.0] - 2026-04-11 ### Añadido - Ahora puedes exportar informes a PDF (#123) ### Corregido - El panel ya no parpadea al cargar la página (#456)"¿Quieres algún cambio?"
Espera la aprobación. Solo continúa a la salida una vez que el usuario confirme.
Fase 5: Salida
CHANGELOG.md
Detecta CHANGELOG.md existente en la raíz del repositorio. Si se encuentra, lee el archivo completo, identifica el punto de inserción (antes de la primera línea ## [), presenta el punto de inserción propuesto al usuario y confirma antes de escribir. Si no se encuentra, crea uno con un encabezado estándar:
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/).
Siempre confirma antes de escribir:
"Voy a anteponer esto a
CHANGELOG.md. ¿Todo bien?"
GitHub Release
Después de guardar el registro de cambios, pregunta:
"¿Quieres que también cree una Release en GitHub con este registro de cambios?"
Si la respuesta es sí, usa gh release create <etiqueta> --notes "<contenido del registro>" para crear la release. Si gh no está disponible, informa al usuario y omite.
Manejo de Errores
ghno disponible -> informa al usuario, omite el enriquecimiento de PR y la Release en GitHub, confía solo en git log- Referencia/etiqueta inválida -> pide al usuario que verifique
- Sin commits en el rango -> informa al usuario, pide que verifique el rango
- Sin contexto del producto -> pide al usuario que describa el producto
- Commits no convencionales -> recurre al análisis del diff para la categorización
Lo que esta habilidad NO hace
- Gestionar la estrategia de versionado (las decisiones de versionado semántico son del usuario)
- Publicar en registros de paquetes
- Generar publicaciones de blog o boletines (usa
/blog-posto/newsletter) - Manejar estrategias de ramificación o flujos de trabajo de lanzamiento