CHANGELOG.md : ce qu'il contient et comment le garder à jour

Un CHANGELOG.md est un fichier Markdown à la racine d’un dépôt qui liste, pour chaque version publiée, ce qui a changé dans des termes sur lesquels un utilisateur du projet peut agir. Le fichier est lu par les gens qui décident s’ils mettent à jour, par ceux qui déboguent après une mise à jour, et par les registres de paquets et les outils de release qui l’affichent sur la page du projet. Le format que suivent la plupart des projets est celui décrit sur keepachangelog.com : la version la plus récente en haut, une section Unreleased au-dessus, et les entrées regroupées sous Added, Changed, Deprecated, Removed, Fixed et Security.

Qu’est-ce qu’un fichier CHANGELOG.md ?

C’est l’historique lisible d’un projet, une version à la fois, gardé à côté du code pour être livré avec lui. Il se distingue de git log par son public et sa sélection : le git log enregistre chaque commit pour les personnes qui les ont écrits, tandis que le changelog enregistre les changements qu’un utilisateur remarquerait, écrits pour la personne qui ne les a pas faits. Un commit qui renomme une variable interne n’a pas de ligne de changelog. Un commit qui change un délai d’attente par défaut en a une, même si le diff tenait en un seul caractère.

Le fichier vit à la racine du dépôt sous ce nom exact parce que les outils le cherchent là. GitHub le lie depuis la page du dépôt, npm et PyPI l’affichent quand il est inclus dans le paquet, et des outils de release comme release-please et semantic-release le lisent et l’écrivent sur place. changelog.md en minuscules et CHANGES.md conviennent aussi aux humains, mais certains outils ne cherchent que le nom canonique.

À quoi ressemble un CHANGELOG.md complet ?

Un exemple court et correct vaut plus qu’une longue description. Celui-ci suit la mise en page de Keep a Changelog 1.1.0 et le versionnage sémantique pour les numéros.

# Changelog

Tous les changements notables de ce projet sont listés ici.
Format : Keep a Changelog. Versions : Semantic Versioning.

## [Unreleased]

### Added
- L'option `--dry-run` de `deploy` affiche le plan sans l'appliquer.

## [2.3.1] - 2026-10-01

### Fixed
- La recherche n'échoue plus sur les requêtes contenant un tiret.
  Cassée depuis 2.3.0.

### Security
- Correction d'un path traversal dans le gestionnaire de fichiers
  statiques. Mettez à jour aujourd'hui si vous servez des fichiers
  envoyés par des utilisateurs.

## [2.3.0] - 2026-09-18

### Added
- Export en streaming. Les fichiers de plus de 100 Mo n'expirent plus.

### Deprecated
- `legacyAuth()` fonctionne encore mais sera supprimé en 3.0.
  Utilisez `auth()`.

[Unreleased]: https://github.com/acme/tool/compare/v2.3.1...HEAD
[2.3.1]: https://github.com/acme/tool/compare/v2.3.0...v2.3.1
[2.3.0]: https://github.com/acme/tool/compare/v2.2.0...v2.3.0

Quatre détails portent l’essentiel de la valeur. Chaque version a une date au format ISO, pour qu’un lecteur puisse la rapprocher du moment où son problème a commencé. Chaque titre de version est un lien vers la vue de comparaison, donc le diff complet est à un clic. Une correction dit quelle version a introduit le bug. Et la section Security est à part, pour que quelqu’un qui cherche “dois-je mettre à jour maintenant” la trouve en quelques secondes.

Comment garder un CHANGELOG.md à jour ?

Écrivez la ligne dans la même pull request que le changement, sous Unreleased, et déplacez la section sous un titre de version au moment de la release. C’est toute la méthode. Le fichier se périme quand la ligne est écrite plus tard par quelqu’un d’autre, au moment de la release, à partir d’une liste de messages de commit qu’il n’a pas rédigés.

