Nexus - AI Task Orchestrator

06-changelog-generation
Procedimiento: Generaci├│n de Changelog

Documentacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
8805 caracteres
# Procedimiento: Generaci├│n de Changelog

## Metadata
- **ID**: PROC-06
- **Frecuencia**: Pre-release o Semanal
- **Duraci├│n estimada**: 10-20 min
- **Requiere**: Acceso al repositorio, commits con formato convencional
- **Dependencias**: PROC-20 (parte del release planning)
- **Bloquea**: Release (changelog debe estar actualizado)
- **Agentes**: documentation-engineer

---

## Objetivo

Generar y mantener un changelog actualizado:
1. Parsear commits con formato Conventional Commits
2. Agrupar cambios por tipo (feat, fix, breaking, etc.)
3. Generar entrada para nueva versi├│n
4. Mantener hist├│rico de versiones anteriores

---

## Formato Conventional Commits

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Tipos soportados:**

| Tipo | Descripci├│n | Aparece en |
|------|-------------|------------|
| `feat` | Nueva funcionalidad | Added |
| `fix` | Correcci├│n de bug | Fixed |
| `docs` | Documentaci├│n | Documentation |
| `style` | Formato (no afecta c├│digo) | No incluir |
| `refactor` | Refactoring | Changed |
| `perf` | Mejora de rendimiento | Performance |
| `test` | Tests | No incluir |
| `chore` | Mantenimiento | No incluir |
| `ci` | CI/CD | No incluir |
| `BREAKING CHANGE` | Cambio incompatible | Breaking Changes |

---

## Checklist Ejecutable

### 1. Determinar Rango de Commits

```bash
# Opci├│n 1: Desde ├║ltimo tag
git describe --tags --abbrev=0
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

# Opci├│n 2: Desde ├║ltima entrada en CHANGELOG
grep -m1 "^## \[" CHANGELOG.md | grep -oE "\[.*\]"

# Opci├│n 3: Desde fecha espec├¡fica
git log --since="2024-01-01" --oneline
```

- [ ] Rango determinado: desde ___ hasta HEAD
- [ ] N├║mero de commits a procesar: ___

### 2. Extraer Commits del Rango

```bash
# Listar commits con formato convencional
git log ${LAST_TAG}..HEAD --pretty=format:"%s|%h|%an|%ai" | \
  grep -E "^(feat|fix|docs|refactor|perf|breaking)(\(.*\))?:"

# Separar por tipo
git log ${LAST_TAG}..HEAD --pretty=format:"%s" | grep "^feat"
git log ${LAST_TAG}..HEAD --pretty=format:"%s" | grep "^fix"
git log ${LAST_TAG}..HEAD --pretty=format:"%s" | grep -i "breaking"
```

- [ ] Features extra├¡das
- [ ] Fixes extra├¡dos
- [ ] Breaking changes identificados

### 3. Detectar Breaking Changes

```bash
# En el cuerpo del commit
git log ${LAST_TAG}..HEAD --pretty=format:"%B" | grep -i "BREAKING CHANGE"

# En el tipo (feat! o fix!)
git log ${LAST_TAG}..HEAD --pretty=format:"%s" | grep -E "^(feat|fix)!:"

# En footer
git log ${LAST_TAG}..HEAD --pretty=format:"%b" | grep "BREAKING-CHANGE:"
```

- [ ] Breaking changes documentados: ___

### 4. Determinar Nueva Versi├│n

**Semver seg├║n cambios:**

| Cambios | Bump |
|---------|------|
| Solo fix | PATCH (0.0.X) |
| feat sin breaking | MINOR (0.X.0) |
| BREAKING CHANGE | MAJOR (X.0.0) |

```bash
# Versi├│n actual
CURRENT=$(git describe --tags --abbrev=0 2>/dev/null || echo "0.0.0")

# Sugerir nueva versi├│n
# Si hay BREAKING -> major
# Si hay feat -> minor
# Si solo fix -> patch
```

- [ ] Versi├│n actual: ___
- [ ] Nueva versi├│n sugerida: ___

### 5. Generar Entrada de Changelog

**Formato est├índar (Keep a Changelog):**

```markdown
## [X.Y.Z] - YYYY-MM-DD

### Added
- feat: nueva funcionalidad X (#123)
- feat(scope): otra funcionalidad Y (#124)

### Fixed
- fix: correcci├│n de bug Z (#125)
- fix(api): otro fix (#126)

### Changed
- refactor: mejora en m├│dulo W (#127)

### Performance
- perf: optimizaci├│n de queries (#128)

### Breaking Changes
- BREAKING: cambio en API endpoint /old -> /new (#129)
```

