Semantic versioning et votre changelog

Le semantic versioning dit à l’appelante combien une release peut lui faire mal avant qu’elle ne lise une seule entrée de changelog. Passer de 2.4.1 à 2.5.0 signifie : nouvelle capacité, rien ne casse. Passer de 2.5.0 à 3.0.0 signifie : lire cette entrée avant de mettre à jour. Le changelog et le numéro de version sont censés affirmer la même chose sous deux formes, et la plupart des frictions entre les deux apparaissent justement quand ils ne concordent pas, ce qui arrive plus souvent que la spécification ne le laisserait penser.

Que promet vraiment chaque chiffre d’une version ?

Le semantic versioning définit trois chiffres, MAJOR.MINOR.PATCH, chacun avec une règle stricte sur ce qui le déclenche. Un saut MAJOR signifie un changement incompatible : quelque chose qu’une intégration correcte et existante pourrait remarquer et pour lequel elle devrait changer. Un saut MINOR signifie une nouvelle fonctionnalité compatible en arrière : rien d’existant ne casse, quelque chose de nouveau est disponible. Un saut PATCH signifie un correctif compatible en arrière : le comportement se rapproche de ce qui était documenté, et personne qui comptait volontairement sur l’ancien comportement ne devrait rien remarquer.

Le tableau sert aussi de test à l’envers : si une entrée ne se lit pas comme sa ligne, soit le numéro de version est faux, soit l’entrée sous-vend ou survend ce qui s’est réellement passé.

Qu’est-ce qui compte comme incompatible pour le versionnage ?

Le même test qui décide si quelque chose appartient à un changelog d’API : si une appelante correcte, écrite contre l’ancien comportement et jamais touchée depuis, pourrait se comporter différemment à cause de ce changement. Qu’est-ce qu’un changement incompatible, et comment le livrer couvre la décision en entier, y compris les cas qui semblent incompatibles sans l’être, et ceux qui semblent petits sans l’être. En bref pour le versionnage : si la réponse est oui, le saut est MAJOR quel que soit le code que le changement a réellement touché en interne. Les numéros de version suivent la conséquence pour l’appelante, pas l’effort de l’équipe.

Comment une entrée de changelog devrait-elle correspondre à un saut de version ?

Une entrée, une catégorie de saut, énoncée d’emblée. Le motif du tableau se poursuit directement : une entrée incompatible se place sous la version qui l’a introduite, formulée d’abord comme un avertissement puis comme une description. Une entrée additive se place sous sa version MINOR, formulée comme une disponibilité. Un correctif se place sous sa version PATCH, formulé comme une correction. Mélanger les catégories dans une entrée, comme glisser un changement incompatible dans le même paragraphe qu’un correctif sans rapport, c’est ainsi qu’une lectrice rate justement la seule chose qui comptait vraiment.

## 3.0.0 (2026-09-07)

### Changed
- **BREAKING:** `GET /reports` renvoie désormais les montants sous
  forme d'entiers dans la plus petite unité monétaire (centimes) au
  lieu de flottants. Mettez à jour tout code qui lit `amount`
  directement.

## 2.9.0 (2026-09-01)

### Added
- Les rapports peuvent désormais être filtrés par `status`.

## 2.8.4 (2026-08-28)

### Fixed
- `GET /reports?status=` renvoyait une page vide au lieu d'un 400 pour
  un statut inconnu.

Lu de haut en bas, le numéro de version et l’étiquette de section disent la même chose deux fois, et c’est exactement le but : une lectrice qui ne parcourt que les titres obtient une lecture correcte du risque avant d’ouvrir la moindre ligne.

La règle du changement incompatible s’applique-t-elle de la même façon avant la 1.0.0 ?

Non, et c’est de là que vient la plupart de la confusion sur « est-ce que c’était vraiment incompatible ». SemVer est explicite : la version majeure zéro, 0.y.z, est pour le développement initial : tout peut changer à tout moment, et l’API publique ne doit pas être considérée comme stable. Un saut de 0.4.0 à 0.5.0 peut porter un changement incompatible sans violer la spécification, parce que la garantie liée à la version majeure ne commence qu’une fois qu’un projet livre sa 1.0.0. Une entrée de changelog doit quand même la même honnêteté aux lectrices sur ce qui a cassé ; ce qui change, c’est seulement que le numéro de version lui-même n’est pas le signal sur lequel s’appuyer avant l’arrivée de la 1.0.0.

Et si votre produit ne livre pas de versions discrètes ?

La plupart des produits SaaS déploient en continu et n’exposent jamais de numéro de version à une appelante, ce qui n’élimine pas le besoin de cette discipline, seulement le chiffre qui la porterait normalement. L’entrée de changelog doit faire tout le travail seule : dire clairement si un changement est incompatible, additif, ou un correctif, avec les mêmes trois mots qu’utilise le semantic versioning, même sans champ de version où les accrocher. Certaines équipes maintiennent une version purement interne juste pour ancrer les entrées de changelog à quelque chose de reliable, sans jamais l’exposer directement à l’appelante.

Comment cela s’applique-t-il spécifiquement à un changelog d’API ?

Plus strictement que presque partout ailleurs, parce que les appelantes d’une API sont du code, pas des personnes qui peuvent hausser les épaules devant un changement inattendu. Changelog d’API : quoi publier et qui le lit couvre la forme complète de ce document ; la discipline de versionnage ici est ce qui garde ses sections breaking et additive honnêtes. Une API qui propose plusieurs versions en parallèle, comme v1 et v2 servies simultanément pendant une fenêtre de migration, applique en pratique le semantic versioning à l’échelle de toute l’interface plutôt que d’un seul paquet, et le même vocabulaire de trois mots s’applique toujours à chaque entrée.

Que dit Keep a Changelog sur le versionnage ?

Il se lie directement par son nom au semantic versioning et recommande le même vocabulaire de catégories que cet article utilise : Added, Changed, Deprecated, Removed, Fixed, Security. Keep a Changelog, en pratique parcourt comment adopter cette spécification, y compris les endroits où les équipes ont tendance à en dévier. Le recoupement n’est pas un hasard : les deux spécifications essaient de résoudre le même problème depuis des extrémités opposées, l’une standardise le numéro de version et l’autre l’entrée qui l’explique.

FAQ

Chaque entrée de changelog a-t-elle besoin d’un numéro de version ? Si le produit livre des versions, oui, parce que le chiffre permet à une lectrice de sauter directement à « à quel point cela me concerne » sans lire l’entrée d’abord. Si le produit déploie en continu sans champ de version, la formulation de l’entrée doit porter ce signal seule.

Quelle est la différence entre un saut MAJOR et une entrée de changement incompatible ? Ils devraient décrire le même événement sous deux formes. Le numéro de version est le signal lisible par machine (l’outillage d’une appelante peut y réagir) ; l’entrée de changelog est l’explication lisible par un humain de ce qui a concrètement changé.

Une release PATCH peut-elle être incompatible ? Par définition, non. Si une telle release est sortie quand même, ne modifiez pas et ne re-taguez pas la version publiée : la FAQ SemVer recommande de publier une nouvelle version qui rétablit la compatibilité, ou une nouvelle MAJOR si la rupture reste, et de documenter la version fautive pour que les utilisateurs sachent l’éviter.

Les changements purement internes ont-ils besoin d’un saut de version ? Non. Le semantic versioning suit l’interface publique. Un refactoring sans effet observable pour une appelante n’a besoin ni de saut ni d’entrée de changelog, même s’il représentait un travail d’ingénierie important.

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, Documentation développeurs