Notes de version automatisées à partir des commits et des captures d'écran : un flux simple pour transformer de courtes notes de PR et des captures UI en changelogs clairs avec moins d'édition manuelle.
Les notes de version sont une de ces tâches que tout le monde reconnaît comme utiles, mais elles sont souvent repoussées à la fin de la semaine quand l'énergie est faible. Après quelques sprints chargés, elles se transforment en un paragraphe expédié ou sont carrément passées sous silence.
Une partie du problème vient du timing. Les détails se trouvent dans les commits, les fils de PR et les messages de chat rapides. Quand vous vous asseyez pour rédiger un changelog, vous essayez de vous souvenir pourquoi un changement comptait, qui il aidait et ce qu'un utilisateur remarquera réellement.
Il y a aussi un décalage de langage. Les développeurs écrivent des choses comme « refactor auth middleware » ou « fix race in cache », mais les utilisateurs veulent lire « La connexion est plus fiable » ou « Les pages se chargent plus vite sur des connexions lentes ». Traduire un travail technique en langage utilisateur demande de la concentration, et c’est difficile quand on change constamment de contexte.
La dérive de formatage aggrave la situation. Une semaine vous écrivez des puces, la suivante des paragraphes. Une personne ajoute des emojis et une autre met des identifiants de ticket. Avec le temps, le changelog perd en fiabilité parce que les lecteurs ne peuvent plus le scanner rapidement ou comparer les versions.
La bonne nouvelle : vous produisez déjà la plupart des éléments bruts. Une description de PR courte plus une ou deux captures d'écran UI contiennent généralement tout ce dont vous avez besoin. L'objectif n'est pas d'écrire un roman. C'est de produire des notes cohérentes et compréhensibles avec moins de travail manuel.
Une approche simple fonctionne le mieux :
Pour obtenir des notes de version qui paraissent cohérentes, clarifiez les entrées que vous avez déjà. La plupart des équipes disposent de suffisamment de détails. Ils sont simplement dispersés.
Un commit est l'unité la plus petite : un enregistrement technique de ce qui a changé dans le code. Les messages de commit sont utiles pour retracer le travail, mais ils disent souvent des choses comme « fix lint » ou « refactor header », ce qui n'est pas ce qu'un client veut lire.
Une description de PR (pull request) fait le pont. Elle explique pourquoi le changement existe, ce que le relecteur doit vérifier et ce qui a changé du point de vue produit. Si vous voulez des notes de version automatisées, les descriptions de PR sont généralement la meilleure matière première parce qu'elles peuvent être rédigées en langage clair sans être longues.
Les titres d'issue (ou titres de ticket) ajoutent un autre indice : ils nomment le problème résolu. Quand les PR référencent des issues, vous obtenez un fil propre du « problème signalé » à la « correction livrée ».
Une capture UI (screenshot ou image annotée courte) est un enregistrement visuel de ce que l'utilisateur verra réellement. Ce n'est pas de la décoration. C'est une preuve et du contexte.
Les sorties des notes de version se divisent généralement en deux types :
Différents publics lisent ces notes pour des raisons différentes. Les clients veulent savoir ce qui a changé pour eux aujourd'hui. Le support doit savoir à quoi s'attendre et quoi dire aux utilisateurs. Les équipes de vente et de customer success cherchent ce qui est nouveau et mérite d'être mentionné. Les équipes internes ont besoin d'un historique de ce qui a été livré et de ce qui pourrait casser.
Les captures d'écran sont les plus utiles quand elles vous aident à faire trois choses : confirmer que le changement est réel, vous rappeler les libellés et noms de boutons exacts, et montrer un avant/après d'une façon que le texte ne peut pas rendre.
Un bon changelog consiste moins à écrire qu'à trier. Si la structure reste la même à chaque publication, vous pouvez transformer de petites notes de PR en notes de version sans repenser le format à chaque fois.
Choisissez 4 à 6 catégories qui correspondent à la façon dont les utilisateurs parlent de votre produit. Trop de catégories vous ralentissent et créent des piles « divers ».
Un ensemble pratique est :
« Admin » est utile quand les changements affectent les propriétaires, la facturation, les rôles ou les paramètres. Si votre produit s'adresse aux développeurs, vous pouvez le remplacer par « API ». Gardez les noms stables pour que les lecteurs apprennent où regarder.
Tracez une ligne claire entre ce qui est visible par l'utilisateur et ce qui est interne. Une règle simple : si un utilisateur peut le remarquer, le rechercher ou s'y fier, cela appartient aux notes de version. Si ce n'est qu'un refactoring, une montée de dépendance ou un changement de logs, laissez-le de côté sauf si le comportement change.
Choisissez un modèle de phrase et tenez-vous-y. Cela empêche les descriptions de PR de se transformer en mini-essais et garde les notes finales faciles à scanner.
Un modèle fiable est :
Ce qui a changé + qui cela affecte + où le trouver.
Par exemple : « Added two-factor login for workspace owners in Settings. » Même si vous ajustez ensuite le ton, l'entrée brute reste cohérente.
Un petit glossaire aide plus que la plupart des équipes ne l'imaginent. Choisissez un terme pour chaque concept clé et n'utilisez pas de synonymes (par exemple, dites toujours « workspace », pas parfois « project » et parfois « team space »). Une formulation cohérente donne l'impression d'une seule voix, pas de cinq.
La façon la plus simple d'obtenir des notes de version automatisées est de traiter chaque PR comme une petite histoire orientée utilisateur. Si quelqu'un extérieur à votre équipe peut lire le titre de la PR et comprendre ce qui a changé, vous avez fait la majeure partie du chemin.
Commencez par le titre de la PR. Faites-en une phrase claire en langage simple, axée sur le résultat, pas l'implémentation. Comparez « Add caching layer to search » avec « Search results load faster. » La seconde peut être copiée directement dans un changelog.
Gardez la description de la PR courte (2 à 5 lignes), mais faites en sorte que chaque ligne ait un objectif :
Les tags aident plus tard lors du tri d'une semaine de changements. Utilisez des crochets cohérents comme [UI], [API], [Billing], [Performance]. Un ou deux tags suffisent. Trop de tags deviennent du bruit.
Ajoutez une ligne unique « Impact utilisateur » qui se lit comme une note de version. Par exemple : « Admins can now export invoices as CSV. » Cette ligne est de l'or lorsque vous compilez des mises à jour sous pression.
Les captures appartiennent à la description de PR uniquement quand l'UI a changé. Utilisez une capture avant et une après, recadrées sur la zone modifiée. Si rien de visible n'a changé, sautez les captures et écrivez une phrase supplémentaire expliquant la différence.
Voici un modèle simple de description de PR que vous pouvez coller dans votre template :
[UI] Faster search results
Intent: Reduce wait time on the search page.
User impact: Everyone sees results in under 1 second for common queries.
Edge cases: Empty search now shows “Try a different keyword”.
Les captures d'écran peuvent vous faire gagner des heures quand vous rédigez les notes de version, mais seulement si elles sont faciles à trouver et à comprendre. Une pile aléatoire d'images nommées « Screenshot 12 » se transforme en travail fastidieux.
Commencez par un schéma de nommage simple pour pouvoir rechercher plus tard. Une option est YYYY-MM-DD_area_feature_state. Par exemple : 2026-01-14_billing_invoices_empty.png. Quand quelqu'un demande « Quand avons-nous changé cet écran ? », vous pouvez répondre en quelques secondes.
Capturez l'état qui raconte l'histoire. Le « happy path » n'est pas toujours le plus utile. Si une mise à jour modifie un comportement, montrez le moment où l'utilisateur le remarquera.
Visez 1 à 3 captures par changement. Les plus utiles sont souvent :
Gardez les annotations légères. Si la capture a besoin d'aide, ajoutez une flèche ou une mise en évidence. Évitez les paragraphes sur l'image. Mettez l'explication dans la description de la PR, où elle peut être réutilisée dans le changelog.
L'endroit où vous stockez les captures compte autant que ce que vous capturez. Sauvez-les à côté de la PR (ou dans un dossier partagé) et incluez l'ID de la PR dans le nom de fichier ou la légende. Exemple : « PR-1842: updated checkout error message. »
Une petite habitude qui rapporte : quand vous changez le texte UI, l'espacement ou le contraste, ajoutez une note d'une ligne comme « Amélioration du contraste du bouton pour la lisibilité. » Cette ligne devient souvent une note de version propre sans réécriture.
Vous n'avez pas besoin d'un système sophistiqué pour obtenir des notes de version fiables. Il vous faut une petite habitude : chaque PR fusionnée doit contenir une note courte orientée utilisateur, et chaque changement d'UI doit avoir une capture qui lui correspond.
Choisissez une fenêtre de publication (par exemple, lundi à vendredi). Rassemblez les titres et descriptions des PR fusionnées pendant cette fenêtre dans un document de brouillon. Si une PR n'a pas de description claire, ne devinez pas. Demandez à l'auteur d'ajouter une ligne tant que le contexte est frais.
Associez les captures aux PR qui ont modifié l'UI. Une capture par changement visible suffit généralement. Étiquetez-les pour qu'il soit évident ce qu'elles montrent (avant/après aide quand la différence est subtile).
Puis faites une passe de nettoyage rapide :
Terminez par une relecture rapide. Partagez le brouillon avec le support ou le produit et posez une question : « Un client comprendrait-il ce qui a changé et pourquoi c'est important ? » Si la réponse est non, simplifiez les mots ou ajoutez un petit contexte.
Par exemple, au lieu de « Refactored permissions middleware », écrivez « Vous pouvez désormais gérer les rôles d'équipe depuis la page Paramètres. »
Les entrées brutes (messages de commit, notes de PR et captures) sont écrites pour des coéquipiers. Les notes de version sont écrites pour des utilisateurs. Le travail consiste à traduire, pas à faire un copier-coller.
Quelques règles de rédaction gardent chaque entrée claire :
La cohérence compte plus qu'une formulation parfaite. Choisissez un temps (la plupart des équipes utilisent le passé : « Fixed », « Improved », « Added ») et tenez-vous-y. Utilisez les mêmes règles de capitalisation. Si vous nommez des fonctionnalités, gardez un seul format, par exemple « Nom de la fonctionnalité (zone) » comme « Saved views (Reports) ». Ces petites règles empêchent le changelog de paraître brouillon.
Quand quelque chose va interrompre un utilisateur, dites-le clairement et donnez la prochaine étape. Évitez la cause technique.
Exemple : « Les clés API créées avant le 10 janv. cesseront de fonctionner. Créez une nouvelle clé dans Paramètres - API keys. »
Ajoutez une section « Problèmes connus » seulement quand les utilisateurs risquent de la rencontrer. Restez concis et fournissez un contournement si vous en avez un.
Exemple : « Problème connu : l'export CSV peut expirer sur de très grands rapports. Contournement : exporter par plage de dates. »
Les captures doivent mériter leur place. Ajoutez-en une quand elle aide les utilisateurs à repérer un nouveau contrôle, un bouton déplacé ou un nouvel écran. Gardez les captures internes quand le changement est mineur (espacements, couleurs, petites corrections de texte) ou quand l'UI est susceptible d'évoluer avant la prochaine version.
La plupart des problèmes de notes de version apparaissent une semaine après le déploiement. Quelqu'un demande « Ce changement était-il volontaire ? » et vous vous retrouvez à fouiller les PR, captures et fils de discussion. Si vous voulez que les notes automatisées restent utiles, évitez les pièges qui rendent les notes difficiles à lire et à croire.
Ces modèles provoquent le plus de retouches :
Les petits changements d'UI sont une autre absence fréquente. Un bouton renommé, un menu déplacé ou un nouvel état vide peut semer plus la confusion qu'un refactor de backend. Si une capture a changé, mentionnez-le, même brièvement. Une ligne simple comme « Le bouton Export a été déplacé en haut à droite du tableau » évite beaucoup d'échanges.
Voici un exemple rapide. Vous livrez une nouvelle mise en page de la page de facturation et vous restreignez aussi qui peut modifier les factures. Si vous ne notez que « Improved billing page », les admins supposeront qu'aucun autre changement n'a eu lieu. Mieux vaut séparer : une ligne pour la mise en page, une ligne pour le changement de rôle, en nommant le rôle.
De bonnes notes de version ne sont pas plus longues. Elles sont plus claires et tiennent mieux dans le temps.
Une bonne note de version répond vite à trois questions : qu'est-ce qui a changé, où le voir et pour qui c'est important. Avant de publier, faites une dernière passe avec des yeux frais.
Lisez chaque item comme si vous étiez l'utilisateur, pas le concepteur. Si vous devez deviner ce que cela signifie, réécrivez.
Après la checklist, faites une lecture « traduction ». Remplacez les mots internes (IDs de ticket, noms de composants, feature flags) par des termes que les utilisateurs reconnaissent. Si une fonctionnalité est derrière un déploiement progressif ou disponible seulement sur certains paliers, dites-le clairement.
Demandez à une personne hors ingénierie de lire. Ça peut être un fondateur, une personne du support, de la vente ou un ami. Si elle ne peut pas répondre à « Qu'est-ce qui a changé ? » en 10 secondes, le texte est encore trop proche de la PR.
Exemple : « Improved settings modal state handling » devient « Les paramètres s'enregistrent maintenant de façon fiable après un changement d'onglet. »
Une petite équipe pousse 12 PR en une semaine : 4 retouches UI, 2 corrections de bugs, le reste sont de petits refactors et tests. Ils veulent des notes automatisées, mais qui ressemblent à quelque chose d'écrit par un humain.
Au lieu d'attendre vendredi, ils collectent les entrées en travaillant. Chaque PR inclut une ligne « orientée utilisateur » et, si l'UI a changé, une capture avant/après unique. Les captures sont stockées à côté des notes de PR (au même endroit à chaque fois), donc personne ne doit fouiller les fils de discussion plus tard.
Le vendredi, une personne parcourt les notes de PR et groupe les changements similaires. Quatre petites retouches UI deviennent une puce orientée utilisateur, et trois refactors internes disparaissent parce que les utilisateurs s'en fichent.
Voici à quoi ressemble le changelog hebdomadaire publié après regroupement et réécriture :
Les réécritures sont là où la plupart des équipes récupèrent du temps. Une note de PR comme « Refactor billing-summary component, rename prop, update tests » devient « Improved the Billing page layout and labels for clearer totals. » Une autre comme « Fix N+1 query in projects list » devient « Improved dashboard load time when you have many projects. »
Les captures évitent la confusion quand le libellé change. Si un bouton passe de « Archive » à « Deactivate », l'image rend évident ce que verront les utilisateurs et le support n'a pas à deviner à quel écran se réfère la note.
La plus grande différence entre « on a essayé une fois » et des notes de version qui tiennent est une petite routine. Désignez une personne responsable des notes pour chaque fenêtre de publication et donnez-lui un créneau fixe de 30 minutes. Quand il y a un propriétaire et un créneau temporel, cela cesse d'être le problème de tout le monde.
Intégrez votre template de PR et les règles de capture dans le travail normal, pas comme un processus spécial. Si une PR n'a pas la phrase « impact utilisateur » ou la capture avant/après, ce n'est pas de la « finition ». Il manque des informations.
Un document de brouillon léger est un facilitateur d'habitude. Gardez un brouillon courant pour la release en cours et mettez-le à jour au fur et à mesure que les PR sont fusionnées, tant que le contexte est frais. Le jour de la release devient de l'édition, pas de l'écriture depuis zéro.
Un rythme simple qui fonctionne bien :
Si le formatage prend encore trop de temps, construisez un petit générateur de brouillon interne. Il peut lire le texte des PR, appliquer vos rubriques et produire un brouillon propre qui ne nécessite qu'une relecture légère. Commencez petit : regrouper par rubrique et apporter les légendes des captures suffit souvent.
Si vous voulez prototyper ce genre de générateur via un chat, Koder.ai est une option. Vous pouvez itérer rapidement sur l'invite et le format de sortie, puis exporter le code source quand vous êtes prêt à le maintenir en interne.
Utilisez surtout les titres et descriptions des PR, car ils incluent généralement le « pourquoi » et l'impact pour l'utilisateur. Les commits sont utiles pour retracer les changements de code, mais ils ne sont pas rédigés pour être lus par des clients.
Rédigez le titre en langage simple, centré sur le résultat que l'utilisateur remarquera. S'il peut être copié dans un changelog avec peu de modifications, il remplit son rôle.
Courte et cohérente : ce qui a changé, qui est affecté, et où le trouver. Cela évite les notes vagues et facilite la lecture.
Choisissez 4 à 6 catégories stables que les utilisateurs reconnaissent, par exemple New, Improvements, Fixes, Security et Admin. Garder les mêmes catégories chaque fois réduit la dérive de format et accélère le tri.
Incluez tout ce que l'utilisateur peut remarquer, rechercher ou utiliser. Les refactorings purs, les montées de dépendances et les changements de logs doivent rester dans un changelog interne sauf s'ils modifient un comportement.
Ajoutez des captures d'écran uniquement si l'interface a changé et que l'image réduira la confusion, par exemple un bouton déplacé, un libellé renommé ou une nouvelle étape d'un flux. Une capture claire (ou une paire avant/après) suffit généralement.
Utilisez un schéma de nommage constant et indexable qui inclut la date et la zone du produit. Ajoutez l'identifiant de la PR dans le nom de fichier ou la légende pour pouvoir retracer rapidement le changement.
Indiquez d'abord l'impact puis dites ce que les utilisateurs doivent faire ensuite. Évitez d'expliquer la cause technique et soyez explicite sur l'endroit où effectuer la modification.
N'ajoutez les « problèmes connus » que si les utilisateurs sont susceptibles de les rencontrer bientôt, et restez concis. Si vous avez un contournement, indiquez-le clairement pour que le support et les utilisateurs puissent agir.
Traitez chaque PR fusionnée comme une petite histoire orientée utilisateur, puis compilez les notes des PR fusionnées sur une fenêtre donnée et regroupez-les dans vos catégories fixes. Les outils peuvent aider à formater, mais gardez une relecture humaine rapide pour enlever les doublons et vérifier le vocabulaire.