Changelogs regroupés à partir de commits (et non de git log brut)

Pourquoi regrouper les commits est important

Lorsqu'un lecteur ouvre une note de version, il cherche ce qui a changé et qui l'affecte. Une longue liste de SHA-1 de commit et de messages courts oblige l'œil à sauter et à manquer l'essentiel. En regroupant les commits dans des catégories logiques, vous offrez au lecteur une carte rapide des nouvelles fonctionnalités, des corrections de bogues et des améliorations internes. Cette carte correspond à la façon dont les gens survolent : ils voient d'abord les titres, puis décident s'ils ont besoin des détails en dessous.

Attentes du lecteur

- Les sections de fonctionnalités répondent à « quoi puis-je faire maintenant? » - Les sections de corrections répondent à « quel problème a été résolu? » - Les sections d'améliorations répondent à « quoi s'est amélioré sans changer de comportement? »

Signal par rapport au bruit

- Les journaux bruts contiennent des commits de fusion, des corrections d'orthographe et du bruit de réorganisation. - Les journaux regroupés ne mettent en surface que l'intention qui compte pour les utilisateurs ou les équipes en aval. - La réduction du bruit réduit le temps nécessaire pour évaluer une version de minutes à secondes.

Mapping des commits conventionnels aux groupes

La spécification des commits conventionnels fournit un préfixe prévisible qui signale l'intention. En lisant le préfixe, vous pouvez décider à quel groupe un commit appartient sans parser le message complet.

Préfixes de balise

- feat : → groupe de fonctionnalités - fix : → groupe de correction de bogues - perf :, refactor :, style : → groupe d'amélioration - docs : → groupe de documentation (souvent omis des notes destinées aux utilisateurs) - test : → groupe de qualité interne

Balises personnalisées

- Les équipes peuvent ajouter security : pour mettre en évidence les correctifs qui résolvent les vulnérabilités. - breaking : peut être utilisé pour signaler les modifications d'API qui nécessitent une migration. - Tout préfixe supplémentaire doit être documenté dans le guide de contribution du projet afin que le générateur sache où le placer.

Algorithme : regroupement de commits par étiquettes sémantiques

Notre générateur suit un pipeline en trois étapes qui transforme un journal Git en un ensemble de groupes prêts à être examinés. Les étapes sont déterministes, donc la même entrée donne toujours la même sortie.

Étape 1 : analyse des messages de commit

- Exécutez git log --pretty=format:%s pour obtenir la ligne de sujet de chaque commit dans la plage. - Divisez le sujet au premier deux-points pour isoler le préfixe et la description. - Si aucun deux-points n'est présent, traitez le commit comme chore : et placez-le dans un seau interne qui est masqué du journal des modifications public.

Étape 2 : regroupement par préfixe

- Maintenez une carte des préfixes connus (feat, fix, perf, refactor, style, docs, test, security, breaking) vers une liste de commits. - Ajoutez chaque commit à la liste qui correspond à son préfixe. - Préservez l'ordre de commit d'origine à l'intérieur de chaque liste afin que les étapes ultérieures puissent afficher une vue chronologique.

Étape 3 : résolution des chevauchements

- Certaines équipes utilisent des préfixes combinés comme feat(parser) :. Nous supprimons les parenthèses et traitons la partie gauche comme le seau principal. - Si un commit correspond à plus d'un seau (rare, mais possible avec des alias personnalisés), nous l'affectons au premier seau correspondant de la liste de priorité : breaking > security > feat > fix > perf > refactor > style > docs > test > chore. - La sortie finale est un tableau ordonné de seaux, chacun contenant ses commits.

Étape | Entrée | Sortie 1 | sujets du journal Git | paires de préfixe + description 2 | paires de préfixe + description | seaux de commits 3 | seaux de commits | seaux ordonnés, dédoublonnés et prêts à être affichés

Pour voir comment l'algorithme fonctionne dans la pratique, vous pouvez l'essayer sur n'importe quel référentiel qui suit le format de commit conventionnel. Le générateur affichera les mêmes groupes que vous créeriez manuellement, mais en une fraction du temps.

