Préréglages de ton pour les développeurs et les clients pour les mêmes validations

Pourquoi des présélections de ton séparées?

J'ai démarré ce projet parce que j'ai vu des équipes perdre du temps à réécrire la même entrée de journal des modifications pour deux lecteurs différents. Les ingénieurs doivent voir ce qui a changé dans le code, quels fichiers ont été modifiés et les API internes cassantes. Les responsables de produits, le personnel de support et les utilisateurs finaux se soucient de ce que le changement signifie pour eux : nouvelles fonctionnalités, bogues corrigés, performances améliorées ou limites supprimées. Un seul ton ne peut pas servir les deux groupes de manière efficace. En créant deux présélections distinctes qui opèrent sur la même liste de commits, nous gardons la source de vérité inchangée tout en livrant des messages adaptés. Cette approche permet également au libellé SemVer de rester la seule source de sens contractuel, car le libellé est attaché au groupe de commits, et non à la formulation.

Préset de ton du développeur : détail premier

Détail au niveau du commit

Lorsque le préset de développeur est actif, l'IA étend chaque commit en une phrase qui inclut le chemin du fichier, la fonction ou la classe modifiée et la nature du changement (ajout, suppression, refactoring). Par exemple, un commit qui corrige un pointeur null dans src/api/user.go devient : « Correction d'une référence de pointeur null dans GetUserByID lorsque l'ID entrant est nul, ajout d'une clause de garde et d'un test unitaire. »

Liens vers les systèmes de suivi

Si le message de commit contient un ID de problème (par exemple, ABC-123), le préset l'entoure d'un lien vers le suivi, en supposant que l'équipe a configuré l'URL de base. Cela permet aux ingénieurs de passer directement à la discussion ou au document de conception sans quitter le journal des modifications.

Inclusion du contexte technique

Le préset ajoute tous les avertissements de compilateur pertinents, les modifications de couverture de test ou les deltas de benchmark de performances qui sont apparus dans l'exécution CI associée au commit. Cela donne un contrôle de santé rapide pour la zone modifiée.

Vérifications de sécurité et de conformité pour la sortie LLM

Puisque le texte est généré par un modèle de langage, je le fais passer par un filtre de sécurité léger qui vérifie le contenu interdit. Le filtre fait référence à la liste OWASP LLM Top 10 pour les risques d'injection de invites et au cadre de gestion des risques AI de NIST pour les conseils sur la gestion des hallucinations et des préjugés. Si un segment déclenche une règle, il est marqué pour examen humain avant publication.

Liste d'exemples pour une version typique

- Ajout de l'interface RetryPolicy dans src/retry/policy.go pour permettre des stratégies de réessai modulaires. - Suppression de la structure LegacyCache obsolète de src/cache/legacy.go ; tous les appelants migrés vers LRUCache. - Correction d'une condition de course dans WorkerPool.Start où un canal nil pouvait être fermé deux fois ; ajout d'un gardien de mutex. - Mise à jour du module Go github.com/stretchr/testify de la version 1.7.0 à la version 1.8.2 pour intégrer la correction de sécurité pour le package assert. - Ajout de benchmarks pour JSONEncoder montrant une réduction de 12 % de la taille d'allocation pour les charges utiles inférieures à 10 Ko.

Préset de ton du client : avantages en premier

Langage axé sur les résultats

Avec le préset du client, l'IA réécrit chaque commit en une phrase qui décrit ce que l'utilisateur peut désormais faire ou quel problème est résolu. Le jargon technique est remplacé par des termes simples. La même correction de pointeur nul devient : « Les utilisateurs ne verront plus d'erreur lorsqu'ils saisissent une ID à valeur nulle dans le champ de recherche d'utilisateur. »

Éviter les identificateurs internes

Les hachages de commit, les noms de branche et les numéros de problème internes sont omis, sauf s'ils font partie d'un indicateur de fonctionnalité public ou d'un point de terminaison d'API versionné que les clients pourraient référencer. L'objectif est de maintenir le bruit au minimum.

Mettre en évidence l'impact sur l'utilisateur

Si un commit améliore les performances, le préset traduit le gain de benchmark en une déclaration visible par l'utilisateur : « Les temps de chargement de page sont maintenant jusqu'à 15 % plus rapides sur les appareils mobiles. » Si un commit supprime une limite, il indique : « Vous pouvez maintenant télécharger des fichiers jusqu'à 100 Mo au lieu de la limite précédente de 25 Mo. »

Lien vers la documentation publique

Lorsqu'un changement touche un point de terminaison d'API public ou une option de configuration, le préset ajoute un lien à la section de documentation pertinente, en supposant que le site de documentation suive un modèle d'URL prévisible (par exemple, https://docs.example.com/api/v2/users).

Liste d'exemples pour la même version

- La logique de nouvelle tentative s'adapte maintenant aux glitches réseau temporaires, réduisant les téléchargements échoués sur les connexions instables. - L'ancienne implémentation du cache a été supprimée ; le nouveau cache utilise moins de mémoire et supprime automatiquement les entrées obsolètes. - Correction d'une erreur rare qui pouvait survenir lorsque de nombreux travailleurs commençaient en même temps. - Bibliothèque tierce mise à jour pour répondre à un avis de sécurité ; aucune action n'est requise de votre part. - Les réponses JSON sont maintenant plus légères, ce qui réduit l'utilisation des données sur les connexions mesurées.

De la différence de commit à deux récits

Analyse et regroupement

