Rédiger un changelog (et des notes de version) que vos clients lisent

par Fraser Hardy

Des pull requests fusionnées qui traversent un filtre pour devenir un changelog daté, avec des entrées Nouveau, Amélioré et Corrigé

Vous avez livré une douzaine de choses le mois dernier. Votre changelog dit « Corrections de bugs et améliorations de performances ».

Les clients qui attendaient l’une de ces corrections n’ont aucune idée qu’elle est arrivée. Le prospect qui vous compare à un concurrent voit un produit qui semble ne pas avoir bougé depuis le printemps.

Voici comment rédiger un changelog que les gens lisent vraiment. Écrivez pour le client, pas pour la personne qui a fusionné le code. Datez chaque entrée. Regroupez les changements sous Nouveau, Amélioré et Corrigé. Commencez chaque entrée par ce que l’on peut désormais faire, ajoutez une ligne sur l’intérêt, et indiquez où le trouver. Laissez de côté tout ce qu’un client ne peut pas voir, et tout ce qui n’est pas encore en ligne. Puis publiez à un rythme régulier, même si certaines semaines sont courtes.

C’est l’essentiel. Le reste de cet article propose un modèle, une série d’exemples faibles et réussis, et une routine pour passer des pull requests fusionnées à des notes publiées sans que cela mange votre vendredi.

Changelog et notes de version : quelle différence ?

On emploie souvent les deux termes indifféremment, mais il y a en réalité deux publics.

Un changelog pour développeurs est généralement un fichier CHANGELOG.md dans le dépôt. Il s’adresse à ceux qui s’intègrent à votre API, votre SDK ou votre bibliothèque. Ils s’intéressent aux numéros de version, aux changements incompatibles et aux dépréciations. Keep a Changelog est la référence standard en la matière, et ses conventions sont sensées : le plus récent en premier, une section par version, des changements regroupés en Added, Changed, Deprecated, Removed, Fixed et Security, et une section « Unreleased » en haut pour le travail fusionné mais pas encore livré.

Les notes de version (ou « nouveautés du produit », ou page de changelog publique) s’adressent aux clients qui utilisent le produit. Ils se moquent que vous ayez mis à jour une dépendance. Ils veulent savoir ce qu’ils peuvent faire maintenant et qu’ils ne pouvaient pas faire la semaine dernière.

Si vous dirigez un produit SaaS, vous avez probablement plus besoin du second que du premier. Beaucoup d’équipes ont besoin des deux, et c’est très bien : une seule liste de travaux fusionnés peut alimenter deux rédactions. Ne publiez simplement pas la version pour développeurs en l’appelant notes de version.

Un modèle de notes de version à copier

Il convient à une mise à jour hebdomadaire ou bimensuelle du produit, sur une page de changelog, dans un widget intégré à l’application ou par e-mail.

## 6 October 2026