Révision de l'interface utilisateur : aperçu et édition de groupes

Après que l'algorithme ait généré les buckets, l'utilisateur voit un aperçu où chaque bucket est une section pouvant être compressée. L'objectif est de permettre à l'auteur de vérifier que le regroupement automatique correspond à l'intention avant la publication du journal des modifications.

Édition en ligne

- Le clic sur une description de commit la transforme en un champ de texte éditable. - Les modifications sont enregistrées localement et peuvent être utilisées pour réaffecter un commit à un bucket différent en faisant glisser la ligne éditée. - Les descriptions éditées sont stockées comme des substitutions afin que les futures exécutions du générateur conservent le libellé choisi par l'homme.

Réorganisation par glisser-déposer

- Les buckets entiers peuvent être déplacés vers le haut ou vers le bas pour refléter le récit de version souhaité. - À l'intérieur d'un bucket, les commits individuels peuvent être réorganisés pour mettre en évidence le changement le plus important en premier. - L'interface utilisateur émette un correctif JSON qui enregistre le nouvel ordre ; ce correctif peut être validé avec le journal des modifications à des fins d'audit.

Ce que cela n'est pas

Il est important d'être clair sur les limites de l'outil pour que les équipes aient des attentes réalistes.

Aucune garantie d'exhaustivité

- Le générateur ne voit que ce qui se trouve dans la plage de validation que vous fournissez. - Si un changement est apporté en dehors du contrôle de version (par exemple, une modification manuelle de la configuration du serveur) il ne sera pas affiché. - Nous n'analysons pas les suiveurs de problèmes, les documents de conception ou les canaux de communication externes.

Pas de remplacement pour l'examen manuel

- Le regroupement automatique peut placer incorrectement un commit si le préfixe est ambigu ou manquant. - Les auteurs devraient toujours parcourir les notes générées pour détecter tout élément mal classé. - L'outil est destiné à réduire les efforts, et non à éliminer le besoin d'un contrôle humain.

Intégration CI/CD

Pour garder les journaux des modifications à jour, vous pouvez exécuter le générateur dans le cadre de votre pipeline. L'étape produit un fichier markdown qui peut être téléchargé en tant qu'artefact ou utilisé pour créer une version GitHub.

Exemple d'action GitHub

Ajoutez une étape à votre workflow qui vérifie le code, configure Node, exécute le générateur, puis crée une version avec le journal des modifications généré.

- utilise : actions/checkout@v4 - exécute : npm ci - exécute : npx ai-changelog-generator --from ${{ github.event.before }} --to ${{ github.sha }} --output CHANGELOG.md - utilise : softprops/action-gh-release@v2 - avec : - tag_name : ${{ github.ref_name }} - name : Version ${{ github.ref_name }} - body_path : CHANGELOG.md

Extrait de CI de GitLab

Dans.gitlab-ci.yml, ajoutez un travail qui exécute le générateur et stocke le journal des modifications en tant qu'artefact de travail.

- image : node:20 - variables : - GIT_STRATEGY : fetch

- npm ci - npx ai-changelog-generator --from $CI_COMMIT_BEFORE_SHA --to $CI_COMMIT_SHA --output CHANGELOG.md

- paths : - CHANGELOG.md

Les deux exemples utilisent le document public OWASP LLM Top 10 comme référence pour les validations de sécurité et le cadre de gestion des risques liés à l'IA de la NIST pour les validations qui touchent la sécurité du modèle. Vous pouvez les voir référencés en ligne :

- https://owasp.org/www-project-top-10-for-large-language-model-applications - https://www.nist.gov/itl/ai-risk-management-framework

Meilleures pratiques pour maintenir des changelogs regroupés

Même avec l'automatisation, quelques habitudes permettent de garder la sortie utile tout au long de la vie d'un projet.

Hygiène des commits

- Commencez toujours un message de commit par un préfixe conventionnel. - Si un commit touche plusieurs domaines, divisez-le en commits séparés afin que chacun ait une intention claire. - Incluez une brève description après les deux points qui explique l'impact visible pour l'utilisateur.

