Changelog : définition et exemple d'entrée

Un changelog est le registre daté de ce qui a changé dans un produit, écrit pour les personnes que le changement concerne, pas pour l’équipe qui l’a livré. Chaque entrée nomme un changement, dit quand il a pris effet, et dit ce que la lectrice doit en faire, ce qui, pour la plupart des entrées, est rien. C’est cette dernière partie qui distingue un changelog d’un journal de commits : un journal de commits est un registre pour ceux qui ont écrit le code, un changelog est un registre pour ceux qui l’utilisent.

Qu’est-ce qu’un changelog, exactement ?

Une liste d’entrées datées, la plus récente en premier, chacune décrivant un seul changement en des termes que la lectrice peut vérifier. Pas ce que l’équipe a construit, mais ce qui est différent maintenant. « Refactoring du service de facturation » est un message de commit. « Les factures affichent désormais la taxe sur une ligne séparée » est une entrée de changelog, parce qu’elle dit à la lectrice quelque chose qu’elle peut vérifier sur son propre compte.

Le format est ancien et volontairement simple : un titre par release ou par jour, une courte liste en dessous, parfois une étiquette de catégorie. Keep a Changelog est la spécification la plus citée pour cette forme, et elle existe parce que la plupart des projets qui font l’impasse sur une spécification finissent par déverser leur historique de commits à la place, ce qui répond à une question différente de celle avec laquelle la lectrice est arrivée.

Les cinq se recoupent en pratique, mais ce ne sont pas les mêmes documents, et la différence tient à qui les tient en main au moment de les lire. Un changelog est celui construit pour être recherché et lié plus tard, d’où le besoin de dates et d’URL stables plus que les autres.

Que contient vraiment une entrée de changelog ?

Quatre choses, dans cet ordre : ce qui a changé, formulé en termes de ce que l’utilisatrice ou l’appelante remarquerait ; quand cela a pris effet ; à quelle catégorie cela appartient (added, fixed, changed, removed sont les quatre courantes) ; et, quand cela compte, ce que la lectrice doit faire. Un lien vers plus de détails est bienvenu. Un paragraphe de justification interne ne l’est pas, parce que la lectrice n’a pas demandé pourquoi, elle a demandé quoi.

## 2026-09-07

### Added
- Les factures affichent désormais la taxe sur une ligne séparée, dans
  la devise du compte du client.

### Fixed
- Exporter un rapport en CSV ne supprime plus la dernière ligne quand
  le rapport dépasse 10 000 lignes.

Cette forme passe d’une mise à jour de deux lignes à cent entrées dans une release sans changer de structure, et c’est le vrai test pour savoir si un format fonctionne : se lit-il de la même façon une semaine chargée et une semaine calme.

Qui écrit un changelog, et quand ?

Celle qui a fait le changement, au moment où il est livré, pas une rédactrice technique qui le reconstitue à partir de tickets une semaine plus tard. Celle qui a touché le code sait ce qui a vraiment changé pour l’utilisatrice ; un résumé écrit après coup tend à décrire le ticket plutôt que ce qui a réellement été livré, ce qui est souvent plus large ou plus étroit que la réalité. Certaines équipes ajoutent une étape de relecture avant qu’une entrée devienne publique, surtout pour intercepter le langage interne qui s’est glissé dedans, et cette relecture doit être assez rapide pour que l’entrée sorte le jour même.

Où un changelog doit-il vivre ?

Sur sa propre page, à une URL stable, diffusé en flux. Enterré dans un menu de paramètres ou une étiquette de release sur un hébergeur de code, il n’atteint que ceux qui savaient déjà où regarder. Une page publique peut être liée depuis un ticket de support, citée dans un avis, ou suivie. Le flux compte autant que la page : une lectrice qui vérifie le changelog d’un produit une fois par mois est rare, une qui s’y abonne ne l’est pas, et seul le flux sert la seconde.

En quoi diffère-t-il des notes de version ?

Les deux sont constamment confondus, et suffisamment différents pour que les mélanger produise un document qui ne sert bien ni l’une ni l’autre lectrice. Changelog vs notes de version parcourt la distinction en entier ; en bref, un changelog est le registre complet et chronologique, et les notes de version sont un sous-ensemble sélectionné, écrit pour qu’une mise à jour paraisse mériter d’être adoptée. Un produit a généralement besoin des deux, adressés à des moments différents de la journée de la lectrice.

Qu’est-ce qui rend un changelog digne d’être lu ?

La précision et l’honnêteté sur sa propre portée. « Divers correctifs » est la phrase qui apprend à une lectrice à cesser d’ouvrir la page, parce qu’elle ne promet rien de vérifiable. Une entrée qui nomme le comportement exact qui a changé, même pour un petit correctif, est celle qui maintient un abonnement en vie. Cette discipline vaut aussi pour ce qu’on omet : un changelog qui n’annonce que des réussites, et jamais un correctif pour quelque chose qui était cassé, se lit comme du marketing déguisé en changelog, et les lectrices le remarquent.

La discipline de versionnage compte aussi. Semantic versioning et votre changelog explique comment le numéro de version et l’entrée devraient concorder, pour qu’une lectrice qui parcourt l’historique des versions reçoive le même signal deux fois plutôt que deux signaux différents.

Comment les changelogs sont-ils générés ?

De deux façons, et la plupart des configurations réelles sont un mélange. La génération automatisée lit les messages de commit, généralement au format Conventional Commits, et les transforme en entrées sans que personne ne touche à la sortie ; des conventional commits au changelog couvre ce pipeline. La génération sélectionnée signifie que quelqu’un écrit ou modifie chaque entrée à la main. La sortie automatisée est plus rapide et ne rate jamais une pull request fusionnée, mais hérite mot pour mot de chaque message de commit vague, donc la plupart des équipes qui automatisent gardent quand même une relecture légère avant de publier plutôt que de montrer la sortie brute.

FAQ

Tout produit a-t-il besoin d’un changelog ? Tout produit avec des utilisatrices concernées par le changement en a besoin, que ce soit une application SaaS, un outil interne ou une API publique. La forme s’adapte (un changelog d’API se lit différemment de celui d’une application grand public), le besoin non.

Qu’est-ce qu’un changelog en termes logiciels ? La même définition que ci-dessus : une liste datée et chronologique de ce qui a changé dans le logiciel, écrite pour ceux qui l’utilisent, pas pour ceux qui l’ont construit.

Un changelog peut-il être généré automatiquement à partir des commits ? Oui, et de nombreuses équipes font exactement cela, généralement à partir de messages au format Conventional Commits. Le compromis est qu’une entrée générée est aussi claire que le message de commit dont elle provient, donc une relecture avant publication intercepte celles à reformuler.

Un changelog est-il la même chose qu’un historique des versions ? Assez proche pour que les termes soient utilisés de façon interchangeable. Un historique des versions n’est parfois qu’une liste de numéros et de dates sans description ; un changelog inclut toujours ce qui a changé.

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.

À voir sur changeloop : Exemples de changelog, Documentation développeurs