changelog-generator

Présentation de changelog-generator skill

Ce que fait changelog-generator

changelog-generator est une skill de gestion des releases pour les équipes d’ingénierie : elle transforme un historique de Conventional Commits en notes de version cohérentes, vérifiables et faciles à auditer. Elle aide un agent IA à analyser les objets de commit, à déduire les changements de version selon le versionnement sémantique, à produire des sections au format Keep a Changelog et à relier le résultat à des workflows de CI ou de hotfix, plutôt qu’à générer un texte libre à partir d’un prompt générique.

Profils et scénarios de release les plus adaptés

Cette skill changelog-generator convient particulièrement aux mainteneurs, release engineers, équipes DevOps et rédacteurs techniques qui ont besoin d’entrées CHANGELOG.md reproductibles à partir d’un véritable historique git. Elle s’adapte aux découpes de release, aux contrôles de commits dans les PR, à la planification semver, aux releases de packages en monorepo et aux notes de hotfix urgentes lorsque la traçabilité est essentielle.

Elle est particulièrement utile comme changelog-generator pour la rédaction technique lorsque les rédacteurs doivent produire des notes destinées aux utilisateurs à partir de messages de commit développeur, tout en conservant les éléments de preuve : plage de commits, version, breaking changes, correctifs de sécurité et notes de migration.

Ce qui la distingue d’un prompt classique

Un prompt classique du type « rédige des notes de version » perd souvent la structure ou invente l’impact produit. Cette skill inclut des scripts et références dédiés : scripts/generate_changelog.py, scripts/commit_linter.py, scripts/version_bumper.py, ainsi que des consignes pour le format du changelog, l’intégration CI, les monorepos et les procédures de hotfix. Elle est donc plus adaptée aux workflows de release automatisés ou semi-automatisés.

Contraintes d’adoption à vérifier en premier

La skill part du principe que les commits sont proches du format Conventional Commits, par exemple feat(auth): add OAuth2 integration ou fix(api): resolve race condition. Si votre dépôt utilise des messages vagues comme updates, misc fixes, ou des commits squashés sans objet exploitable, la qualité de sortie diminuera sauf si vous fournissez du contexte supplémentaire. Les équipes qui n’appliquent pas de politique de release semver doivent considérer la proposition de changement de version comme une recommandation, pas comme une décision automatique.

Comment utiliser changelog-generator skill

Installation de changelog-generator et configuration du dépôt

Pour des skills locales de type Claude, copiez le dossier de la skill dans votre répertoire de skills. Le README du dépôt donne des exemples comme :

cp -R engineering/changelog-generator ~/.claude/skills/changelog-generator

Adaptez le chemin source à l’emplacement réel du dépôt cloné. Avant d’utiliser la skill en production, examinez aussi ces fichiers :

• SKILL.md pour le workflow côté agent
• README.md pour les commandes de démarrage rapide
• references/changelog-formatting-guide.md pour les règles de sortie
• references/ci-integration.md pour les exemples CI
• references/monorepo-strategy.md si vous publiez des packages indépendamment
• references/hotfix-procedures.md pour la classification des releases urgentes

Entrées nécessaires à la skill pour un résultat fiable

Pour bien utiliser changelog-generator, fournissez une frontière de release précise et suffisamment de contexte sur vos règles internes. Les entrées utiles incluent :

• le tag précédent et le tag cible, par exemple v1.2.0..v1.3.0
• la version cible ou la version actuelle si la skill doit calculer l’incrément
• les objets de commit bruts issus de git log --oneline si l’agent n’a pas accès à git
• l’indication que les breaking changes nécessitent ou non des notes de migration
• le périmètre du package pour les monorepos, par exemple payments ou auth
• le format souhaité : markdown pour CHANGELOG.md, JSON pour la CI, ou brouillon d’annonce de release

Prompt faible : « Génère un changelog. »

Prompt plus solide : « Use changelog-generator to create a Keep a Changelog entry for v1.4.0 from commits between v1.3.0 and HEAD. Group by Security, Added, Changed, Deprecated, Removed, Fixed. Flag breaking changes, infer the semver bump, and produce a concise markdown entry suitable for CHANGELOG.md. »

Modèles de commandes pratiques

Les outils inclus peuvent être utilisés directement ou consultés par l’agent pendant un workflow de release.

Générer du markdown à partir d’une plage de tags :

python3 scripts/generate_changelog.py \
  --from-tag v1.2.0 \
  --to-tag v1.3.0 \
  --next-version v1.3.0 \
  --format markdown

Vérifier les objets de commit avant merge :

python3 scripts/commit_linter.py \
  --from-ref origin/main \
  --to-ref HEAD \
  --strict \
  --format text