Le pipeline commence par l'exécution de git log --pretty=format:%H %s %b --since="il y a 1 semaine" pour collecter les commits depuis le dernier tag. Chaque commit est analysé pour son type de commit conventionnel (feat, fix, perf, refactor, etc.) et sa portée. Les commits avec le même type et implication de version SemVer sont regroupés ensemble car ils partageront le même incrément de version.

Application de prompts spécifiques au ton

Pour chaque groupe, je crée deux prompts : un réglé pour le preset de développeur, un pour le preset de client. Le prompt de développeur demande une « description détaillée et technique qui inclut les noms de fichiers, les symboles et les modifications de tests ou de benchmarks pertinentes ». Le prompt de client demande une « explication concise et orientée vers les avantages qui évite le jargon interne et se concentre sur ce que l'utilisateur expérimente ». La même liste de commits alimente les deux prompts, garantissant que les faits sous-jacents restent identiques.

Révision humaine

La sortie de l'IA atterrit dans un éditeur de brouillon où un responsable de maintenance peut accepter, modifier ou rejeter chaque phrase. J'ai constaté que la plupart des modifications sont des ajustements mineurs de formulation plutôt que des modifications factuelles, ce qui montre que le modèle est bon pour rester fidèle à la différence de source. Après révision, le brouillon est rendu en Markdown, puis en HTML pour publication.

Tableau : mappage des types de commit conventionnels sur les phrases de ton

Type de commit | Exemple de formulation de développeur | Exemple de formulation de client feat | Ajout de la méthode ExportCSV à ReportService qui transmet les lignes pour réduire l'utilisation de la mémoire. | Vous pouvez maintenant télécharger des rapports au format CSV directement à partir du bouton d'exportation. fix | Résolution d'un blocage dans JobQueue.Push lorsqu'un travail nil est mis en file d'attente sous charge élevée. | Les travaux ne seront plus bloqués lorsque le système est occupé. perf | Remplacement de la recherche O(n²) dans TagIndex.Find par une carte de hachage, réduisant la latence de 12 ms à 0,8 ms pour 10 000 balises. | Les recherches de balises sont maintenant nettement plus rapides, en particulier avec de grandes bibliothèques. refactor | Extraction de l'interface PasswordValidator de AuthHandler pour permettre des règles de force pluggables. | Les exigences de mot de passe peuvent maintenant être ajustées sans modifier le code de connexion de base. docs | Mise à jour d'API.md avec la nouvelle description et la charge utile d'exemple de l'endpoint PATCH /users/:id. | Le centre d'aide affiche maintenant la façon de mettre à jour partiellement un profil d'utilisateur.

Préservation du sens de SemVer à travers les tons

Les règles de version restent ancrées aux commits

L'étiquette SemVer est déterminée uniquement par les types de commits conventionnels dans le groupe : une fonctionnalité déclenche une augmentation mineure, une correction un correctif, et un changement de rupture une augmentation majeure. Puisque les préreglages de ton ne modifient pas les messages de commit ou leurs types, le numéro de version résultant est identique que vous lisiez la version développeur ou la version client.

Consistance du contrat

Je traite l'étiquette SemVer comme le contrat entre le producteur et le consommateur du logiciel. Le journal des modifications n'est qu'une expression lisible par l'homme de ce contrat. En gardant le contrat intact, les équipes peuvent compter sur des outils automatisés (comme des bots de publication ou des vérificateurs de dépendances) pour interpréter correctement la version, tandis que le journal des modifications à double ton sert les deux publics sans créer d'ambiguïté.

Exemple d'une version majeure

Supposons qu'un commit ajoute BREAKING CHANGE : supprimer l'API v1 héritée. Le préreglage développeur notera les suppressions de fichiers exactes et les étapes de migration requises. Le préreglage client expliquera que le point de terminaison de l'API ancien n'est plus disponible et dirigera les utilisateurs vers la documentation v2. Dans les deux cas, la version passe de 2.4.1 à 3.0.0, en préservant le sens contractuel.

Ce que cela n'est pas

Je veux être clair sur les limites de cette approche pour que vous puissiez avoir des attentes réalistes.

- Cela ne garantit pas que chaque phrase générée sera parfaite en termes de ton ; des expressions trop techniques peuvent parfois apparaître dans le brouillon client, ou un langage vague peut apparaître dans le brouillon du développeur. Une révision humaine est toujours nécessaire. - Ce n'est pas un remplacement à 100 % pour un rédacteur technique dédié ou un marketeur de produit. L'IA accélère le premier jet, mais la nuance, la voix de la marque et les mentions légales nécessitent toujours une touche humaine. - Cela n'élimine pas la nécessité d'une hygiène de commit claire. Si les messages de commit sont vagues ou manquent de structure de commit conventionnelle, les groupes seront moins précis et la sortie sera moins utile. - Ce n'est pas un outil magique qui satisfera automatiquement tous les régulateurs ou les lignes directrices d'accessibilité. Les vérifications de sécurité que j'ai ajoutées sont de base ; vous devriez toujours effectuer votre propre examen de conformité. - Cela ne promet pas que le journal des modifications ne manquera jamais un changement. Si un commit est omis de la plage de journal git (par exemple, en raison d'un clone superficiel ou d'un filtre erroné), il n'apparaîtra pas dans l'un ou l'autre ton.

Références

- OWASP LLM Top 10 - Cadre de gestion des risques liés à l'IA de NIST

Lectures associées

- Les journaux de modifications regroupés à partir de validations (et non du journal git brut) — Changelog AI - La matrice de sujets LX AI Micro-SaaS