Révision régulière du groupe

- Avant chaque version, ouvrez le changelog généré et vérifiez que chaque seau contient les commits attendus. - Si vous voyez un commit dans le mauvais seau, éditez la description ou ajoutez un préfixe personnalisé pour guider le générateur. - Faites de l'habitude de mettre à jour le guide de contribution chaque fois que vous ajoutez un nouveau préfixe personnalisé afin que les futurs contributeurs connaissent la convention.

Liste de contrôle de l'opérateur pour les changelogs regroupés à partir des commits (et non du journal git brut)

Je garde une liste de contrôle écrite à côté de chaque version qui touche ce sujet. La liste est ennuyeuse par intention : nommer le propriétaire, nommer l'artefact de preuve et nommer la restauration. Si une étape ne peut pas produire un fichier, un ticket ou une ligne de journal, ce n'est pas une étape - c'est un vœu.

Avant de modifier la production

- Geler la branche ou la révision de configuration que vous allez mesurer. - Enregistrer le mode d'échec actuel avec une entrée concrète et une sortie concrète. - Confirmer l'identité sous laquelle s'exécute le travail et si cette identité peut accéder à des données qu'elle ne devrait pas. - Ouvrir les références principales que vous allez citer : https://owasp.org/www-project-top-10-for-large-language-model-applications, https://www.nist.gov/itl/ai-risk-management-framework.

Pendant que vous exécutez la vérification

- Préférer un chemin reproductible à dix captures d'écran anecdotiques. - Écrire le résultat sécurisé attendu avant de déclencher l'outil ou la requête. - Capturer la commande exacte, l'invite, le schéma ou l'expression régulière sous test - et non une paraphrase. - Si le système peut agir (envoyer, écrire, supprimer, transférer), exiger une limite de confirmation dans le même passage.

Après avoir terminé

- Enregistrer le risque résiduel avec un propriétaire et une date, même si l'analyse est propre. - Ne pas convertir un contrôle vert en langage de vente qui prétend être complet. - Réexécuter la même liste de contrôle lorsque le modèle, le schéma de l'outil ou les règles de validation changent.

Signal | Qu'enregistrer | Arrêter l'expédition? Écriture ou envoi inattendu | Nom de l'outil, arguments, identité | Oui jusqu'à ce que cela soit géré Action destructive manquante | Chemin d'appel et contournement | Oui Texte non fiable traité comme instruction | Surface source et action résultante | Oui pour la portée de l'agent Analyseur propre, jugement ouvert | Éléments différés + propriétaire | Seulement si le chemin principal est sécurisé

ai-changelog-generator aide pour le premier passage mesurable. Les choix d'architecture, la validation légale et les allégations orientées client nécessitent toujours un propriétaire humain. Traitez chaque ligne de la liste de contrôle comme un support de décision, et non comme un certificat.

Comment j'explique les limites aux acheteurs

Lorsqu'un prospect me demande si le produit "couvre tout", je réponds avec la limite : les vérifications automatisées détectent les modèles connus ; les chaînes nouvelles et le jugement politique nécessitent toujours un examen. Cette honnêteté permet de réduire la charge de support et de garder le blog aligné sur ce que le produit fait réellement.

Si vous avez besoin d'un second avis, associez ce texte aux références ci-dessous et à votre propre reproduction de staging. Ne sautez pas l'étape de reproduction simplement parce qu'un modèle a rédigé un résumé confiant.

Références

- https://owasp.org/www-project-top-10-for-large-language-model-applications - https://www.nist.gov/itl/ai-risk-management-framework

Les informations fournies sont conformes aux exigences de l'UE sur le règlement général sur la protection des données (RGPD) et prennent en compte les directives de l'OWASP pour les applications de modèles de langage à grande échelle.

Lectures connexes

- Prérégulations de tonalité pour les développeurs et les clients pour les mêmes validations — Changelog AI - La matrice de sujets de micro-SaaS LX AI