Deux choses font tenir l’habitude. La première est un contrôle en CI qui fait échouer une pull request touchant src/ sans toucher au changelog, avec un label pour le sauter quand le changement n’a aucun effet visible ; un contrôle de changelog en GitHub Action montre la version en quarante lignes. La seconde est une étape de release qui renomme Unreleased en version et date en une seule commande, pour que personne n’ait à y penser à la main. Qui écrit le changelog explique comment les équipes tranchent la question de savoir à qui revient la ligne.

Faut-il générer le changelog à partir des commits ?

La génération vous donne un brouillon complet ; elle ne vous donne pas un changelog. Les outils bâtis sur les conventional commits, et une automatisation de release comme release-please, lisent les préfixes feat:, fix: et BREAKING CHANGE: et produisent une liste groupée où chaque pull request est liée. La liste vaut ce que valent les sujets de commit, et les sujets de commit décrivent le code.

Le compromis qui marche est de générer, puis relire. Laissez l’outil créer la section Unreleased à partir des commits, et faites réécrire par la pull request de release les lignes qu’un utilisateur lira : le symptôme plutôt que le nom de la fonction, le réglage qui a bougé plutôt que le fichier modifié. Des conventional commits à un changelog parcourt le pipeline, et un générateur de changelog dans le navigateur suffit à obtenir un brouillon depuis un git log collé, sans rien installer.

Que ne faut-il pas mettre dans CHANGELOG.md ?

Les refactorisations internes, les montées de dépendances sans changement de comportement, les commits réservés aux tests, la configuration CI et les changements de formatage. Ils ont leur place dans l’historique git, où quiconque en a besoin peut les retrouver. Les inclure enterre les lignes qui comptent et apprend aux lecteurs à sauter le fichier.

L’autre chose à laisser dehors est la version marketing d’un changement. “Des exports ultra rapides” ne donne rien de vérifiable au lecteur. “L’export est désormais en streaming ; les fichiers de plus de 100 Mo n’expirent plus” si. Le fichier est un document de référence, et son ton doit suivre : des lignes courtes, des noms concrets, une version ou une date sur tout. Keep a Changelog, mis en pratique couvre les parties de la spec que les équipes oublient le plus souvent, et formats de fichier de changelog explique quand une source JSON ou YAML à côté du fichier Markdown vaut son coût.

Un produit avec une page de changelog a-t-il encore besoin du fichier ?

Une bibliothèque, oui, parce que le fichier est ce que les registres de paquets affichent et ce qu’un développeur lit hors ligne. Un produit SaaS sans artefact installable peut se contenter de la page, puisque ses utilisateurs ne voient jamais le dépôt. Beaucoup d’équipes tiennent les deux : le fichier comme registre d’ingénierie, et une page de changelog publique rédigée à partir de lui pour un public plus large, avec la répartition du détail que décrit changelog vs release notes. Si la page est alimentée par le fichier, gardez le fichier comme source de vérité et générez la page, pour n’avoir qu’un seul endroit à modifier.

FAQ

Quelle est la différence entre CHANGELOG.md et des release notes ? Le changelog est le registre complet et continu de chaque changement notable, conservé dans le dépôt. Les release notes sont un message sur une seule release, souvent plus court et réécrit pour un public plus large. Beaucoup de projets publient la section du changelog d’une version comme release notes.

Où doit vivre CHANGELOG.md ? À la racine du dépôt, sous ce nom exact, pour que GitHub, les registres de paquets et les outils de release le trouvent. Un monorepo en garde un par paquet, à côté du manifeste de chaque paquet.

Faut-il générer CHANGELOG.md à partir des commits git ? Générez le brouillon, puis relisez les lignes qu’un utilisateur lira. Les messages de commit décrivent le changement de code ; le changelog décrit ce qu’un utilisateur remarque. Des outils comme conventional-changelog et release-please donnent un bon point de départ.

Chaque commit a-t-il besoin d’une entrée de changelog ? Non. Seulement les changements qu’un utilisateur du projet pourrait remarquer : nouvelle capacité, comportement modifié, dépréciations, suppressions, corrections et correctifs de sécurité. Les refactorisations, les changements de tests et les modifications de CI restent dans l’historique git.

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 : Générateur de changelog, Exemples de changelog