Tags git, releases et votre changelog

Un tag git, une release et une entrée de changelog sont trois enregistrements différents du même événement, et les confondre fait doucement dériver un changelog de ce qui a vraiment été livré. Un tag marque un commit. Une release empaquette ce tag avec des artefacts et une description. Une entrée de changelog explique, en des termes qu’une lectrice hors du dépôt peut utiliser, ce qui a changé. Ils se produisent généralement proches dans le temps, et c’est exactement pourquoi il est facile de les traiter comme une seule étape plutôt que trois, et exactement pourquoi l’écart ne devient visible que des mois plus tard, quand quelqu’un demande « qu’est-ce qui est sorti dans la v2.4 » et que la réponse honnête demande de vraies recherches.

Quelle est la différence réelle entre les trois ?

Un tag est le plus mécanique des trois : git tag v2.4.0 et c’est fait, sans aucune obligation que quelque chose explique ce qu’il contient. Une release ajoute une description et, en général, des artefacts téléchargeables, et son public reste des développeuses qui savent ce qu’est une page de release. Une entrée de changelog est la seule des trois écrite pour une lectrice qui n’ouvrira peut-être jamais le dépôt, c’est pourquoi c’est celle qui demande le plus d’attention éditoriale et celle la plus susceptible d’être sautée sous pression de délais.

Chaque tag git a-t-il besoin d’une entrée de changelog ?

Non, et les traiter un-à-un est une erreur courante. Un tag peut marquer un jalon interne, une release candidate, ou un hotfix qui n’atteint jamais la plupart des utilisatrices ; aucun d’eux n’a nécessairement besoin d’une entrée publique. Le test est le même que celui qui décide si quelque chose appartient du tout à un changelog : est-ce qu’une utilisatrice ou une appelante le remarquerait ou s’en soucierait. La plupart des tags passent ce test. Certains, comme un tag créé uniquement pour déclencher un pipeline CI, jamais.

Chaque entrée de changelog a-t-elle besoin de son propre tag ?

Pas toujours, et c’est là que les équipes qui déploient en continu divergent de celles qui livrent des packages versionnés. Un produit SaaS qui déploie plusieurs fois par jour peut regrouper plusieurs déploiements sous une entrée de changelog datée sans tag 1:1 par déploiement ; une bibliothèque publiée dans un registre de packages a généralement besoin d’un tag par version publiée. Les modules Go et Swift Package Manager résolvent les versions à partir des tags eux-mêmes ; sur npm ou PyPI, le registre détient la version publiée, et le tag est ce qui permet de relier cette version à sa source. Un dépôt avec plusieurs packages versionnés indépendamment doit décider ça par package, pas une seule fois pour tout le repo ; changelogs de monorepo couvre comment les préfixes de tags et la portée du changelog devraient suivre les frontières des packages, pas des dossiers. Semantic versioning et votre changelog couvre comment le numéro de version lui-même devrait correspondre aux catégories de changelog ; les tags sont le mécanisme qui rend un numéro de version vérifiable contre le code réel.

Comment une description de release devrait-elle se rattacher à l’entrée de changelog ?

Elles peuvent être le même texte, mais seulement si le public des deux est vraiment le même, ce qui est plus rare qu’il n’y paraît. Une page de release sur un hébergeur de code est lue presque exclusivement par des développeuses ; si un produit a aussi des utilisatrices non techniques qui lisent le changelog, dupliquer la description de release mot pour mot livre des termes internes et une formulation orientée code à une lectrice qui avait besoin de la version en langage clair. Le schéma le plus propre : écrire l’entrée de changelog comme l’artefact principal orienté lectrice, et laisser la description de release soit y renvoyer, soit garder un résumé plus court et plus technique pour le public déjà à l’aise là-bas.

# Release v2.4.0 (GitHub, pour développeuses)
Fait passer le pipeline de rapports au nouveau moteur d'agrégation.
Voir le changelog pour le résumé orienté client :
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, orienté client)
### Added
- Les rapports se chargent désormais en moins d'une seconde, même
  pour les comptes de plus d'un million de lignes.

Même release, deux documents, chacun avec sa propre formulation pour sa propre lectrice.

D’où vient vraiment l’entrée de changelog ?

De deux points de départ, et la plupart des pipelines réels sont un mélange des deux. Elle peut être générée à partir des messages de commit au moment du tag, ce qui est rapide et ne rate jamais une pull request fusionnée ; des conventional commits au changelog couvre ce pipeline en entier. Ou elle peut être écrite à la main, séparément du tag, calée sur le moment où une fonctionnalité est considérée terminée plutôt que sur le moment où le code est fusionné. Les entrées générées sont cohérentes mais héritent de chaque message de commit vague ; les entrées écrites à la main sont plus claires mais ont besoin de quelqu’un pour vraiment les écrire. La plupart des équipes qui automatisent gardent quand même une légère passe d’édition sur le texte généré avant qu’il ne devienne l’entrée publique, la même discipline que recommande Keep a Changelog, en pratique, peu importe d’où vient originellement le texte brut.

Que casse-t-il quand les trois se désynchronisent ?

La confiance dans celui que la lectrice a vérifié en premier. Un tag qui existe sans entrée de changelog correspondante ressemble, du côté de la lectrice du changelog, à rien ne s’étant passé cette semaine-là. Une entrée de changelog sans tag ou release correspondant rend impossible pour quelqu’un qui débogue un problème en production de récupérer le code exact qui était en direct quand une entrée a été publiée. La solution n’est pas une automatisation parfaite, c’est une source unique de vérité pour la correspondance : un endroit, ne serait-ce que la propre checklist du processus de release, qui dit qu’un changement livrable reçoit les trois, dans le même commit ou la même pull request qui l’introduit.

FAQ

Les entrées de changelog devraient-elles être générées automatiquement à partir des tags git ? Elles peuvent être un point de départ, mais un tag seul ne porte aucune description orientée lectrice, seulement une plage de commits. La génération automatisée doit lire les messages de commit dans cette plage, pas seulement l’existence du tag, pour produire quelque chose d’utilisable.

Et si on ne tague pas chaque release ? Alors l’entrée de changelog devient l’enregistrement principal, et elle devrait quand même porter une date et, si le produit en a un, un numéro de version, pour que l’entrée reste quelque chose qu’une lectrice puisse référencer plus tard même sans tag correspondant.

Les tags de pré-release (comme v2.4.0-rc.1) devraient-ils avoir des entrées de changelog ? Généralement non. Une release candidate est pour des tests internes ou bêta, et une entrée de changelog pour elle entraîne les lectrices à attendre des entrées pour des versions qui pourraient ne jamais sortir telles que décrites. Réservez les entrées aux tags qui atteignent la disponibilité générale.

Une seule entrée de changelog peut-elle couvrir plusieurs tags git ? Oui, et elle le devrait souvent pour les équipes qui taguent fréquemment. Regroupez les tags apparentés sous une entrée datée décrivant le changement net, plutôt que de publier une entrée maigre par tag qui fragmente une fonctionnalité sur plusieurs lectures.

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