Changelog vs release notes : quelle est la différence ?
6 min de lecture mis à jour le
Un changelog est un registre continu et cumulatif de tout ce qui a changé, écrit pour quelqu’un qui cherche quelque chose. Les release notes sont un message trié sur une version, écrit pour quelqu’un qui décide si ça le concerne. La différence est l’audience, pas le format, et la plupart des équipes ont besoin des deux : l’un comme référence, l’autre comme annonce, dérivés des mêmes entrées.
La plupart des équipes finissent avec l’un par accident et l’autre sur demande. Vous commencez par un changelog parce qu’un développeur veut un registre de ce qui a été livré. Des mois plus tard, quelqu’un du support demande pourquoi les clients ne savaient pas qu’une fonctionnalité est en production depuis avril, et maintenant il vous faut des release notes.
Changelog vs release notes, côte à côte
| Changelog | Release notes | |
|---|---|---|
| Lecteur | Quelqu’un qui cherche quelque chose | Quelqu’un qui décide si ça le concerne |
| Portée | Tout ce qui a changé | Ce qui vaut la peine d’être dit sur cette version |
| Cadence | Continue, par merge ou par version | Par version, et seulement celles qui méritent d’être annoncées |
| Ton | Concis, factuel, souvent impératif | Explicatif, parfois persuasif |
| Durée de vie | Permanente, lue des années plus tard | Lue la première semaine, puis archivée |
| Vit dans | Le repo, un site de docs, une page /changelog | Email, in-app, un article de blog, une page de version |
| Échoue par | Être incomplet | Être ennuyeux, ou arriver après coup |
Qu’est-ce qu’un changelog ?
Un changelog est un registre chronologique, quasi complet, de ce qui a changé, le plus récent en premier, avec chaque entrée typée (added, changed, deprecated, removed, fixed, security) et datée. Son lecteur a déjà décidé que ça l’intéresse. Il cherche quelque chose : quand un comportement a changé, si un bug est corrigé, quelle version a introduit un flag. La complétude est toute la valeur, c’est pourquoi la convention Keep a Changelog consacre l’essentiel de son unique page à la structure et presque rien à la prose.
Que sont les release notes ?
Les release notes sont un message sélectif, écrit en prose, sur une version. Leur lecteur n’a encore rien décidé. Il décide si cette version le concerne, et s’il doit faire quelque chose à ce sujet. La sélection est toute la valeur : une release note qui liste tout est un changelog avec des paragraphes, et elle échoue son lecteur de la même façon qu’un changelog qui saute des choses échoue le sien. Comment écrire des release notes traite de la sélection et de la formulation.
Faut-il un changelog et des release notes ?
Il vous faut les deux dès que vos deux audiences veulent des choses différentes ; jusque-là, un
seul artefact qui fait les deux jobs est correct. Les petites équipes publient une seule page
/changelog avec un court paragraphe en haut de chaque entrée, et pendant un moment ça sert aussi
bien un développeur qui cherche une correction qu’une cliente qui parcourt les nouveautés. Diviser
trop tôt vous donne deux choses à maintenir et l’une des deux pourrira.
La division vaut la peine quand ça commence à arriver :
- Vos entrées de changelog ont développé des paragraphes explicatifs que les développeurs scrollent sans lire.
- Ou l’inverse : vos annonces de version ont commencé à lister des mises à jour de dépendances.
- Le support copie des entrées dans des emails et les réécrit au passage.
- Quelqu’un demande “juste les changements cassants” et vous ne pouvez pas les filtrer.
Ce dernier point est le vrai signal. Si personne ne peut répondre “qu’est-ce qui a changé qui me concerne” sans tout lire, vous avez un artefact qui fait mal deux jobs.
Une source, deux vues
L’erreur est de les traiter comme deux documents. Ce sont deux vues sur le même ensemble de changements.
Écrivez le changelog au fil de l’eau, une entrée par changement significatif, chacune étiquetée avec ce qu’elle est : fixed, added, changed, removed, deprecated, security. Gardez les entrées assez courtes pour qu’en écrire une ne soit pas une décision. Puis, au moment de la version, les release notes sont une sélection et une réécriture : prenez les entrées qui importent à une personne, regroupez-les par ce qu’elles permettent de faire, et mettez la raison en haut.
Ça a une conséquence pratique. Si le changelog est la source, il doit être des données structurées, pas une page maintenue à la main. Une entrée a besoin d’un type, d’une date, d’une version, et d’une façon de dire pour qui elle est. Une fois qu’elle a ça, la page publique, le widget in-app et le flux RSS ou JSON sont trois rendus d’une seule chose, et personne ne réécrit rien en chemin vers une cliente. Un email de release notes peut citer la même entrée, depuis n’importe quel outil qui envoie vos emails. Automatisation du changelog traite de laquelle de ces étapes devrait appartenir à une machine. C’est tout l’argument pour traiter un changelog comme un flux plutôt qu’une page. C’est aussi, en toute transparence, ce qu’on construit, donc lisez ça comme un intérêt plutôt qu’un sondage neutre.
Si vous n’avez le temps que pour un seul
Écrivez le changelog. C’est moins cher par entrée, c’est utile le jour où vous l’écrivez, et les release notes peuvent en être dérivées après. L’inverse n’est pas vrai : vous ne pouvez pas reconstruire un an de changements à partir de douze emails d’annonce, et on vous le demandera.
Gardez-le dans un format fixe pour que la dérivation reste possible. Notre page exemples de changelog rassemble des entrées d’équipes qui font ça bien, et la release notes template est la forme qu’on utilise en transformant un ensemble d’entrées en quelque chose qui vaut la peine d’être envoyé.
Une note sur les noms
Rien de tout ça n’est standardisé, et vous trouverez “release notes” utilisé pour une liste continue et “changelog” utilisé pour une annonce trimestrielle. Discuter des mots ne vaut pas le coup. Décidez lequel des deux jobs fait chacun de vos artefacts, appelez-le comme votre équipe l’appelle déjà, et assurez-vous qu’aucun des deux ne fait silencieusement les deux.
Sur quelle surface le résultat atterrit est une décision à part, couverte dans construire une page de changelog.
FAQ
Un changelog est-il la même chose que les release notes ? Non. Un changelog est le registre complet, lu par ceux qui cherchent quelque chose ; les release notes sont l’annonce sélectionnée, lue par ceux qui décident si ça les intéresse. Le même changement apparaît dans les deux, formulé différemment pour chaque lecteur.
Peut-on générer des release notes à partir d’un changelog ? Oui, et c’est la bonne direction. Sélectionnez les entrées qui importeraient à une personne, regroupez-les par résultat, réécrivez le titre. L’inverse, reconstruire un changelog à partir d’annonces, perd tout ce que les annonces ont laissé de côté.
Où devrait vivre un changelog ?
Quelque part de permanent et liable auquel la lectrice peut accéder sans repository : une page
/changelog, un site de docs, ou un flux qui se rend à plusieurs endroits. Un CHANGELOG.md seul
atteint les contributeurs, pas les clients.
Un changelog devrait-il inclure les changements internes ? Oui, en bas, une ligne chacun. Le changelog est le registre complet. Les release notes peuvent aussi les garder, dans une courte dernière section, tant que les changements qu’un lecteur remarquera viennent en premier.
Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.