Compétence de générateur de journal des modifications pour Conventional Commits

--- name: conventional-commits-changelog-builder description: Transforme un journal git au format Conventional Commits en une section de notes de version prête à coller au format Keep a Changelog - Added, Changed, Deprecated, Removed, Fixed, Security - avec portées, liens vers les issues et commits, et un bloc de changements cassants. Signale les changements cassants sans notes de migration, les commits non conformes et fixup, les reverts et doublons, et suggère la prochaine version SemVer. Inclut un générateur Python hors ligne avec --self-test. --- # Générateur de journal de modifications Conventional Commits Vous aidez les mainteneurs à transformer les commits depuis le dernier tag en entrée de journal de modifications que les gens peuvent réellement lire. Le faire à la main signifie parcourir un journal, deviner quels commits comptent et oublier le changement cassant caché dans un pied de page. Le générer aveuglément copie chaque faute de frappe, commit WIP et fonctionnalité annulée dans la version. Vous analysez les commits, les mappez aux sections Keep a Changelog, listez exactement ce qui a été omis et pourquoi, et indiquez quelle version la version devrait recevoir. ## Fichiers dans cette compétence - `scripts/changelog_build.py` - lit `git log` (format par défaut), `git log --oneline` ou un export d'enregistrements `%x1f`/`%x1e` ; analyse les en-têtes `type(scope)!: description` et les pieds de page `BREAKING CHANGE:` ; regroupe en Added / Changed / Deprecated / Removed / Fixed / Security avec un bloc BREAKING CHANGES ; annule les reverts dans la plage, ignore les merges, supprime les doublons, signale les commits fixup/WIP et non conformes avec un en-tête suggéré ; lie les issues, commits et la plage de comparaison ; suggère le bump SemVer (conscient de 0.x) ; peut insérer la section dans un CHANGELOG.md existant (bibliothèque standard Python 3.8+ uniquement) - `references/commit-to-changelog-mapping.md` - le tableau type -> section, règles de changements cassants, règles de bump et codes de constatation CC01-CC10 - `references/release-hygiene.md` - rédaction d'entrées pour les utilisateurs, notes de migration, que faire avec un historique non conforme, et vérifications CI - `templates/release-notes-review.md` - la revue à remettre avec la section - `examples/git-log.txt` - 21 commits d'un CLI fictif (tidyq) depuis v2.3.1 : deux changements cassants, un correctif de sécurité, une dépréciation, un revert, un cherry-pick en double, un fixup, un WIP et un commit "Fixed ..." simple - `examples/CHANGELOG.md` - le journal de modifications existant du projet (Unreleased + 2.3.1 + 2.3.0) - `examples/changelog-report.md` - la sortie réelle du générateur sur ce journal ## Flux de travail ### 1. Obtenir la plage de commits Demandez le dernier tag publié et exportez tout ce qui suit, du plus récent au plus ancien : ``` git log v2.3.1..HEAD > commits.txt git log v2.3.1..HEAD --format='%H%x1f%s%x1f%b%x1e' > commits.txt # le plus sûr : conserve les corps, pas de devinette d'analyse ``` Demandez également la version actuelle, la date de publication, l'URL du dépôt (pour les liens), le préfixe de tag (`v` par défaut) et si les commits internes (refactor, docs, ci, chore, test) doivent être listés. Un flux de travail squash-merge est idéal : un PR = un commit = une ligne. ### 2. Exécuter le générateur ``` 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 ``` Code de sortie 0 = prêt à taguer, 1 = constatations élevées, 2 = entrée invalide. Sans shell, appliquez `references/commit-to-changelog-mapping.md` à la main : analysez chaque en-tête, mappez le type à la section, collectez les pieds de page `!` et `BREAKING CHANGE:`, annulez les reverts, puis choisissez le bump le plus élevé. ### 3. Corriger les constatations avant de taguer - CC03 (élevé) : un commit `!` sans pied de page `BREAKING CHANGE:` ne donne aucun chemin de migration aux utilisateurs. Écrivez la note (ce qui casse, quoi faire à la place) dans la section. - CC08 (élevé) : les commits non conformes qui ressemblent à des fonctionnalités ou correctifs manquent dans le journal de modifications. Ajoutez-les à la main avec l'en-tête suggéré, et activez une vérification commit-lint. - CC07 : les commits fixup/WIP doivent être squasher avant la version ; CC04 : les reverts de versions plus anciennes nécessitent une phrase expliquant pourquoi. - CC01/CC02/CC05/CC06 : formulation et conformité ; corrigez dans le texte du journal, pas en réécrivant l'historique publié. ### 4. Éditer pour les humains Le générateur vous donne une structure correcte, pas une bonne prose. Réécrivez les entrées comme des effets visibles par l'utilisateur ("Export écrit Parquet par défaut" plutôt que "refactor writer"), fusionnez les entrées qui décrivent un seul changement, conservez les portées que les utilisateurs reconnaissent, et placez le bloc BREAKING CHANGES là où personne ne peut le manquer. Voir `references/release-hygiene.md`. ### 5. Livrer Remplissez `templates/release-notes-review.md` : version et pourquoi, section finale, notes de migration, ce qui a été omis, et suivis (commitlint, vérification des titres de PR). Avec `--insert`, remettez le CHANGELOG.md mis à jour ; le fichier original n'est jamais modifié. ## Exemple de résultat Sur `examples/git-log.txt` (actuel 2.3.1), le générateur lit 21 commits, 85% conformes, et suggère **3.0.0** : `feat(export)!` rend Parquet par défaut (avec un pied de page BREAKING CHANGE approprié) et `fix(config)!` supprime le fichier de configuration INI sans aucune note de migration (CC03, élevé). "Fixed crash when the config file is empty" n'est pas un commit Conventional et manquerait silencieusement le journal de modifications (CC08, élevé ; suggéré `fix: crash when the config file is empty`). Le correctif de fuite de jeton atterrit sous Security, la dépréciation `--legacy-dates` sous Deprecated, la fonctionnalité de thèmes de couleurs et son revert s'annulent, le correctif BOM cherry-pické est listé une fois, et le merge, fixup, WIP et 5 commits internes sont listés comme omis. ## Règles - N'inventez jamais d'entrées : chaque ligne provient d'un commit, et chaque commit est soit dans la section, soit dans la liste "omis". - Un changement cassant reçoit toujours une note de migration et le bump majeur (mineur sur 0.x) ; ne le cachez jamais dans Changed. - Les correctifs de sécurité vont sous Security même lorsque le type de commit est `fix`. - Ne réécrivez pas l'historique publié pour corriger les messages de commit ; corrigez le texte du journal et ajoutez une vérification lint pour l'avenir. - Gardez la version la plus récente en haut, les dates au format AAAA-MM-JJ et un lien de comparaison par version. - La version est une suggestion : le mainteneur décide, surtout pour les changements de comportement typés `fix`.