Habilidad: changelog
Crea o actualiza un registro de cambios (changelog) a partir del historial de Git, agrupado por versiones y categorizado por tipo de funcionalidad.
Disparadores
/changelog- Crear o actualizar el changelog- "Crea un changelog", "Actualiza el changelog", "¿Qué ha cambiado desde..."
Parámetros
Pregunta al usuario la siguiente información si no se proporciona:
-
Público objetivo (también determina el archivo predeterminado)
- Usuario final →
Changelog.md(simplificado, describe el beneficio) - Desarrollador →
Changelog-Dev.md(técnico, con detalles de commits)
- Usuario final →
-
Modo
- Actualizar (predeterminado): Solo añadir cambios nuevos desde la última entrada
- Crear desde cero: Crear un changelog completo desde un punto en el tiempo
-
Periodo (solo para "Crear desde cero")
- Ejemplos: "desde marzo de 2025", "desde v2.3.0"
Flujo de trabajo
1. Verificar changelog existente
# Verificar si existe el changelog
ls Changelog.md Changelog-Dev.md 2>/dev/null
Si el changelog existe:
- Determinar el último estado documentado (versión o commit)
- Buscar el marcador
## 🔮 En desarrollopara encontrar el último commit conocido - O tomar la última versión Insiders/Stable documentada como referencia
2. Recolectar datos de Git
# Obtener tags con fecha
git for-each-ref --sort=-creatordate --format='%(refname:short) %(creatordate:short)' refs/tags
# Determinar el último tag
git describe --tags --abbrev=0
# Commits desde el último tag (para "En desarrollo")
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%h %ad %s" --date=short
# Commits desde una versión específica
git log v2.3.0..HEAD --pretty=format:"%h %ad %s" --date=short
3. Categorizar commits
Analiza los mensajes de commit y asígnalos:
| Categoría | Palabras clave |
|---|---|
| Nuevas funcionalidades | Add, Feat, Feature, New, Implement |
| Correcciones | Fix, Bugfix, Hotfix, Resolve |
| Rendimiento | Performance, Optimize, Speed |
| Técnico | Bump, Update, Refactor, Chore, Deps |
Ignorar:
- Commits de merge ("Merge branch", "Merge pull request")
- Commits de release ("Release v", "Bump version")
- Commits WIP, correcciones de build
4. Asignar versiones
Importante: Las funcionalidades pasan por las fases secuencialmente:
🔮 En desarrollo → 🧪 Insiders → ✅ Estable
(Previsión) (Early Adopter) (Todos los usuarios)
- Una funcionalidad solo puede aparecer en una fase
- Si está en Estable, antes estuvo en Insiders
- Si está en Insiders, antes estuvo en Desarrollo
- Cada sección muestra solo los cambios nuevos respecto a la versión anterior
5. Actualizar el changelog
Al actualizar:
- Leer el archivo existente
- Actualizar la sección "En desarrollo" con los nuevos commits
- Si hay un nuevo release: mover "En desarrollo" → "Insiders" o "Insiders" → "Estable"
- Guardar el archivo
Al crear desde cero:
- Crear la plantilla completa con todas las versiones
Archivos predeterminados
| Público objetivo | Archivo | Contenido |
|---|---|---|
| Usuario final | Changelog.md | Describir el beneficio, sin detalles técnicos, sin hashes de commit |
| Desarrollador | Changelog-Dev.md | Detalles técnicos, hashes de commit, números de PR, cambios que rompen compatibilidad |
Plantilla de salida (Usuario final)
# Changelog [Nombre del proyecto]
---
## 🔮 En desarrollo (Previsión del próximo release)
*Estas funcionalidades se han añadido después de [ULTIMO_TAG] y se incluirán en el próximo release.*
### Nuevas funcionalidades
- Descripción de la funcionalidad desde la perspectiva del usuario
### Correcciones
- Descripción de la corrección desde la perspectiva del usuario
---
## 🧪 Insiders vX.Y.Z-insiders.N (DD.MM.AAAA)
*Versión de vista previa con nuevas funcionalidades respecto a Estable vX.Y.Z.*
### Nuevas funcionalidades (respecto a vX.Y.Z)
- Descripción de la funcionalidad
---
## ✅ Estable vX.Y.Z (DD.MM.AAAA)
*Versión estable: contiene todas las funcionalidades de vX.Y.Z-insiders.1 a vX.Y.Z-insiders.N.*
### Nuevas funcionalidades (respecto a vX.Y-1.Z)
- Descripción de la funcionalidad *(desde insiders.N)*
### Correcciones (respecto a vX.Y-1.Z)
- Descripción de la corrección *(desde insiders.M)*
---
## Proceso de release
Las funcionalidades pasan por tres fases antes de llegar a todos los usuarios:
🔮 En desarrollo → 🧪 Insiders → ✅ Estable (Previsión) (Early Adopter) (Todos los usuarios)
| Fase | Público objetivo | Descripción |
|------|------------------|-------------|
| 🔮 **En desarrollo** | Desarrolladores | Previsión de próximas funcionalidades. Aún no incluidas en ningún release. |
| 🧪 **Insiders** | Early Adopter | Versiones de vista previa para probar nuevas funcionalidades antes del release estable. |
| ✅ **Estable** | Todos los usuarios | Versión lista para producción. Las funcionalidades están completamente probadas y aprobadas. |
**Nota:** Cada sección solo lista los cambios que son **nuevos** en esta fase.
Plantilla de salida (Desarrollador)
# Changelog (Desarrollador)
---
## 🔮 En desarrollo
*Commits desde [ULTIMO_TAG]*
### Nuevas funcionalidades
- `abc1234` Añadida funcionalidad X (#123)
### Correcciones
- `def5678` Corregido error Y (#456)
### Cambios técnicos
- `ghi9012` Actualizada dependencia Z
---
## 🧪 Insiders vX.Y.Z-insiders.N (DD.MM.AAAA)
### Cambios que rompen compatibilidad
- Descripción de los cambios que rompen compatibilidad
### Nuevas funcionalidades
- `abc1234` Descripción de la funcionalidad (#123)
### Correcciones
- `def5678` Descripción de la corrección (#456)
---
## ✅ Estable vX.Y.Z (DD.MM.AAAA)
*Contiene Insiders .1 a .N*
### Cambios que rompen compatibilidad
- Descripción
### Commits
- Lista de todos los commits desde la última versión estable
Ejemplos
Ejemplo 1: Actualizar changelog (predeterminado)
Usuario: "Actualiza el changelog"
Procedimiento:
- Verificar si existe
Changelog.md - Determinar el último estado documentado
git log [ULTIMO_ESTADO]..HEAD --pretty=format:"%h %ad %s" --date=short- Categorizar los nuevos commits
- Actualizar la sección "En desarrollo"
Ejemplo 2: Changelog para desarrolladores
Usuario: "Crea un changelog para desarrolladores"
Procedimiento:
- Verificar si existe
Changelog-Dev.md - Recolectar el historial de Git con hashes de commit y números de PR
- Documentar detalles técnicos y cambios que rompen compatibilidad
- Guardar en
Changelog-Dev.md
Ejemplo 3: Documentar un nuevo release
Usuario: "Hemos lanzado v2.4.0-insiders.3"
Procedimiento:
- Leer Changelog.md
- Mover el contenido de "En desarrollo" a "Insiders v2.4.0-insiders.3"
- Crear una nueva sección vacía "En desarrollo"
- Añadir la fecha
Consejos
- Para mensajes de commit largos, usar la primera oración
- Conservar los números de PR (#123) solo en el changelog para desarrolladores
- Agrupar commits relacionados (ej. varios commits para una misma funcionalidad)
- Si hay muchos commits, usar el comando
headpara limitar la salida - Al actualizar, usar siempre el changelog existente como base