### New
**[What you can now do, in plain words]**
[One or two sentences: what it does and who it's for.]
Find it in **[Page > Section]**. [Link to help article]

### Improved
**[The thing that got better]**
[What's different from before, in terms the customer notices:
faster, fewer clicks, works on mobile, handles bigger files.]

### Fixed
- [Symptom the customer saw], now fixed.
- [Symptom the customer saw], now fixed.

### Heads up (only if needed)
**[Anything changing or going away]**
[What's happening, when, and what they need to do.]

Quelques règles pour que cela fonctionne :

Entrées de changelog faibles et réussies

Une mauvaise entrée de changelog rédigée comme des messages de commit, à côté d'une bonne entrée qui explique ce qui a changé pour le client et où le trouver

L’échec le plus courant est de coller des messages de commit. Voici ce que cela donne :

v2.14.0
- feat(export): csv async job
- fix: tz bug in reports
- refactor billing svc
- bump deps
- misc improvements

Tout y est vrai. Rien n’est utile à un client. Deux entrées sont du bruit interne, une ne veut rien dire (« misc improvements »), et les deux vrais changements sont écrits pour celui qui a relu la pull request.

Voici la même version, réécrite :

6 October

NEW: Big CSV exports run in the background
Exports over 10,000 rows no longer time out. Start the export
and we'll email you a link when the file is ready.
Find it in Reports > Export.

FIXED: Report dates now match your timezone
Daily totals were splitting at midnight UTC instead of your
local midnight, so some days looked short. They're correct now,
including for past reports.

Deux entrées au lieu de cinq. Chacune dit ce qui a changé, pourquoi le lecteur doit s’y intéresser et où regarder. La refactorisation et la mise à jour de dépendances ont disparu, car aucun client ne les remarquera.

Quelques paires de plus, car il faut un moment pour que ce schéma devienne une habitude :

FaibleRéussi
Ajout du SSOConnectez-vous avec Okta ou Google Workspace. Les administrateurs peuvent l’activer dans Paramètres > Sécurité.
Amélioration des performancesLe tableau de bord se charge bien plus vite sur les gros comptes. Les projets de plusieurs milliers d’éléments ne se figent plus au premier chargement.
Correction d’un bug de notificationVous ne recevrez plus d’e-mails en double quand quelqu’un vous mentionne deux fois dans un même commentaire.
Dépréciation des points d’accès v1L’API v1 cessera de fonctionner le 1er mars. Passez à la v2 d’ici là. Voici ce qui change.

Remarquez que « bien plus vite » reste vague. Si vous avez un chiffre mesuré, utilisez-le. Sinon, décrivez l’expérience plutôt que d’inventer un pourcentage.

Comment rédiger un changelog à partir des pull requests fusionnées

Workflow de changelog en cinq étapes : collecter les pull requests fusionnées, ne garder que les changements visibles par les clients et déjà en ligne, regrouper par type, réécrire pour le client, publier avec des liens

La plupart des équipes n’ont pas de mal avec la rédaction. Elles ont du mal à se rappeler ce qui a été livré. Voici une routine qui tient la route.

1. Collectez. Listez tout ce qui a été fusionné depuis la dernière entrée. Avec la CLI de GitHub :

gh pr list --state merged \
  --search "merged:>=2026-10-27" \
  --json number,title,labels,mergedAt,url \
  --limit 100

2. Filtrez. Pour chaque pull request, posez deux questions. Un client peut-il le voir ou le ressentir ? Est-ce réellement en ligne pour lui ? Les refactorisations internes, les modifications d’intégration continue et les corrections de tests sortent. Tout ce qui est derrière un drapeau de fonctionnalité non activé aussi. Annoncer un travail auquel les clients n’ont pas encore accès est pire que de ne pas l’annoncer, car vous recevrez des tickets « où est-ce ? ».

3. Regroupez. Classez ce qui reste en Nouveau, Amélioré et Corrigé. Plusieurs petites pull requests forment souvent une seule entrée (« Modification en masse » peut représenter quatre pull requests).

4. Réécrivez. Transformez chaque groupe en entrée à l’aide du modèle. L’avantage d’abord, des mots simples, l’endroit où le trouver.

5. Publiez et ajoutez des liens. Postez, reliez chaque nouvelle fonctionnalité à son article d’aide et diffusez partout où vos clients le verront.

L’astuce qui facilite beaucoup l’étape 4 est de demander la phrase destinée au client au moment de la pull request, tant que l’auteur se souvient de ce qu’il a construit. Ajoutez une section à .github/pull_request_template.md :

## Customer-facing change
<!-- One sentence a customer would understand, or "None". -->
<!-- e.g. "You can now export reports over 10,000 rows." -->

- [ ] Behind a feature flag (don't announce until it's on)
- [ ] Help articles checked

Cette dernière case compte. Chaque modification livrée qui touche l’interface peut rendre un article d’aide obsolète, et le changelog est un bon moment pour s’en apercevoir. Nous traitons cet aspect dans comment garder votre documentation à jour.

À quelle fréquence publier les nouveautés du produit ?

Calquez-vous sur votre rythme de livraison, dans la limite du raisonnable. Si vous livrez en continu, un récapitulatif hebdomadaire ou bimensuel se lit mieux qu’une entrée par déploiement. Si vous livrez chaque mois, publiez chaque mois.

Plus que la fréquence, c’est la régularité qui compte. Un changelog avec trois entrées en janvier et rien depuis dit aux visiteurs quelque chose que vous ne vouliez probablement pas dire. Une semaine courte, ce n’est pas grave. « Deux corrections cette semaine, une version plus importante la semaine prochaine » vaut mieux que le silence.

Les grands lancements méritent plus qu’une ligne de changelog : une vraie annonce, un e-mail, peut-être une courte vidéo. Le changelog est le journal courant, pas tout le plan marketing.

Où placer votre changelog

Des outils dédiés comme Beamer, Headway, LaunchNotes ou le changelog de Canny gèrent bien le widget et l’e-mail. Beaucoup d’équipes utilisent simplement une page de leur site de documentation. L’outil compte moins que l’habitude.

Où se place Ellie Docs

Transparence : c’est un problème pour lequel nous avons construit quelque chose. Ellie Docs surveille vos pull requests fusionnées et en tire des brouillons d’entrées de changelog, écrites pour les clients plutôt que pour les relecteurs. Il retient les entrées sur du travail non publié ou protégé par un drapeau, pour que vous n’annonciez pas des choses que les gens ne peuvent pas utiliser. Vous modifiez, écartez ou publiez chaque entrée. Rien ne part tout seul.

La vue changelog d'Ellie Docs avec des entrées lisibles par les clients rédigées à partir de pull requests fusionnées, chacune liée à l'article d'aide correspondant, prêtes à être modifiées ou publiées

Comme il maintient aussi votre centre d’aide, la même pull request qui produit une entrée de changelog produit une suggestion de mise à jour pour tout article devenu obsolète, présentée sous forme de diff que vous acceptez ou rejetez.

Une mise à jour suggérée d'un article d'aide après une pull request, affichée sous forme de diff rouge et vert avec les boutons Accept et Dismiss

Si votre changelog est aujourd’hui une liste de titres de commits, ou n’a pas été touché depuis le lancement, c’est le vide qu’il comble. Si vous êtes à l’aise pour l’écrire à la main, le modèle et la liste de contrôle des pull requests ci-dessus vous mèneront déjà loin.

Quelques questions fréquentes

Un changelog doit-il inclure les corrections de bugs ? Oui, celles que les clients ont remarquées. La correction d’un bug signalé par quelqu’un fait partie de ce que vous pouvez publier de plus lu, surtout si vous prévenez la personne qui l’a signalé. Laissez de côté les corrections de problèmes que personne hors de l’équipe n’a jamais vus.

Ai-je besoin de numéros de version ? Pour une API, un SDK ou tout ce qui s’installe, oui, et suivez le versionnage sémantique pour que chacun puisse juger du risque d’un coup d’œil. Pour une application web qui se déploie en continu, les dates sont plus claires. Les clients ne raisonnent pas en versions.

Quelle longueur pour une entrée de changelog ? Un titre en gras plus une à trois phrases. Si vous avez besoin de plus, rédigez un article d’aide ou un article de blog et faites un lien.

Vous voulez que votre changelog soit rédigé à partir des pull requests déjà fusionnées ? Essayez Ellie Docs gratuitement. Il existe une offre gratuite, sans carte bancaire.