Utilisez la sortie JSON lorsque la CI a besoin de résultats lisibles par machine, et le markdown lorsqu’une personne doit relire le contenu ou l’ajouter en tête de CHANGELOG.md.

Workflow pour de meilleures notes de version

Commencez par contrôler les commits, puis déduisez le changement de version, générez ensuite l’entrée de changelog, puis retravaillez-la sous l’angle de l’impact utilisateur. L’étape éditoriale la plus importante consiste à transformer des messages très orientés implémentation en changements visibles par les utilisateurs, sans masquer les risques techniques importants.

Par exemple, fix(db): resolve deadlock issues in concurrent transactions devrait devenir une note destinée aux utilisateurs comme « Correction de blocages de base de données susceptibles d’interrompre des mises à jour de compte concurrentes », et non « Modification de la logique de verrouillage des transactions ».

FAQ sur changelog-generator skill

changelog-generator est-elle réservée aux releases entièrement automatisées ?

Non. La skill fonctionne aussi bien dans des workflows automatisés que dans des workflows éditoriaux. La CI peut imposer le format des commits ou générer des notes en brouillon, tandis que les humains peuvent affiner la formulation, ajouter des détails de migration et valider l’entrée de release finale.

Les débutants peuvent-ils utiliser ce guide changelog-generator ?

Oui, si le dépôt utilise déjà des tags et des commits raisonnablement structurés. Les débutants devraient commencer avec assets/sample_git_log.txt, exécuter les scripts localement, puis comparer le résultat avec references/changelog-formatting-guide.md. La partie la plus difficile n’est généralement pas l’outil lui-même, mais l’apprentissage de messages de commit contenant assez de périmètre et d’intention.

Quand ne faut-il pas utiliser cette skill ?

Évitez d’en faire la source principale de vérité lorsque les commits sont trompeurs, fortement squashés ou déconnectés du comportement réellement livré. Elle convient aussi mal aux notes de lancement marketing qui exigent du positionnement, des captures d’écran, des citations client ou un message de campagne. Dans ces cas, utilisez cette skill pour établir l’inventaire factuel de la release, puis rédigez une annonce séparée.

Comment gère-t-elle les monorepos et les commits scopés ?

Les recommandations monorepo privilégient les Conventional Commits avec scope, comme feat(payments): add Stripe webhook handler. Cela permet un filtrage par package et une meilleure attribution de responsabilité. Si vos scopes ne correspondent pas aux noms de packages ou de répertoires, les changelogs par package risquent d’être incomplets ou bruités ; alignez donc les scopes de commit avant de dépendre de l’automatisation.

Comment améliorer changelog-generator skill

Améliorer les entrées de changelog-generator avant la génération

Le moyen le plus rapide d’améliorer les résultats de changelog-generator est d’améliorer le flux de commits. Utilisez des types clairs, des scopes explicites et des objets pertinents pour les utilisateurs :

• Bon : fix(security): patch SQL injection vulnerability in reports
• Bon : feat(admin)!: redesign admin panel with role-based permissions
• Faible : fix stuff
• Faible : updates after review

Pour les breaking changes, ajoutez ! dans l’objet du commit et fournissez le contexte de migration dans le prompt s’il n’apparaît pas dans le corps du commit.

Éviter les modes d’échec courants

Les problèmes fréquents incluent l’oubli d’éléments de sécurité, la remontée excessive de tâches internes, des incréments semver incorrects et des puces de changelog qui décrivent des modifications de code plutôt que l’impact produit. Pour les limiter, demandez à l’agent de :

• exclure les commits purement chore, style ou test, sauf s’ils affectent les utilisateurs
• signaler explicitement les commits security, deprecated, remove et les breaking changes
• séparer « incrément de version recommandé » et « décision du release manager »
• inclure des notes de migration pour les breaking changes

Itérer après la première sortie

Considérez le premier changelog comme un brouillon structuré. Posez des questions de suivi comme :

• « Which bullets are not user-visible and should be removed? »
• « Which breaking changes need migration notes? »
• « Rewrite the Fixed section for customer-facing clarity. »
• « Return JSON with commit hash, category, scope, and final bullet for audit review. »

Cela préserve la traçabilité tout en améliorant la lisibilité.

Étendre la skill selon votre politique de release

Les équipes peuvent améliorer la skill en ajoutant leurs propres règles de release : types de commits autorisés, scopes obligatoires, labels de sévérité, ownership des packages ou modèles de changelog. Si vous publiez depuis la CI, enrichissez references/ci-integration.md avec votre job GitHub Actions ou GitLab CI réel. Si les hotfixes sont fréquents, personnalisez references/hotfix-procedures.md avec votre circuit d’approbation, vos déclencheurs de rollback et votre formulation SLA.