Habilidad de Constructor de Registro de Cambios de Conventional Commits

--- name: conventional-commits-changelog-builder description: Convierte un git log en formato Conventional Commits en una sección de release lista para pegar en Keep a Changelog - Added, Changed, Deprecated, Removed, Fixed, Security - con scopes, enlaces a issues y commits, y un bloque de breaking changes. Señala breaking changes sin notas de migración, commits no conformes y fixup, reverts y duplicados, y sugiere la siguiente versión SemVer. Incluye un builder offline en Python stdlib con --self-test. --- # Conventional Commits Changelog Builder Ayudas a los mantenedores a convertir los commits desde la última etiqueta en una entrada de changelog que la gente pueda leer realmente. Escribirla a mano significa revisar un log, adivinar qué commits importan y olvidar el breaking change oculto en un footer. Generarla a ciegas copia cada typo, commit WIP y feature revertida en el release. Parseas los commits, los mapeas a las secciones de Keep a Changelog, listas exactamente qué se omitió y por qué, y dices qué versión debería recibir el release. ## Archivos en esta skill - `scripts/changelog_build.py` - lee `git log` (formato por defecto), `git log --oneline` o una exportación de registros `%x1f`/`%x1e`; parsea cabeceras `type(scope)!: description` y footers `BREAKING CHANGE:`; agrupa en Added / Changed / Deprecated / Removed / Fixed / Security con un bloque BREAKING CHANGES; cancela reverts que están en rango, omite merges, elimina duplicados, señala commits fixup/WIP y no conformes con una cabecera sugerida; enlaza issues, commits y el rango de comparación; sugiere el bump SemVer (consciente de 0.x); puede insertar la sección en un CHANGELOG.md existente (solo biblioteca estándar de Python 3.8+) - `references/commit-to-changelog-mapping.md` - la tabla tipo -> sección, reglas de breaking change, reglas de bump y los códigos de hallazgo CC01-CC10 - `references/release-hygiene.md` - escribir entradas para usuarios, notas de migración, qué hacer con historial no conforme y comprobaciones de CI - `templates/release-notes-review.md` - la revisión para devolver junto con la sección - `examples/git-log.txt` - 21 commits de un CLI ficticio (tidyq) desde v2.3.1: dos breaking changes, un fix de seguridad, una deprecación, un revert, un cherry-pick duplicado, un fixup, un WIP y un commit simple "Fixed ..." - `examples/CHANGELOG.md` - el changelog existente del proyecto (Unreleased + 2.3.1 + 2.3.0) - `examples/changelog-report.md` - la salida real del builder sobre ese log ## Flujo de trabajo ### 1. Obtener el rango de commits Pide la última etiqueta publicada y exporta todo lo posterior, del más nuevo al más antiguo: ``` git log v2.3.1..HEAD > commits.txt git log v2.3.1..HEAD --format='%H%x1f%s%x1f%b%x1e' > commits.txt # más seguro: conserva cuerpos, sin adivinanzas de parseo ``` También pide la versión actual, la fecha del release, la URL del repositorio (para enlaces), el prefijo de etiqueta (`v` por defecto) y si los commits internos (refactor, docs, ci, chore, test) deben listarse. Un flujo de squash-merge es ideal: un PR = un commit = una línea. ### 2. Ejecutar el builder ``` python3 scripts/changelog_build.py examples/git-log.txt --current 2.3.1 --date 2026-11-03 --repo-url https://github.com/tidyq/tidyq python3 scripts/changelog_build.py commits.txt --current 2.3.1 --insert CHANGELOG.md > CHANGELOG.new.md python3 scripts/changelog_build.py commits.txt --current 0.9.4 --include-internal --json python3 scripts/changelog_build.py --self-test ``` Salida 0 = listo para etiquetar, 1 = hallazgos altos, 2 = entrada incorrecta. Sin shell, aplica `references/commit-to-changelog-mapping.md` manualmente: parsea cada cabecera, mapea el tipo a la sección, recoge footers `!` y `BREAKING CHANGE:`, cancela reverts, luego elige el bump más alto. ### 3. Corregir los hallazgos antes de etiquetar - CC03 (alto): un commit con `!` sin footer `BREAKING CHANGE:` no da a los usuarios una ruta de migración. Escribe la nota (qué se rompe, qué hacer en su lugar) en la sección. - CC08 (alto): commits no conformes que parecen features o fixes faltan en el changelog. Añádelos manualmente con la cabecera sugerida y activa una comprobación de commit-lint. - CC07: los commits fixup/WIP deben aplastarse antes del release; CC04: los reverts de releases anteriores necesitan una frase explicando por qué. - CC01/CC02/CC05/CC06: redacción y conformidad; corrige en el texto del changelog, no reescribiendo historia publicada. ### 4. Editar para humanos El builder te da estructura correcta, no buena prosa. Reescribe las entradas como efectos visibles para el usuario ("Export escribe Parquet por defecto" en lugar de "refactor writer"), fusiona entradas que describen un solo cambio, mantén scopes que los usuarios reconozcan y coloca el bloque BREAKING CHANGES donde nadie pueda pasarlo por alto. Consulta `references/release-hygiene.md`. ### 5. Entregar Completa `templates/release-notes-review.md`: versión y por qué, la sección final, las notas de migración, qué se omitió y seguimientos (commitlint, comprobación de títulos de PR). Con `--insert`, devuelve el CHANGELOG.md actualizado; el archivo original nunca se modifica. ## Ejemplo de resultado En `examples/git-log.txt` (actual 2.3.1) el builder lee 21 commits, 85% conformes, y sugiere **3.0.0**: `feat(export)!` hace Parquet el formato por defecto (con un footer BREAKING CHANGE adecuado) y `fix(config)!` elimina el archivo de configuración INI sin ninguna nota de migración (CC03, alto). "Fixed crash when the config file is empty" no es un Conventional Commit y se perdería silenciosamente del changelog (CC08, alto; sugerido `fix: crash when the config file is empty`). El fix de fuga de tokens va bajo Security, la deprecación de `--legacy-dates` bajo Deprecated, la feature de temas de color y su revert se cancelan, el fix BOM cherry-picked se lista una vez, y el merge, fixup, WIP y 5 commits internos se listan como omitidos. ## Reglas - Nunca inventes entradas: cada línea proviene de un commit, y cada commit está en la sección o en la lista de "omitidos". - Un breaking change siempre recibe una nota de migración y el bump mayor (menor mientras esté en 0.x); nunca lo ocultes en Changed. - Los fixes de seguridad van bajo Security incluso cuando el tipo de commit es `fix`. - No reescribas historia publicada para corregir mensajes de commit; corrige el texto del changelog y añade una comprobación de lint para el futuro. - Mantén el release más nuevo arriba, fechas como YYYY-MM-DD y un enlace de comparación por versión. - La versión es una sugerencia: el mantenedor decide, especialmente para cambios de comportamiento tipados como `fix`.