- [ ] Secci├│n Added generada
- [ ] Secci├│n Fixed generada
- [ ] Secci├│n Breaking Changes (si aplica)

### 6. Actualizar CHANGELOG.md

```bash
# Verificar que existe
test -f CHANGELOG.md || echo "# Changelog" > CHANGELOG.md

# Estructura esperada:
# # Changelog
#
# ## [Unreleased]
#
# ## [X.Y.Z] - YYYY-MM-DD
# ...
```

- [ ] Nueva versi├│n a├▒adida despu├®s de [Unreleased]
- [ ] Formato consistente
- [ ] Links a PRs/issues incluidos

### 7. Verificar Calidad

```bash
# Validar formato markdown
npx markdownlint CHANGELOG.md

# Verificar que versiones est├ín ordenadas (m├ís reciente primero)
grep "^## \[" CHANGELOG.md | head -5

# Verificar que fechas son v├ílidas
grep -E "## \[[0-9]+\.[0-9]+\.[0-9]+\] - [0-9]{4}-[0-9]{2}-[0-9]{2}" CHANGELOG.md
```

- [ ] Markdown v├ílido
- [ ] Versiones ordenadas correctamente
- [ ] Fechas en formato ISO

---

## Template de Changelog

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Nuevas funcionalidades pendientes de release

### Fixed
- Fixes pendientes de release

## [1.2.0] - 2024-01-15

### Added
- feat(api): nuevo endpoint para consulta de usuarios (#45)
- feat: soporte para autenticaci├│n OAuth2 (#42)

### Fixed
- fix(db): correcci├│n de query lenta en b├║squeda (#44)
- fix: manejo de errores en upload de archivos (#43)

### Breaking Changes
- El endpoint `/api/v1/users` ahora requiere autenticaci├│n (#42)

## [1.1.0] - 2024-01-01

### Added
- feat: m├│dulo de reportes (#40)

### Fixed
- fix: correcci├│n de validaci├│n de fechas (#39)
```

---

## Output Esperado

```
====== PROC-06 COMPLETADO [TIMESTAMP] ======
Proyecto: [nombre]

RANGO ANALIZADO:
- Desde: [tag/fecha]
- Hasta: HEAD
- Commits procesados: X

CAMBIOS DETECTADOS:
- Features (feat): X
- Fixes (fix): Y
- Refactors: Z
- Breaking Changes: W

VERSI├ôN:
- Actual: X.Y.Z
- Nueva sugerida: X.Y.Z (bump: major/minor/patch)

CHANGELOG GENERADO:
## [X.Y.Z] - YYYY-MM-DD

### Added
- [lista]

### Fixed
- [lista]

ARCHIVO ACTUALIZADO:
- CHANGELOG.md Ô£à

PR├ôXIMOS PASOS:
1. Revisar entrada generada
2. Ajustar descripciones si es necesario
3. Crear tag con nueva versi├│n
```

---

## Criterios de ├ëxito

- [ ] Todos los commits relevantes incluidos
- [ ] Breaking changes claramente marcados
- [ ] Versi├│n correcta seg├║n semver
- [ ] Formato v├ílido y consistente

---

## Alertas y Escalaci├│n

| Severidad | Condici├│n | Acci├│n |
|-----------|-----------|--------|
| CRITICAL | Breaking change sin documentar | Bloquear release |
| WARNING | Commits sin formato convencional | Revisar manualmente |
| WARNING | CHANGELOG no existe | Crear con template |
| INFO | Changelog actualizado | Proceder con release |

---

## Automatizaci├│n

En ejecuci├│n no-interactiva:
1. Detectar ├║ltimo tag/versi├│n
2. Extraer commits del rango
3. Clasificar por tipo
4. Generar entrada de changelog
5. Actualizar archivo
6. Commit autom├ítico

---

## Herramientas Opcionales

```bash
# Conventional Changelog CLI
npm install -g conventional-changelog-cli
conventional-changelog -p angular -i CHANGELOG.md -s

# Standard Version (bump + changelog + tag)
npm install -g standard-version
standard-version

# Release It
npm install -g release-it
release-it
```

---


---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-06 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "score": 85, "drift_percent": 8,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-06"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- entries_added, commits_processed

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar

## Historial de Ejecuciones

| Fecha | Proyecto | Versi├│n Anterior | Nueva Versi├│n | Commits | Breaking |
|-------|----------|------------------|---------------|---------|----------|
| | | | | | |