changeloop blog

Release notes de correctifs : écrire des entrées utiles

Fri, 02 Oct 2026 00:00:00 GMT

De bonnes release notes de correctifs décrivent ce que l'utilisateur a vu mal tourner, pas ce que le code a mal fait. Chaque entrée dit qui était concerné, depuis quand, si la correction est complète et si le lecteur doit faire quelque chose, même si c'est seulement "aucune action requise".

La plupart des équipes recopient une ligne du message de commit. Le tableau montre six réécritures, et les sections qui suivent expliquent les règles.

Avant (le message de commit)	Après (le symptôme)
Fixed null pointer in export handler	Les exports n'échouent plus avec "Une erreur est survenue" quand un projet n'a aucun tag. Relancez tout export qui a échoué depuis le 3 septembre.
Resolved race condition in sync worker	Les modifications faites sur deux appareils à quelques secondes d'écart ne s'écrasent plus. Rien à faire.
Fix timezone bug	Les rapports planifiés s'exécutent maintenant à l'heure choisie. Les comptes à l'est de UTC voyaient des rapports partir jusqu'à un jour trop tôt depuis le 12 août. Aucun changement nécessaire.
Patched XSS in comment renderer	Correctif de sécurité : un commentaire spécialement conçu pouvait exécuter un script dans le navigateur d'un autre utilisateur. Passez en 4.2.1 aujourd'hui. Nos logs ne montrent aucune exploitation.
Fixed regression from 4.1.0	La recherche fonctionne de nouveau pour les requêtes contenant un tiret. Elle était cassée en 4.1.0 et corrigée en 4.1.1.
Bug fixes and performance improvements	Dites lesquels. Voir la dernière section.

Comment rédiger une entrée de correctif dans des release notes ?

Commencez par le symptôme dans les mots de l'utilisateur, puis qui était touché et depuis quand, puis l'état de la correction, puis l'action. Une ou deux phrases suffisent d'ordinaire. La cause dans le code a sa place dans la pull request, là où un ingénieur ira la chercher.

Un lecteur cherche une seule chose : "est-ce que c'était moi ?" Quatre éléments couvrent presque toutes les entrées :

Le symptôme. Ce qui est apparu à l'écran, dans la réponse de l'API ou sur la facture. Citez le texte de l'erreur s'il y en avait un, car les gens le recherchent.
La portée. Quel plan, quelle plateforme, quelle version d'API ou forme de données. "Les comptes de plus de 50 000 lignes" se vérifie. "Certains utilisateurs" non.
La période. Depuis quelle version ou quelle date, pour qu'un lecteur puisse décider si le résultat bizarre d'hier était ce bug.
L'action. Relancer, resynchroniser, mettre à jour, retirer un contournement, ou rien du tout.

Si des utilisateurs ont mis en place un contournement, c'est la ligne d'action qui leur dit qu'ils peuvent le supprimer.

Quelle différence entre une release note et un changelog ?

Un changelog est le registre complet et continu des changements. Les release notes sont un message choisi et réécrit sur une version, pour des gens qui se demandent si cela les concerne. Pour les correctifs, le changelog liste chaque correction et les notes mettent en tête celles qu'un lecteur pouvait remarquer.

Une coquille dans une infobulle va seulement dans le changelog. Un mauvais taux de TVA sur les factures va dans les deux. La répartition complète est dans changelog vs release notes, et la forme d'un bon ensemble de notes dans comment écrire des release notes.

Keep a Changelog est une convention pratique pour le côté registre. Elle réserve "Fixed" aux corrections de bugs et une rubrique "Security" séparée aux vulnérabilités, soit la même séparation que fait cet article pour le lecteur.

Un correctif est-il une mise à jour ?

Oui. Un correctif modifie le produit, donc en livrer un est une mise à jour. Avec le versionnage sémantique, un correctif rétrocompatible est une version patch, par exemple de 4.2.0 à 4.2.1.

Savoir si le lecteur doit faire quelque chose est une autre question, et la note doit y répondre. Un correctif qui change ce qu'observe un appelant correct est proche d'un changement cassant, et les changements cassants expliquent où se situe cette limite.

Quand un correctif mérite-t-il sa propre entrée, et quand est-il mineur ?

Donnez à un correctif sa propre entrée quand un utilisateur pouvait remarquer le bug, y perdre du temps ou des données, ou bâtir un contournement autour. Regroupez-le dans une courte liste "Corrections mineures" quand personne hors de votre équipe ne pouvait le voir. Jugez selon l'expérience du lecteur, quelle que soit la taille du diff.

A sa propre entrée	Va dans la liste des corrections mineures
Signalé par un client ou subi par beaucoup	Défaut cosmétique dans un écran rarement ouvert
A causé un résultat faux, des tâches en échec ou du travail perdu	Coquille, espacement, icône mal alignée
Demande une action du lecteur	Correction dans un outil interne ou une page d'admin
Une régression d'une version récente	Échec vu seulement dans un environnement de test
Touche la facturation, les permissions ou les données	Libellé de log, mises à jour de dépendances sans effet utilisateur

Chaque ligne du groupe doit quand même dire quelque chose : "Corrections de quelques problèmes d'interface" est un texte de remplissage.

Comment parler d'une régression ?

Nommez la version qui l'a introduite, appelez cela une régression et donnez la version qui la corrige. Ceux qui ont subi le bug savent déjà que ça ne marchait pas, donc un aveu court et direct les sert mieux qu'une formulation vague.

Par exemple : "Les résultats de recherche pour les requêtes contenant un tiret revenaient vides en 4.1.0. C'est corrigé en 4.1.1. Si vous aviez modifié vos requêtes pour éviter les tirets, vous pouvez revenir en arrière."

"Fiabilité de la recherche améliorée" passe pour de l'évasion aux yeux de quiconque a perdu un après-midi à cause du bug. Si la cause reste à confirmer, dites-le, comme le formulent les conseils sur les release notes d'urgence : ne laissez jamais la note paraître plus certaine que l'équipe.

Comment annoncer un correctif de sécurité ?

Indiquez la gravité sans détour, nommez les versions touchées et la version qui corrige, dites l'urgence de la mise à jour et incluez l'identifiant CVE s'il en existe un. Ne publiez les détails que lorsque les utilisateurs peuvent agir sur un correctif, en suivant un processus de divulgation coordonnée quand un rapporteur est impliqué.

L'ordre compte : le rapporteur vous prévient en privé, vous livrez le correctif, et la note publique sort quand les utilisateurs peuvent se protéger. Le processus de divulgation coordonnée des vulnérabilités de la CISA coordonne le signalement, l'analyse et la divulgation publique des vulnérabilités. Les règles des CVE Numbering Authorities régissent l'attribution et la publication des enregistrements CVE, et sur GitHub un repository security advisory permet de rédiger l'avis en privé et de demander un identifiant.

Une entrée de sécurité porte en général quatre faits :

Ce qu'un attaquant pouvait faire, en une phrase et sans preuve de concept.
Les versions touchées, et la version qui corrige.
L'urgence : "mettez à jour aujourd'hui" ou "mettez à jour à votre prochaine version".
Si vous avez observé une exploitation, et un crédit au rapporteur s'il est d'accord.

Laissez de côté les étapes d'exploitation.

Que doit dire une note sur la correction d'une perte de données ?

Dites quelles données étaient touchées, comment savoir si les vôtres l'étaient et si on peut les récupérer. "Aucune action requise" est rarement vrai ici, et la première question du lecteur est "mes données sont-elles perdues".

Une entrée utilisable donne la condition qui faisait perdre des données ("supprimer un dossier pendant une synchronisation"), la période où c'était possible, un moyen de vérifier ("ouvrez la Corbeille et cherchez les éléments datés du 3 au 9 septembre") et le chemin de récupération. Si les données ne peuvent pas être récupérées, dites-le. Contactez aussi directement les clients touchés, car la release note ne doit pas être le seul endroit où quelqu'un apprend que ses données ont été touchées.

Pourquoi "Corrections de bugs et améliorations de performance" est-il une mauvaise note ?

Cela ne donne rien à faire au lecteur et cache les corrections que quelqu'un attendait. Un client qui avait signalé un plantage ne peut pas savoir s'il est corrigé, et un client qui a un contournement ne peut pas savoir s'il doit le retirer.

Il y a deux alternatives honnêtes. Si une version n'a rien qu'un lecteur pourrait remarquer, ne publiez pas de notes pour elle et laissez le changelog garder la trace. Si elle a des corrections, listez-les dans les termes du lecteur :

Avant :
  Corrections de bugs et améliorations de performance.

Après :
  Corrigé : l'export CSV échouait pour les projets sans tags.
  Corrigé : le mode sombre cachait le curseur dans les commentaires.
  Plus rapide : le tableau de bord s'ouvre plus vite pour les
  espaces de plus de 100 projets.

D'où viennent les notes de correctifs ?

Elles viennent de la pull request qui a corrigé le bug et du signalement qui l'a déclenchée. Si les mots de la personne qui a signalé le problème accompagnent le correctif, la moitié du symptôme est déjà écrite.

Demande de fonctionnalité ou bug explique pourquoi étiqueter correctement un signalement décide de qui en est responsable. Dans Changeloop, un bug signalé via le widget devient une issue GitHub étiquetée bug, et l'entrée de changelog est rédigée à partir de la pull request fusionnée puis retenue jusqu'à l'approbation d'une personne avant publication. Le modèle de release notes vous donne la même forme d'entrée pour écrire à la main : symptôme, portée, période, action.

FAQ

Que doivent contenir les release notes de correctifs ? Chaque entrée doit nommer le symptôme vu par l'utilisateur, qui était touché, depuis quelle version ou quelle date, si la correction est complète et ce que le lecteur doit faire, y compris "rien".

Faut-il lister chaque correctif dans les release notes ? Non. Listez ceux qu'un utilisateur pouvait remarquer, qui lui ont fait perdre du temps ou qu'il a contournés, et regroupez les corrections cosmétiques ou internes dans une courte liste "Corrections mineures". Le changelog garde chaque correction pour qui doit en retrouver une.

Comment rédiger des release notes pour un bug que vous avez introduit ? Dites que c'était une régression, nommez la version qui l'a introduite et celle qui la corrige, et indiquez aux lecteurs s'ils peuvent retirer un contournement. Une formulation directe se lit mieux qu'une formulation adoucie.

Comment consulter les release notes d'un produit que vous utilisez ? Cherchez une page changelog ou release notes liée depuis le menu d'aide, le pied de page ou la documentation du produit, ou l'onglet des releases du dépôt pour les projets open source.

Comment demander un feedback client dans un produit logiciel

Fri, 02 Oct 2026 00:00:00 GMT

Pour demander un feedback client dans un produit logiciel, posez une question précise sur quelque chose que l'utilisateur vient de faire, à l'endroit où il l'a fait. "Comment s'est passé l'export de ce rapport ?" juste après un export obtient une réponse. "Dites-nous ce que vous pensez de notre produit" dans un pied de page obtient le silence. Le reste de cette page, ce sont les moments, les canaux et les formulations exactes.

La plupart des conseils sur ce sujet sont écrits pour des boutiques et des services clients. Une équipe logicielle sait exactement ce que l'utilisateur a fait il y a une seconde, donc la question peut porter là-dessus.

Moment	Où demander	Question prête à l'emploi
Juste après la fin d'une tâche	Dans l'app, à côté du résultat	"Cet export a-t-il fait ce qu'il vous fallait ?"
Après le premier usage d'une nouvelle fonctionnalité	Dans l'app, une seule fois	"Qu'essayiez-vous de faire avec la modification groupée ?"
Après la résolution d'un ticket de support	Dans le fil du support	"Est-ce que ça a réglé le problème, ou y a-t-il encore un souci ?"
Quand un utilisateur bloque ou abandonne un parcours	E-mail, un jour plus tard	"Vous vous êtes arrêté à l'étape 3 de la configuration. Qu'est-ce qui vous a freiné ?"
Après 30 jours d'usage régulier	E-mail d'une personne identifiée	"Quelle est la seule chose que vous changeriez ?"
Quand un utilisateur résilie	Dans le parcours de résiliation	"Qu'est-ce qui vous a fait décider de partir aujourd'hui ?"
Après la livraison de ce qu'il avait demandé	Là où il l'avait demandé	"Vous aviez demandé l'import CSV. C'est en ligne. Cela couvre-t-il votre cas ?"

Quel est le bon moment pour demander un feedback ?

Le bon moment est juste après que l'utilisateur a terminé quelque chose, tant que le détail est encore frais dans sa tête. Une question qui suit une action obtient une réponse sur cette action. Une question qui arrive de nulle part obtient une réponse sur l'humeur du moment, ou aucune réponse.

Ne demandez pas à l'inscription, car personne n'a rien utilisé. Ne demandez pas au milieu d'une tâche, car vous interrompez ce que vous voulez comprendre. Quand une personne a répondu, laissez-la tranquille jusqu'à ce que vous ayez quelque chose à lui annoncer en retour.

Où demander un feedback client ?

Demandez à l'endroit où l'expérience a eu lieu. Une invite dans l'app convient à une question sur un écran. Le fil du support convient à une question sur un correctif. L'e-mail convient à une question sur une semaine d'usage, ou sur un parcours que la personne a abandonné. Un appel convient aux questions qu'on ne peut pas prévoir.

Chaque canal donne un type de réponse différent :

Dans l'app : court, immédiat et précis, mais seulement de la part des personnes présentes. Vous n'entendez rien des utilisateurs partis.
Fil du support : de la part de gens déjà assez frustrés pour écrire. Utile pour trouver ce qui est cassé, peu pour juger le reste du produit.
E-mail : réponses plus longues de moins de monde, et seul moyen de joindre les utilisateurs devenus silencieux. Écrivez-le comme un court message d'une personne identifiée, avec une seule question dedans.
Entretien : la façon de comprendre pourquoi les gens font ce qu'ils font. Demandez-leur de vous montrer comment ils travaillent, et taisez-vous pendant qu'ils le font.

La qualité du signal de feedback explique comment pondérer ce que chaque canal vous apprend.

Comment demander un feedback de façon professionnelle ?

Soyez précis sur l'objet, dites pourquoi vous demandez, et faites en sorte que la réponse prenne moins d'une minute. Une demande professionnelle nomme le moment, fait comprendre qu'une personne lira la réponse, et ne s'excuse pas de déranger.

Nommez l'action exacte ("l'export que vous venez de lancer"), demandez une seule chose, utilisez une zone de texte libre sans champ obligatoire, et signez d'un prénom.

Quelle bonne phrase pour demander un feedback ?

Une bonne phrase est une question sur un moment précis, à laquelle on peut répondre en quelques mots. Comparez les deux colonnes ci-dessous. Celles de gauche appellent un haussement d'épaules. Celles de droite obligent la personne à se rappeler quelque chose de réel.

Demande faible	Demande plus forte
"Un avis ?"	"Quelle a été la partie la plus difficile de cette configuration ?"
"Comment trouvez-vous notre produit ?"	"À quoi l'avez-vous utilisé la semaine dernière ?"
"Notez votre expérience de 1 à 10."	"Avez-vous fait aujourd'hui ce que vous veniez faire ?"
"Dites-nous comment nous améliorer."	"Qu'est-ce qui vous a ralenti cette semaine ?"
"Nous recommanderiez-vous ?"	"À qui l'avez-vous montré en dernier, et qu'avez-vous dit ?"

Une autre qui marche presque partout : "Que faites-vous à la place quand ça ne vous convient pas ?" Elle fait remonter le vrai concurrent, qui est souvent un tableur.

Quelles sont les pires façons de demander un feedback ?

Les pires demandes sont vagues, prématurées, longues ou orientées. Elles ont un défaut commun : la personne ne peut pas répondre sans faire la réflexion que vous auriez dû faire.

"Merci de remplir notre enquête de 20 questions." Ceux qui vont au bout sont ceux qui ont le plus de temps libre ou les opinions les plus tranchées.
Une pop-up sur la première page après la connexion. L'utilisateur venait faire quelque chose et vous l'avez bloqué. La fermer est la seule réponse raisonnable.
"Nous aimerions avoir votre avis !" sans aucune question. Cela demande à l'utilisateur d'inventer le sujet.
Une question orientée : "À quel point aimez-vous le nouveau tableau de bord ?" Vous obtenez un accord et n'apprenez rien.
Une note sans suite. Un 6 sur 10 vous dit l'humeur. Il ne vous dit pas quoi changer.
Demander, puis se taire. Cela vous coûte le tour suivant, comme on le verra plus bas.

Comment appelle-t-on les retours clients sur un produit ?

Les retours sur un produit s'appellent en général le feedback produit, et ils se rangent en deux sortes. Un rapport de bug dit que quelque chose ne marche pas comme prévu. Une demande de fonctionnalité dit que quelque chose manque. La distinction décide de qui s'en occupe en premier, et demande de fonctionnalité ou bug trace cette ligne. Une troisième sorte, les compliments, vaut la peine d'être gardée et citée avec permission.

Un formulaire de feedback qui propose "Bug" et "Demande de fonctionnalité" comme premier choix fait ce premier tri pour vous.

Que faire des réponses ?

Mettez chaque réponse là où l'équipe travaille déjà, avec les mots de la personne intacts. Une ligne citée vaut mieux que votre résumé. Étiquetez par type et urgence approximative, fusionnez les doublons, puis décidez : le construire, le mettre de côté ou le refuser.

Refuser compte aussi comme une réponse. "Nous n'allons pas construire ça, et voici pourquoi" met fin à l'attente, et refuser une demande de fonctionnalité propose des formulations. Pour la tuyauterie, le suivi des demandes de fonctionnalités décrit comment ramener les demandes de cinq canaux dans une seule liste. Si vous recevez des demandes par écrit, un template de demande de fonctionnalité les garde comparables.

Le widget de Changeloop crée chaque soumission comme une issue GitHub, si bien que le feedback atterrit à côté du code qui le traitera. Avec n'importe quel outil, la règle est la même : une liste, un responsable, aucune réponse oubliée dans la boîte de réception de quelqu'un.

Pourquoi dire ce qui a été livré ?

Cela montre à la personne que répondre valait son temps. Un utilisateur qui vous a dit quelque chose et apprend plus tard "c'est livré, merci" a une raison de répondre à nouveau. Celui qui n'entend rien en conclut que personne ne lit la boîte.

La dernière étape de la demande est donc une réponse. Dites à chaque personne qui a demandé quand sa demande est livrée, dans ses propres termes, sur le canal qu'elle a utilisé. Fermer la boucle de feedback client décrit le mécanisme : l'entrée de changelog publiée déclenche le message, si bien que le demandeur n'est prévenu qu'une fois le changement en ligne. Dans Changeloop, quand un feedback du widget est devenu une issue GitHub et que la pull request fusionnée la ferme, approuver l'entrée poste un commentaire "Shipped" sur cette issue et montre l'entrée à l'auteur de la soumission dans le widget ; les issues créées à la main, et les dépôts GitLab ou Bitbucket, ne reçoivent aucun commentaire. Notre documentation liste la configuration du widget et du flux.

Une réponse peut être courte : "Vous aviez demandé l'import CSV en mars. C'est en ligne aujourd'hui, voici comment ça marche." Elle vous donne aussi la meilleure question suivante : est-ce que cela couvre ce dont la personne avait besoin ?

Un plan pour démarrer

Choisissez un moment dans le tableau du haut, celui où les utilisateurs réussissent ou abandonnent le plus souvent. Écrivez une question pour lui, placez-la dans un canal, et lisez chaque réponse pendant deux semaines avant d'ajouter une deuxième invite. Répondez à toute personne qui vous a donné quelque chose de concret.

FAQ

À quelle fréquence faut-il demander un feedback aux clients ? Rattachez les demandes à des événements, pas à un calendrier. Un utilisateur ne devrait voir qu'une invite par semaine au plus, et aucune juste après en avoir rempli une. Le message qui suit un feedback doit être une réponse sur ce qu'il est devenu.

Comment demander un feedback sans agacer les utilisateurs ? Demandez après une tâche, jamais au milieu d'une tâche, limitez-vous à une question et facilitez le refus. Respectez un refus pendant quelques semaines.

Faut-il offrir une contrepartie pour un feedback ? En général ce n'est pas nécessaire. Une question précise et une réponse visible pèsent plus qu'une carte cadeau, et les contreparties attirent des gens qui veulent la récompense. Gardez-les pour les entretiens, où vous demandez 20 minutes du temps de quelqu'un.

Que faire si personne ne répond ? Resserrez la question et rapprochez-la du moment, par exemple un seul écran, posée juste après son utilisation. Si le silence persiste, écrivez directement à quelques utilisateurs et servez-vous de ces échanges pour écrire de meilleures invites.

Exemples de roadmap produit : six formats et leurs limites

Fri, 02 Oct 2026 00:00:00 GMT

Les exemples de roadmap produit qui méritent d'être copiés se rangent en six formats : Now/Next/Later, une frise trimestrielle, une roadmap par thèmes, une roadmap par résultats, une roadmap publique et une roadmap de releases interne. Chacun répond à une question différente pour un lecteur différent ; le bon exemple est donc celui qui correspond à la personne qui lira la vôtre. La mise en page vient en dernier.

Tous les exemples ci-dessous portent sur un produit imaginaire, une petite application de tâches pour équipes, et chaque élément est inventé. Ce qui compte, c'est la forme : ce qui va dans chaque case, à quoi ressemble une vraie entrée, et ce qui fait craquer ce format au bout d'un trimestre.

Quels sont de bons exemples de roadmap produit ?

Un bon exemple de roadmap est court, nomme son lecteur et fait un seul type de promesse. Choisissez le format selon la promesse que vous êtes prêt à tenir : une direction, une date, un thème de travail, un résultat, un engagement public ou un calendrier de livraison.

Format	Pensé pour	Fonctionne quand	Échoue quand
Now/Next/Later	Toute l'entreprise	Les plans changent souvent	"Next" se remplit et devient une file d'attente
Frise trimestrielle	Ventes, support, direction	Les dates sont de vraies contraintes	Les dates glissent et personne ne les met à jour
Par thèmes	Direction, nouvelles recrues	Vous voulez expliquer le pourquoi	Les thèmes deviennent si larges que tout y rentre
Par résultats	Produit et ingénierie	Vous pouvez mesurer l'objectif	La métrique n'a ni responsable ni données
Publique	Clients	Vous savez la garder petite	Elle devient un fourre-tout de backlog
Releases interne	Ingénierie, QA, support	Plusieurs équipes livrent ensemble	On la prend pour de la stratégie

À quoi ressemble chaque exemple de roadmap produit ?

Chaque format ci-dessous est montré avec des entrées réalistes, suivies de ceux à qui il convient, de ce qui le fait tenir et de la façon dont il échoue d'ordinaire.

Now/Next/Later

NOW (en cours de construction ce mois-ci)
  Vues enregistrées dans la boîte de réception
  Export CSV fiable pour les gros comptes
NEXT (décidé, ordre non fixé)
  SSO pour le plan Team
  Notifications Slack
LATER (une direction, aucun engagement)
  Application mobile
  Journal d'audit

Ce format convient à une entreprise qui ne veut pas promettre de dates, ce qui est le cas de beaucoup d'équipes en phase de démarrage. Il tient parce que les trois colonnes décrivent votre degré de certitude : "now" est en cours, "next" est décidé, "later" est un espoir. Il échoue quand "later" devient le parking de toutes les idées qu'on n'ose pas refuser, et quand "next" acquiert discrètement un ordre et une date sans que personne parle de calendrier.

Frise ou roadmap trimestrielle

T4 2026
  Oct   Vues enregistrées dans la boîte de réception
  Nov   SSO en bêta avec cinq partenaires de conception
  Déc   SSO en disponibilité générale
T1 2027
  Jan   Notifications Slack
  Mar   Journal d'audit (export seulement)

Ce format convient aux ventes, au support et à la finance, qui doivent planifier autour de quelque chose. Il fonctionne quand les dates sont de vraies contraintes : un contrat, une conférence, une échéance de conformité. Il échoue quand les dates sont des suppositions, car un mois affiché sur une roadmap devient une promesse dans une présentation commerciale en quelques semaines. Si vous choisissez ce format, indiquez pour chaque trimestre s'il est engagé ou prévisionnel, et rendez le deuxième trimestre visiblement plus flou que le premier.

Roadmap par thèmes

THÈME : première semaine d'utilisation
  Import depuis CSV et Trello
  Modèles de démarrage
THÈME : prêt pour les grandes équipes
  SSO
  Journal d'audit
  Permissions par rôle
THÈME : moins d'étapes manuelles
  Notifications Slack
  Tâches récurrentes

Ce format convient aux points avec la direction et aux nouvelles recrues, parce qu'il explique pourquoi le travail existe avant d'énumérer le travail. Il tient quand chaque thème correspond à une raison pour laquelle un client s'en soucierait. Il échoue quand les thèmes sont si larges ("Croissance", "Qualité") que chaque élément rentre sous chacun d'eux ; le regroupement n'explique alors plus rien.

Roadmap par résultats

OBJECTIF : plus d'équipes terminent la configuration
  Métrique : config terminée en 7 jours, de 40 % à 55 %
  Paris : import CSV, modèles de démarrage
OBJECTIF : moins de tickets support sur les exports
  Métrique : tickets d'export par semaine, de 30 à 10
  Paris : correctif des gros comptes, page d'état des exports

Les chiffres sont illustratifs, et c'est la structure qui compte : un objectif, une métrique avec un point de départ et une cible, et les paris que vous allez tenter. Ce format convient aux équipes produit et ingénierie à qui l'on fait confiance pour choisir la solution. Il fonctionne quand la métrique existe et que quelqu'un en répond. Il échoue quand l'objectif n'est pas mesurable, ou quand les "paris" sont la même liste de fonctionnalités qu'avant, avec une phrase de résultat collée par-dessus.

Roadmap publique orientée client

PLANIFIÉ
  Vues enregistrées dans la boîte de réception
EN CONSTRUCTION
  Notifications Slack
LIVRÉ
  Export CSV pour les gros comptes

C'est le plus petit format, et il fait la promesse la plus forte. Il convient aux clients, qui veulent savoir si leur demande a été entendue. Il tient avec très peu d'éléments, sans dates, et avec des titres écrits dans les mots du client. Il échoue en fourre-tout de backlog : chaque "peut-être" que vous affichez est une promesse dont quelqu'un vous demandera des comptes plus tard. Le fonctionnement concret à partir de votre issue tracker se trouve dans une roadmap publique en trois colonnes, on ne le répète donc pas ici.

Roadmap de releases interne

Release	Cible	Responsable	Dépend de	Statut
5.2	14 oct.	Plateforme	Mise à jour du service d'auth	Code terminé
5.3	11 nov.	Inbox	API des vues enregistrées	En cours
5.4	9 déc.	Plateforme	Contrat du fournisseur SSO	Bloqué

Ce format convient à l'ingénierie, à la QA et au support, qui doivent savoir ce qui part ensemble et ce qui bloque quoi. Il fonctionne quand il est exact à la semaine près et qu'il y a un responsable par ligne. Il échoue quand quelqu'un le prend pour de la stratégie : un calendrier de livraison dit ce qui sort et quand, et ne dit rien sur la pertinence de ces releases.

Quel format de roadmap produit choisir ?

Choisissez d'abord selon le lecteur, puis selon le degré de certitude dont vous disposez réellement. Si vous ne pouvez pas nommer qui lit la roadmap et quelle décision elle l'aide à prendre, aucun des exemples ci-dessus ne la sauvera.

Des clients qui demandent "m'avez-vous entendu ?" Utilisez le format public, avec une poignée d'éléments.
Des ventes et un support qui demandent "puis-je donner une date au client ?" Utilisez la frise trimestrielle, en séparant clairement l'engagé du prévisionnel.
Une direction qui demande "pourquoi ce travail ?" Utilisez des thèmes, ou des résultats si vous avez les données.
Une équipe qui change de direction chaque mois. Utilisez Now/Next/Later et résistez à l'envie de le dater.
Des ingénieurs qui demandent "qu'est-ce qui sort quand ?" Utilisez la roadmap de releases, et gardez-la séparée de la stratégique.

La plupart des équipes finissent avec deux documents : une roadmap stratégique sous l'une des quatre premières formes, et un calendrier de releases en dessous. La roadmap publique est alors une vue filtrée de la stratégique, qui ne montre que ce sur quoi vous acceptez d'être jugé.

Comment rédiger une roadmap produit ?

Rédigez une roadmap en nommant le lecteur, en choisissant le format qui répond à sa question, en ne listant que les éléments que vous défendriez en réunion, et en donnant à chacun un statut et un responsable. Décidez ensuite à quelle fréquence elle sera relue, avant de la publier.

Nommez le lecteur et la décision. "Le support décide quoi dire aux clients sur le SSO" est une raison. "Tout le monde devrait voir la roadmap" ne vous donne rien à concevoir.
Partez de ce que vous savez déjà. Les demandes ouvertes, classées selon une règle que vous savez expliquer, sont une meilleure matière première qu'un brainstorming.
Écrivez chaque élément comme un résultat pour le client. "Garder un filtre que vous utilisez souvent" se lit mieux que "Implémenter la persistance des vues enregistrées", et ça dit au client si c'est son problème.
Décidez ce que la roadmap ne contiendra pas. Dates, estimations et backlog d'idées sont les trois exclusions habituelles.
Fixez une date de relecture. Une roadmap sans relecture planifiée a des funérailles non planifiées.

Comment garder une roadmap produit à jour ?

Gardez une roadmap à jour en déplaçant les éléments quand le travail avance, depuis l'endroit où le travail est suivi, et en consignant ce qui s'est passé quand un élément est livré ou abandonné. Une roadmap qu'on met à jour à la main dans un outil séparé devient obsolète parce que ce n'est le travail quotidien de personne.

La source de vérité la moins coûteuse est l'issue tracker. Si chaque colonne de la roadmap correspond à un label sur l'issue, la roadmap change quand le label change, et rien n'est ressaisi. La version de Changeloop utilise les labels roadmap:planned, roadmap:building et roadmap:shipped, et quand une issue en porte deux, le plus avancé l'emporte. Déplacer une carte vers livré reste un changement de label à part ; intégrez-le à la relecture où vous approuvez l'entrée du changelog.

Cette entrée est l'autre moitié. Quand un élément est livré, le changelog dit ce qui a changé dans les termes du client, et la personne qui l'avait demandé peut être prévenue. Fermer cette boucle est tout l'objet de la boucle de feedback client, et la roadmap est la partie de cette boucle que le client peut voir avant que quoi que ce soit ne soit livré. Si vous abandonnez un élément, dites-le ; un "non" public clôt aussi cette demande, et refuser une demande de fonctionnalité explique comment le formuler. Les équipes qui veulent voir à quoi ressemblent des entrées terminées peuvent parcourir des exemples de changelog.

FAQ

Quel est le format de roadmap produit le plus simple ? Now/Next/Later. Il a trois colonnes, n'exige aucune date et regroupe les éléments par degré de certitude. Pour une petite équipe qui change souvent de direction, c'est aussi le format le plus difficile à rater de façon embarrassante.

Combien d'éléments une roadmap produit devrait-elle contenir ? Moins que vous ne croyez. Moins de dix éléments toutes colonnes confondues suffisent pour une roadmap publique, et une roadmap stratégique interne dépasse rarement une douzaine. Au-delà, c'est un backlog avec un plus bel en-tête.

Une roadmap produit doit-elle comporter des dates ? Seulement si les dates sont de vraies contraintes, et alors uniquement pour le trimestre le plus proche. Au-delà, utilisez des colonnes ou des thèmes. Une date sur une roadmap devient un engagement dans une conversation commerciale, que vous l'ayez voulu ou non.

Quelle différence entre une roadmap produit et un plan de release ? Une roadmap dit ce que vous comptez construire et pourquoi. Un plan de release dit quelle version sort à quelle date et qui en répond. La roadmap change quand votre stratégie change, et le plan de release change quand le travail change.

Release management : processus pour équipes qui livrent vite

Fri, 02 Oct 2026 00:00:00 GMT

Un processus de release management est l'ensemble des étapes qui mène un changement de "fusionné" à "en production et expliqué aux personnes concernées". Pour une équipe qui livre souvent, il se résume à sept étapes : cadrer le périmètre, isoler le changement, construire et tester, approuver, déployer et vérifier, communiquer, et faire le bilan. Chaque étape a besoin d'un responsable nommé et d'un critère de sortie, sans quoi elle cesse discrètement d'avoir lieu.

Ce guide suppose une équipe de 5 à 50 ingénieurs qui déploient chaque semaine ou chaque jour et veulent que le processus reste discret.

Étape	Responsable	Critères de sortie
1. Cadrer le périmètre	Product ou tech lead	La liste des changements de cette release est écrite, et tout ce qui est risqué est marqué
2. Branche ou flag	L'ingénieur qui porte le changement	Le travail est sur une branche de courte durée ou derrière un flag, pour que main reste livrable
3. Construire et tester	La CI, avec l'auteur d'astreinte en cas d'échec	Pipeline vert sur le commit exact qui sera livré
4. Approuver	Relecteur, plus le release manager pour les changements risqués	Revue faite, chemin de rollback nommé, décision go ou no-go consignée
5. Déployer et vérifier	Release manager ou ingénieur d'astreinte	Déployé, smoke checks réussis, taux d'erreur et latence conformes à la référence d'avant release
6. Communiquer	Celui qui comprend le changement, relu par quelqu'un qui ne le comprend pas	Release notes publiées là où les utilisateurs lisent, support et ventes prévenus
7. Faire le bilan	Release manager	Métriques lues, tout ce qui a mal tourné a un responsable et un correctif

Qu'est-ce que le processus de release management ?

C'est le chemin reproductible qu'un changement suit pour atteindre les utilisateurs : périmètre, build, test, approbation, déploiement, vérification, annonce, et retour d'expérience. L'intérêt de l'écrire est que chaque release suit le même chemin, de sorte qu'une personne en vacances, une nouvelle recrue ou un ingénieur d'astreinte à 2 h du matin puisse l'exécuter sans demander à personne comment ça marche.

Quels sont les différents types de release management ?

Il y en a trois en pratique : le déploiement continu, les releases planifiées et la gestion des changements réglementée. Ils diffèrent par ce qui se passe avant une release et par ce qui est automatisé. Le déploiement continu livre chaque changement fusionné, les releases planifiées regroupent les changements dans un train, et la gestion réglementée des changements ajoute une approbation formelle et une piste d'audit.

	Déploiement continu	Releases planifiées	Gestion des changements réglementée ou ITIL
Unité de release	Une pull request fusionnée	Un lot, hebdomadaire ou bimensuel	Une demande de changement
Étape de périmètre	Implicite, la fusion est le périmètre	Réunion de planification de release	Fiche de changement avec niveau de risque
Approbation	Revue de code plus contrôles automatisés	Le release manager valide le lot	Comité consultatif des changements ou approbateur délégué
Maîtrise du risque	Feature flags, canaries, rollback rapide	Test en staging, release candidate	Plan de retour arrière documenté, fenêtre de maintenance
Rythme typique	Plusieurs par jour	Hebdomadaire à mensuel	Fixé par le calendrier des changements
Point faible	Personne ne dit aux utilisateurs ce qui a changé	Les gros lots cachent le changement qui a tout cassé	Le temps de processus écrase le changement lui-même

La plupart des équipes sont un mélange. Un produit SaaS peut déployer en continu pendant que son application mobile part sur un train hebdomadaire, et l'unique service de paiement qui intéresse les auditeurs suit une fiche de changement formelle. Choisissez le type par service, pas par entreprise. Quand les changements ne sont exposés que progressivement, la release et l'annonce deviennent deux événements distincts, ce que couvrent les release notes avec feature flags.

Quelles sont les responsabilités d'un release manager ?

Un release manager est responsable du chemin que suit un changement jusqu'à la production. Il tient le calendrier des releases, décide si un changement est prêt, exécute ou supervise le déploiement, prend la décision de rollback, veille à ce que les utilisateurs soient prévenus et mène le bilan ensuite.

Avant la release, il confirme le périmètre et vérifie que chaque changement risqué a un chemin de rollback. Pendant, il déroule la checklist de déploiement, surveille les premières minutes des métriques de production et déclenche tôt un rollback. Après, il confirme que les notes sont sorties et consigne ce qu'il faut corriger dans le processus.

Dans une petite équipe, faites tourner le rôle chaque semaine et rédigez la checklist pour que personne n'ait besoin d'un savoir tribal. Un monorepo avec de nombreux paquets publiés indépendamment demande en général un responsable de release par paquet, sans quoi le rôle devient un goulot d'étranglement.

Quels sont les KPI clés du release management ?

Suivez les métriques de livraison logicielle de DORA, et ajoutez-en une de votre cru : le temps qu'il faut pour que les utilisateurs soient prévenus. La recherche de DORA identifie cinq métriques, réparties entre débit (délai de mise en production d'un changement, fréquence de déploiement, temps de rétablissement après un déploiement raté) et instabilité (taux d'échec des changements, taux de reprise des déploiements).

Le guide de DORA les définit simplement (dora.dev, software delivery metrics) :

KPI	Ce qu'il mesure	Ce qu'il faut surveiller
Délai de mise en production (change lead time)	Temps entre le commit dans le contrôle de version et le déploiement en production	Un chiffre qui monte signale en général des files d'attente en revue ou en approbation
Fréquence de déploiement	Combien de fois vous déployez, ou le temps entre deux déploiements	Une fréquence qui baisse signifie que les lots grossissent
Temps de rétablissement après déploiement raté	Temps pour se remettre d'un déploiement qui exige une intervention immédiate	Les problèmes de rollback et d'alerte apparaissent ici
Taux d'échec des changements	Part des déploiements qui exigent un rollback ou un hotfix	Monte quand les lots sont trop gros ou les tests trop minces
Taux de reprise des déploiements	Part des déploiements non planifiés et causés par un incident de production	Signe que les correctifs sortent plus vite que les leçons
Délai avant information des utilisateurs	Minutes entre le déploiement en production et une note publiée côté utilisateurs	À mesurer vous-même, aucun framework ne la fournit

Les anciens documents listent quatre métriques clés et appellent le rétablissement "time to restore". Le guide actuel utilise les cinq ci-dessus.

Le même guide met en garde contre le fait d'en faire des cibles. Fixer un objectif comme "tout se déploie plusieurs fois par jour d'ici la fin de l'année" pousse les équipes à tricher avec les chiffres, et les métriques sont à lire par application ou par service, pas mélangées à l'échelle de l'entreprise. Son conseil pratique pour les améliorer toutes est de réduire la taille de chaque changement, car les petits changements sont plus faciles à relire, à faire passer dans le pipeline et à rattraper.

Comment la communication de release s'intègre-t-elle au processus de release management ?

C'est l'étape six, et elle a un responsable et un critère de sortie comme toutes les autres : notes publiées là où les utilisateurs lisent, et équipes internes prévenues. C'est celle que les équipes sautent le plus souvent, parce que l'outillage de déploiement annonce le succès dès que le code est en ligne.

Le moyen le moins coûteux de tenir cette étape est d'écrire l'entrée quand le changement est fusionné, pas quand la release part. La pull request contient déjà le titre, l'auteur, l'issue liée et le contexte. Un brouillon construit à partir d'elle se retouche au lieu de s'écrire de mémoire une semaine plus tard. C'est l'idée de l'automatisation du changelog : dériver un brouillon à la fusion, le retenir pour approbation humaine, puis le publier partout depuis une seule source. Changeloop fonctionne ainsi, rédigeant des entrées à partir des pull requests fusionnées avec l'IA et les retenant pour approbation avant toute publication.

Deux variantes méritent d'être prévues à l'avance. Le support et les ventes ont besoin d'une autre note que les clients, ce à quoi servent les notes de release internes. Une release déclenchée par un incident n'a pas le temps de suivre la boucle de rédaction habituelle ; gardez donc un modèle court sous la main, comme décrit dans release notes d'urgence. Le modèle de release notes vous donne une forme de départ pour la version destinée aux clients.

Comment garder le processus léger ?

Automatisez chaque critère de sortie qu'une machine peut vérifier, et gardez les humains pour les jugements. Un pipeline vert, un marqueur de déploiement sur les tableaux de bord et une entrée de changelog brouillon par pull request fusionnée se vérifient. Savoir si un plan de rollback est crédible, ou si les notes parlent à un client, demande une personne.

Pour tester le processus, prenez une release du mois dernier et demandez si quelqu'un hors de l'équipe pourrait dire, à partir du seul dossier écrit, ce qui est sorti, qui l'a approuvé, comment cela a été vérifié et quand les utilisateurs ont été prévenus. Chaque trou est votre prochaine amélioration.

FAQ

Quelle différence entre release management et change management ? Le release management fait construire, tester, déployer et annoncer un ensemble de changements. Le change management, au sens ITIL, est le processus d'approbation et de risque autour de chaque changement. Les équipes qui livrent souvent intègrent l'approbation à la revue de code et aux contrôles automatisés.

À quelle fréquence faut-il livrer ? Aussi souvent que vos tests et votre chemin de rollback le permettent, ce qui pour beaucoup d'équipes web veut dire chaque jour ou plus. Le conseil de DORA est de réduire la taille de chaque changement, car les petits changements sont plus faciles à relire et à rattraper.

Les petites équipes ont-elles besoin d'un release manager ? Elles ont besoin des responsabilités, pas forcément du titre. Faites tourner le rôle entre ingénieurs, donnez à la personne de tour une checklist écrite, et veillez à ce que quelqu'un porte chacune des sept étapes.

Que doit contenir une checklist de release ? Périmètre confirmé, pipeline vert sur le commit livré, chemin de rollback nommé, approbation consignée, smoke checks après déploiement, métriques comparées à la référence, release notes publiées, support prévenu et bilan planifié. Tenez-la sur une page.

Exemples de release notes pour chaque type de changement

Fri, 02 Oct 2026 00:00:00 GMT

Les meilleurs exemples de release notes sont courts, nomment les personnes concernées et disent quoi faire ensuite. Voici un exemple pour chaque type de changement que vous livrerez, avec la raison pour laquelle il fonctionne, pour que vous puissiez copier la forme et y mettre vos propres faits.

Tous les exemples sont inventés, pour une application de facturation fictive appelée Tidepool.

Que partagent les bons exemples de release notes ?

Ils disent aux utilisateurs ce qui a changé et ce qu'ils doivent éventuellement en faire, avec leurs mots à eux. Chaque type de changement a un rôle différent, donc la forme varie de l'un à l'autre.

Type de changement	L'entrée doit dire	Où la placer
Nouvelle fonctionnalité	Ce que le lecteur peut faire maintenant, et qui y a accès	En haut des notes
Amélioration	Ce qui est devenu plus rapide ou plus simple, avec un chiffre si possible	Après les fonctionnalités
Correctif	Le symptôme que le lecteur a vu, et que c'est corrigé	Après les améliorations
Changement cassant	Qui est concerné, la date, la migration	Toujours en premier
Correctif de sécurité	Ce qui était exposé, si cela a été exploité, quoi faire	En premier
Dépréciation	Ce qui disparaît, la date de fin, le remplacement	Près du haut
Note pour l'app store	Une phrase simple par changement, dans la limite de caractères	Fiche de la boutique
Note interne	Ce qui a changé et ce qu'il faut dire aux clients	Canaux support et ventes

À quoi ressemble une bonne note de nouvelle fonctionnalité ?

Une bonne note de fonctionnalité s'ouvre sur ce que le lecteur peut faire maintenant et nomme les plans ou les rôles qui y ont accès. Elle laisse de côté l'implémentation.

Envoyez vos factures dans la langue du client. Vous pouvez désormais choisir une langue pour chaque client, et ses factures, ses relances et sa page de paiement la suivent. Le français, l'allemand, l'espagnol et le portugais sont disponibles sur tous les plans. Réglez-la depuis la page du client, sous Préférences de facturation.

Le titre est une phrase que le lecteur dirait à voix haute, et le corps donne la portée et l'emplacement. Un lecteur qui ne parcourt que la ligne en gras sait déjà ce qui est sorti. La méthode générale est dans comment écrire des release notes.

À quoi ressemble une bonne note d'amélioration ?

Une note d'amélioration décrit un changement que le lecteur va ressentir, et y met un chiffre mesuré quand il en existe un. Sans chiffre, dites ce que le lecteur n'a plus à faire.

La liste des factures se charge environ trois fois plus vite. Les comptes de plus de 5 000 factures attendaient environ neuf secondes pour la liste. Elle s'ouvre maintenant en trois secondes environ. Aucune action requise.

"Améliorations de performance" ne dit rien au lecteur, alors que neuf secondes contre trois est une affirmation qu'il peut vérifier lundi matin. Le "Aucune action requise" final répond à la question que chaque lecteur se pose.

À quoi ressemble une bonne note de correctif ?

Une note de correctif décrit le symptôme que l'utilisateur a vu, pas la cause dans le code, et dit s'il doit refaire quelque chose. Les corrections que personne n'a remarquées peuvent aller dans la liste du bas.

Corrigé : e-mails de relance envoyés en double le jour d'échéance. Certains clients recevaient deux relances identiques lorsque leur facture arrivait à échéance le dernier jour d'un mois. C'est corrigé. Les relances déjà envoyées ne sont pas concernées, et personne n'a besoin de rien renvoyer.

Le titre commence par "Corrigé" pour qu'un lecteur qui survole puisse trier d'un coup d'œil, et la vraie condition (le dernier jour du mois) suit aussitôt.

Comment rédiger des release notes pour un changement cassant ?

Une note de changement cassant commence par la date et le groupe concerné, puis donne la migration dans la même entrée. Elle va en premier dans les release notes, parce que c'est l'entrée qu'un lecteur ne doit pas manquer.

Les signatures de webhook deviennent obligatoires le 1er décembre 2026. À partir de cette date, Tidepool cesse d'envoyer des charges utiles de webhook non signées. Cela concerne toute personne qui reçoit des webhooks sans vérifier l'en-tête Tidepool-Signature. Pour migrer, vérifiez l'en-tête avec le secret sous Paramètres, Développeurs. Si vous vérifiez déjà les signatures, aucune action requise.

La date est dans le titre, donc elle survit à une lecture en diagonale. Le groupe concerné est désigné par ce qu'il fait, et la dernière phrase libère ceux qui sont déjà en règle, ce qui réduit la charge du support. Le guide sur les changements cassants explique comment décider si un changement en est un.

À quoi ressemble une note de correctif de sécurité ?

Une note de sécurité dit ce qui était exposé, si quelqu'un l'a exploité, qui est concerné et ce qu'il doit faire. Restez factuel et calme.

Sécurité : des liens de réinitialisation de mot de passe pouvaient être réutilisés. Entre le 3 et le 17 septembre 2026, un lien de réinitialisation de mot de passe restait valide après un premier usage. Nous n'avons trouvé aucun signe d'exploitation. C'est corrigé, et tous les liens de réinitialisation en attente ont été invalidés. Si vous avez demandé une réinitialisation pendant cette période, demandez un nouveau lien.

La période exacte permet au lecteur d'évaluer sa propre exposition, et la phrase sur l'exploitation répond à la première question que tout le monde pose. "Un problème potentiel" ressemble à de la dissimulation, alors dites ce que vous savez.

Comment rédiger un avis de dépréciation ?

Un avis de dépréciation nomme ce qui est retiré, donne une date de fin ferme et pointe vers le remplacement.

L'endpoint v1 des factures est déprécié et prend fin le 1er mars 2027. GET /v1/invoices continue de fonctionner jusqu'au 1er mars 2027, puis renvoie 410 Gone. Utilisez GET /v2/invoices, qui renvoie les mêmes champs plus currency. Les réponses de v1 incluent désormais un en-tête Sunset avec la date de fin. Un guide de migration côte à côte est dans la documentation.

Le nom de l'endpoint est dans le titre, parce que les personnes concernées le recherchent, et le remplacement se trouve à côté du retrait. L'en-tête Sunset indique aux développeurs quels appels utilisent encore l'ancienne version. Le traitement plus long est dans déprécier une API.

À quoi ressemble une note de release pour l'app store ?

Une note pour l'app store tient en deux ou trois phrases simples, parce que la plupart des gens ne lisent que la première ligne. Commencez par le changement qu'un utilisateur remarquerait.

Scannez un reçu papier et Tidepool remplit le montant, la date et le fournisseur. Le mode sombre suit désormais le réglage de votre téléphone. Nous avons aussi corrigé un plantage à l'ouverture d'une facture depuis une notification.

Le changement le plus utile vient en premier, et la correction nomme la situation qui plantait. Pas de numéro de version et pas de "corrections de bugs et améliorations". Les release notes pour applications mobiles couvrent les règles propres aux boutiques.

Que doit contenir une note de release interne ?

Une note interne est la version pour le support et les ventes. Elle ajoute ce que la note publique omet : ce qu'il faut dire, et ce qu'il faut éviter de promettre.

Les factures multilingues sont sorties aujourd'hui (tous les plans). Support : les clients règlent la langue sous Préférences de facturation, et les factures existantes gardent leur langue d'origine. L'italien n'est pas encore disponible. Ventes : c'est ouvert à tous les plans, ne le présentez donc pas comme une montée en gamme.

Chaque public a sa propre ligne étiquetée, et la note pose la limite ("L'italien n'est pas encore disponible") avant qu'un client ne la demande. L'article sur les notes de release internes couvre le format et les canaux.

À quoi ressemble une mauvaise note de release, réécrite ?

Une mauvaise note de release énumère ce que l'équipe a fait au lieu de ce que le lecteur obtient. Corrigez-la en mettant le résultat en tête et en supprimant le vocabulaire interne.

Avant :

v3.8.1 Refactorisation du planificateur de relances. Correction d'une race condition dans ReminderJob. Mise à jour de bull en 4.12. Améliorations diverses.

Après :

Les e-mails de relance ne partent plus en double. Les clients dont une facture arrivait à échéance le dernier jour d'un mois pouvaient recevoir deux relances. C'est corrigé, et les relances déjà envoyées n'ont pas besoin d'être renvoyées. Aucune action requise.

Aussi dans 3.8.1 : bull mis à jour en 4.12.

La mise à jour de dépendance est descendue en pied de note, et la race condition est devenue un symptôme qu'un client reconnaîtrait.

Comment garder des release notes cohérentes d'une version à l'autre ?

Rédigez chaque entrée quand le changement est fusionné, et faites-la approuver par une personne avant la livraison.

Changeloop fonctionne ainsi : il rédige une entrée à partir de chaque pull request fusionnée avec l'IA et la retient jusqu'à ce qu'un humain l'approuve. C'est à l'étape d'approbation qu'un éditeur applique les règles ci-dessus. Pour fixer d'abord le format, partez du modèle de release notes, et consultez des exemples de changelog pour voir à quoi ressemblent des pages terminées.

FAQ

Que sont de nouvelles release notes ? De nouvelles release notes sont le message publié avec la dernière version d'un produit, qui décrit ce qui a changé et ce que les utilisateurs doivent faire. Elles couvrent les fonctionnalités, les améliorations, les correctifs et les changements cassants.

Quelle est la différence entre une release note et un changelog ? Le changelog garde tout, pour quiconque veut l'historique complet. Une release note y puise : une seule version, écrite pour les lecteurs qui se demandent si elle les concerne. La comparaison complète est dans changelog vs release notes.

Que signifie release notes ? Les release notes disent aux utilisateurs ce qui a changé dans une version. L'expression couvre tout ce qui explique ce qui est sorti, d'un texte "Nouveautés" de l'app store à une page du site d'une entreprise.

Quelle longueur pour chaque entrée de release notes ? Deux à quatre phrases suffisent pour la plupart des entrées : le résultat, les personnes concernées et quoi faire. Un changement cassant ou un correctif de sécurité peut être plus long, car il faut une date ou une migration.

Versionnage de l'API Stripe : fonctionnement et à copier

Fri, 02 Oct 2026 00:00:00 GMT

Le versionnage de l'API Stripe fonctionne par date. Chaque compte est épinglé sur une version d'API nommée d'après une date de publication, et n'importe quelle requête peut remplacer cet épinglage avec un en-tête Stripe-Version. Au moment de la rédaction (octobre 2026), la version actuelle dans la documentation de Stripe est 2026-09-30.endive, et le même schéma est à la portée d'une API bien plus petite, en un week-end.

Chaque fait sur Stripe ci-dessous vient des pages de Stripe elles-mêmes, liées à l'endroit où il est utilisé.

Mécanisme	Ce que fait Stripe	Source
Nom de version	Une date, plus un nom de release depuis 2024 (`2026-09-30.endive`)	Versioning
Version par défaut	Épinglée sur le compte, modifiable dans Workbench	Versioning
Remplacement par requête	En-tête `Stripe-Version`, ou l'option du SDK	Upgrades
Webhooks	Rendus dans la version définie sur l'endpoint	Upgrades
Rythme	Releases mensuelles sans changement cassant, une release majeure deux fois par an	Versioning
Anciennes versions	Maintenues grâce à des modules internes de changement de version	Engineering post

Comment fonctionne le versionnage de l'API Stripe ?

Stripe donne à chaque compte une version d'API par défaut, et toute requête qui ne nomme pas de version l'utilise. Les appelants choisissent quand changer, en modifiant la valeur par défaut ou en indiquant une version sur chaque requête.

L'article d'ingénierie de Stripe explique que le compte est épinglé dès sa première requête à l'API : il est "automatically pinned to the most recent version available", et ensuite chaque appel se voit attribuer cette version de manière implicite.

La version est une chaîne de date. Depuis la release 2024-09-30.acacia, elle porte aussi un nom, comme dans 2026-09-30.endive. La date ordonne les versions, et le nom indique à quelle famille de release majeure appartient une version.

Comment choisir une version par requête ?

Envoyez l'en-tête Stripe-Version avec la requête, ou définissez la version dans le SDK. Le guide de mise à niveau de Stripe montre la forme avec l'en-tête, et le même appel fonctionne en production comme en test.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Le guide de Stripe précise que lorsque vous définissez la version globalement ou par requête dans un SDK, les objets de réponse reviennent dans cette version.

Stripe déconseille aussi de s'appuyer sur la valeur par défaut du compte. Selon ses termes, indiquez la version pour chaque requête, avec l'en-tête ou un SDK épinglé, afin que votre code décide de la version et non un réglage du tableau de bord.

Les SDK s'épinglent différemment selon le langage. La documentation dit que les versions récentes des bibliothèques à typage dynamique utilisent la version d'API qui était la plus récente à la sortie de cette version du SDK, et que les bibliothèques fortement typées (Java, Go et .NET) y sont fixées. Installer une version de bibliothèque revient, en pratique, à choisir une version d'API.

Que deviennent les webhooks quand la version change ?

Un événement webhook est rendu dans la version d'API rattachée à son endpoint, et non dans celle que le code de votre serveur utilise. La documentation de Stripe indique que les événements utilisent la version définie à la création de l'endpoint, et sinon la valeur par défaut du compte. Changer la version de votre SDK ne change pas ce que reçoit votre gestionnaire de webhooks.

Votre chemin de requêtes et votre chemin d'événements peuvent donc reposer sur deux versions différentes. Pour les destinations d'événements, vous ne définissez snapshot_api_version qu'à la création de la destination ; une autre version signifie donc une nouvelle destination.

Le chemin de mise à niveau de Stripe pour cela est une exécution en parallèle. Créez un nouvel endpoint à la version cible, envoyez les mêmes événements aux deux, apprenez au gestionnaire à traiter l'un et à ignorer l'autre, puis basculez et désactivez l'ancien endpoint. Comme chaque événement arrive deux fois pendant le chevauchement, le gestionnaire doit être idempotent. C'est un bon schéma à copier pour toute API qui émet des événements, et un changelog de webhooks est l'endroit où annoncer les changements de charge utile qui le rendent nécessaire.

Que sont les releases mensuelles et majeures ?

Depuis la release 2024-09-30.acacia, Stripe publie une nouvelle version d'API chaque mois sans changement cassant, et émet une nouvelle release majeure deux fois par an, qui démarre avec une version contenant des changements cassants. Sa page de versionnage indique que vous pouvez passer à n'importe quelle release mensuelle sans modifier votre code, alors qu'une release majeure peut exiger des changements.

Les releases majeures portent des noms. La page de versionnage donne Basil en exemple, et l'annonce du processus par Stripe dit que les noms viennent de plantes, en commençant par Acacia, et que les releases mensuelles gardent le nom de la release majeure qui les précède pour signaler qu'on peut les adopter sans risque. Le changelog de Stripe liste les noms en usage, et au moment de la rédaction l'entrée la plus récente est 2026-09-30.endive.

La date répond donc à "quelle fraîcheur", et le nom à "est-ce une frontière cassante". L'annonce de Stripe garde aussi une marge pour les exceptions : elle se réserve le droit de publier un changement cassant hors cycle lorsqu'une intégration serait gravement touchée sans lui. L'annonce est sur Stripe's new API release process.

Quelle est la dernière version de l'API Stripe ?

Au moment de la rédaction (octobre 2026), la page de versionnage de Stripe indique que la version actuelle est 2026-09-30.endive, et son changelog liste la même version comme la plus récente. Stripe publie une nouvelle version chaque mois, donc toute chaîne imprimée dans un article vieillit vite. Lisez le changelog en direct avant d'épingler quoi que ce soit, et épinglez la version contre laquelle vous avez testé.

Comment Stripe maintient-il les anciennes versions ?

Stripe garde les anciennes versions en vie en écrivant chaque changement cassant sous forme de module de changement de version autonome et en appliquant les modules à rebours depuis la forme la plus récente des données. Son article d'ingénierie sur le versionnage d'API décrit le mécanisme.

Chaque module déclare ce qu'il change, documente le changement et inclut une fonction de transformation. L'article donne l'exemple d'un champ qui passe d'une chaîne à un hash. Pour construire une réponse, le système détermine la version cible, puis remonte le temps en appliquant chaque module rencontré en chemin jusqu'à atteindre cette version.

Deux effets de bord découlent de cette conception, et l'article nomme les deux. Comme les modules déclarent les champs et ressources qu'ils touchent, Stripe peut générer son changelog d'API à partir d'eux au déploiement. Et comme la version du compte est connue, la documentation peut s'y adapter et avertir des changements rétro-incompatibles depuis cette version.

Que coûte-t-il, et que doit copier une API plus petite ?

Le versionnage coûte de l'attention d'ingénierie, et Stripe le dit. L'article reconnaît une charge de maintenance et pose comme objectif que moins il faut penser aux anciens comportements en écrivant du nouveau code, mieux c'est. Il décrit aussi des revues d'API légères avant la sortie, pour éviter d'avoir besoin d'un changement de version.

Une petite API n'a pas les moyens d'avoir une chaîne de modules pour chaque ancienne version, et n'en a pas besoin. Copiez les éléments qui portent la valeur :

Des versions datées. Une date n'exige aucun jugement sur ce qui compte comme "majeur", et les appelants peuvent la lire. L'article sur les bonnes pratiques de versionnage la compare aux schémas par URL et par en-tête.
Une version par défaut épinglée. Fixez le compte ou la clé sur la version au premier usage, pour que l'API ne bouge jamais sous une intégration qui fonctionne.
Un remplacement par requête. Un en-tête qui permet à un appelant de tester une nouvelle version sur un seul appel, en production, avant de s'engager.
Une version sur l'endpoint de webhook. Les charges utiles d'événements sont l'endroit où les appelants sont le plus surpris.
Une entrée de changelog par version. Qu'elle nomme la version, la date, les personnes concernées et ce qu'il faut faire. Ce qui compte comme cassant est le test de ce qui a sa place dans une nouvelle version, et l'article sur le changelog d'API couvre l'entrée elle-même.

Sautez la chaîne de modules jusqu'à ce que le nombre de versions prises en charge l'impose. Deux ou trois versions actives se gèrent avec quelques branches et une date d'arrêt, que mettre fin à une version d'API détaille.

Si vous publiez un changelog daté, l'historique des versions ne vaut que ce que valent ses entrées. Dans Changeloop, une entrée brouillon est créée à partir de chaque pull request fusionnée et retenue jusqu'à l'approbation d'un humain avant d'être publiée sur la page de changelog et le flux. C'est là qu'on écrit l'entrée de chaque version, et l'unique validation humaine est la relecture qui dit ce qu'un appelant doit faire.

FAQ

Quelle est la dernière version de l'API Stripe ? Au moment de la rédaction (octobre 2026), la page de versionnage de Stripe indique que la version actuelle est 2026-09-30.endive. Stripe publie une nouvelle version chaque mois ; consultez donc son changelog avant d'épingler, et écrivez la version dans votre code au lieu de vous fier à la valeur par défaut du compte.

Comment définir la version de l'API Stripe sur une requête ? Envoyez l'en-tête Stripe-Version, par exemple Stripe-Version: 2026-09-30.endive, ou définissez la version dans votre SDK côté serveur, globalement ou par requête. Sans l'un ni l'autre, une requête utilise la version par défaut de votre compte, que vous définissez dans Workbench.

Les webhooks utilisent-ils la même version de l'API Stripe que mes requêtes ? Pas forcément. Les événements webhook utilisent la version définie à la création de l'endpoint, et la valeur par défaut du compte si aucune n'a été définie. Mettre à jour votre SDK ne change pas la charge utile que reçoit votre gestionnaire de webhooks ; mettez donc les endpoints à niveau séparément et testez-les en parallèle.

Le versionnage par date à la Stripe convient-il à une petite API ? Des versions datées, une version par défaut épinglée, un en-tête par requête et une entrée de changelog par version coûtent peu et valent d'être copiés. La chaîne interne de modules de changement de version, non, tant que vous n'avez pas à prendre en charge de nombreuses anciennes versions à la fois. Commencez avec deux versions actives et une date d'arrêt pour la plus ancienne.

Qui écrit le changelog, et qui devrait l'écrire

Tue, 22 Sep 2026 00:00:00 GMT

Demandez à une équipe qui écrit le changelog et la réponse honnête est généralement « qui s'en souvient », ce qui est le même mode d'échec qu'imposer une entrée de changelog en CI existe pour corriger au niveau mécanique. Mais forcer l'existence d'une entrée ne décide pas qui est qualifiée pour bien l'écrire, et les équipes qui sautent cette question ont tendance à se rabattre par défaut sur qui est le plus facile à contraindre, généralement l'autrice de la PR, sans vérifier si c'est vraiment la personne qui peut bien l'écrire.

Pourquoi l'autrice de la PR n'est-elle pas automatiquement la meilleure rédactrice de changelog ?

Parce qu'elle connaît l'implémentation, pas nécessairement l'impact, et ce sont deux types de connaissance différents. Où s'arrêtent les conventional commits couvre cet écart côté message de commit : fix(auth): reject expired refresh tokens est correct et ne dit rien à une cliente, et qui a écrit ce correctif est souvent la personne la moins équipée pour le traduire, parce qu'elle a pensé en termes du bug pendant des heures et a perdu la vue extérieure de ce qu'une utilisatrice a réellement vécu. C'est la même raison pour laquelle les rédactrices techniques existent en tant que profession : traduire l'implémentation en impact est une compétence distincte du fait d'avoir construit la chose, et ça demande de la pratique, peu importe la qualité de la développeuse sur le code lui-même.

Cela signifie-t-il que le produit ou le support devraient écrire chaque entrée à la place ?

Non, parce qu'ils ont l'écart inverse : ils savent ce qui compte pour les utilisatrices mais pas toujours ce qui a vraiment été livré, ce qui produit des entrées lisibles mais occasionnellement fausses sur la portée, une affirmation « supporte maintenant X » pour une fonctionnalité encore derrière un flag, ou un correctif décrit comme complet alors qu'il ne couvre qu'un cas sur trois. Le mode d'échec des entrées écrites par des développeuses est illisible-mais-précis ; le mode d'échec des entrées écrites par des PM est lisible-mais-non-vérifié. Aucun rôle ne possède les deux moitiés de ce dont une bonne entrée a besoin.

Rôle	Réussit généralement	Rate généralement
Développeuse qui a écrit le code	Portée exacte de ce qui a changé	Le cadrer pour quelqu'un qui ne l'a pas construit
PM ou responsable support	Pourquoi ça compte pour l'utilisatrice	Limites précises de ce qui a vraiment été livré
Responsable dédiée du changelog	Voix cohérente, vérifie la portée croisée	A besoin des deux ci-dessus pour vérifier

À quoi ressemble vraiment un modèle de propriété qui fonctionne ?

Un brouillon de qui est le plus proche du changement, revu par qui est le plus proche de l'utilisatrice, avec une personne nommée responsable de la formulation finale au lieu que tout le monde suppose que quelqu'un d'autre attrapera les problèmes. Le brouillon a davantage besoin d'exister et d'être précis que d'être bon ; une phrase brute écrite par une développeuse qui dit correctement ce qui a changé est un meilleur point de départ qu'une polie mais non vérifiée, parce que réécrire pour la clarté est plus facile que réécrire pour la justesse. L'étape de revue est où une PM ou responsable support lit le brouillon et pose la seule question qui attrape l'écart de lisibilité : est-ce que je comprendrais ça si je n'avais pas vu le code.

La même personne devrait-elle toujours être la responsable, ou est-ce que ça tourne ?

Nommée et stable bat tournante, au moins pour la validation finale. Une responsable tournante signifie que chaque entrée est revue par quelqu'un qui re-dérive les conventions de l'équipe à partir de zéro, ce qui est exactement comment la voix dérive d'entrée en entrée et une lectrice commence à remarquer que le changelog a été écrit par un comité. Une seule personne, ou un très petit groupe stable, accumule les jugements avec le temps, quand dire « amélioré » plutôt que nommer le chiffre spécifique, quand un correctif a besoin de sa propre entrée plutôt que d'être fondu dans un lot, et ce jugement vaut plus que distribuer le travail équitablement.

Brouillon (développeuse, depuis la PR) :
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revu (responsable du changelog, vérifié contre la vraie PR) :
"Corrigé : les exports triés par date pouvaient retourner
des résultats désordonnés au-delà de la première page.
Maintenant cohérent sur toutes les pages."

Une petite équipe a-t-elle besoin d'autant de processus pour une ligne de texte ?

Pas les rôles en tant que personnes séparées, mais les deux étapes comptent encore même en solo. Une équipe d'une personne est à la fois la développeuse et la revieweuse, et la discipline qui survit à cette échelle est de faire la revue comme un passage mental séparé, pas de sauter directement de l'écriture du correctif à la publication d'une description de celui-ci dans le même souffle. Le piège à petite échelle, c'est de sauter entièrement le deuxième passage, pas le manque d'une deuxième personne, parce que personne d'externe ne l'impose, et l'écart de précision que ce passage existe pour attraper ne disparaît pas juste parce que la même personne pourrait théoriquement remarquer son propre angle mort.

Que se passe-t-il quand personne n'est responsable de l'entrée finale ?

Le changelog se dégrade de façon inégale plutôt que d'échouer carrément, ce qui est pire parce que personne ne le remarque jusqu'à ce qu'une lectrice le signale. Certaines entrées restent nettes parce que qui les a écrites s'en souciait ; d'autres deviennent vagues, « diverses améliorations et corrections de bugs », parce que qui les a écrites allait vite et que personne ne l'a attrapé avant publication. Les contraintes de format de Keep a Changelog attrapent la dérive structurelle, dates manquantes, mauvaises catégories, mais rien dans un modèle n'attrape une entrée vague qui est techniquement bien formatée, ce qui est exactement l'écart qu'une responsable nommée est là pour combler.

FAQ

La responsable du changelog devrait-elle être un rôle d'ingénierie ou de produit ? Les deux peuvent fonctionner si la personne a à la fois la fluidité technique pour vérifier la portée et assez de distance avec l'implémentation pour écrire pour une lectrice externe ; le titre compte moins que si elle peut faire les deux moitiés, ou sait à qui demander pour la moitié qu'elle ne peut pas.

Un planning tournant de type astreinte est-il jamais approprié pour la propriété du changelog ? Pour le volume, parfois, si l'équipe est trop petite pour qu'une personne revoie tout ; pour la voix et le jugement, non, parce que c'est exactement ce que la rotation érode. Une rotation qui partage la charge de rédaction tout en gardant une revieweuse stable obtient le bénéfice sans la dérive.

Quel est le signe le plus rapide que quelque chose ne va pas avec la configuration actuelle de propriété ? Des entrées précises mais illisibles, ou lisibles mais fausses sur la portée, selon un schéma qui suit qui les a écrites. Si la qualité corrèle avec l'autrice au lieu de rester cohérente, c'est la propriété qui est l'écart, pas la compétence rédactionnelle.

L'automatisation réduit-elle à quel point la propriété compte ? Elle réduit combien d'écriture est nécessaire, pas combien de jugement est nécessaire. L'automatisation du changelog couvre ce qu'un pipeline peut générer en sécurité, formatage, publication, cross-posting ; la formulation, le regroupement et ce qui compte comme digne de mention restent des décisions humaines peu importe combien du pipeline est automatisé.

Que faire si l'autrice de la PR et la revieweuse ne sont pas d'accord sur la formulation ? C'est à la revieweuse de trancher, parce que la question à laquelle elle répond, une lectrice extérieure comprendrait-elle ceci, est celle que le rôle existe pour protéger. Ça ne rend pas l'avis de la développeuse sans valeur : si le désaccord porte sur la justesse plutôt que sur la formulation, la revieweuse s'efface, parce que la portée est la moitié qui revient à l'autrice de bien cadrer. Séparer les deux types de désaccord, formulation contre justesse, évite que la plupart d'entre eux ne tournent à l'impasse.

Release notes d'urgence : écrire sous vraie pression

Tue, 22 Sep 2026 00:00:00 GMT

La plupart des release notes sont écrites une fois le code terminé, révisées tranquillement, et publiées selon un calendrier qui n'a rien à voir avec l'urgence avec laquelle quelqu'un a besoin de les lire. Une version d'urgence, un patch de sécurité, un bug de perte de données, la correction d'une panne, inverse chacune de ces conditions à la fois : les notes doivent exister avant que la plupart des gens commenceraient normalement à les écrire, reçoivent presque aucune revue, et sont lues par des gens qui sont inquiets plutôt que détendus. Comment écrire des release notes couvre le processus normal ; ceci porte sur ce qui change quand il ne reste plus de temps pour le suivre.

Quelle est la seule chose qu'une release note d'urgence doit absolument réussir ?

Si la lectrice doit faire quelque chose, énoncé dans la première phrase, sans aucun cadrage avant. Une lectrice qui tombe sur une release note pilotée par un incident est souvent déjà inquiète, ayant entendu parler du problème via une page de statut, un fil de support, ou ses propres utilisatrices, et une note qui commence par du contexte avant l'action à entreprendre se lit comme une rétention d'information exactement dans les circonstances où retenir se lit le plus mal. « Aucune action nécessaire, ceci corrige une vulnérabilité qui ne nécessitait aucune donnée utilisateur pour être exploitée » et « Mettez à jour immédiatement : cette version corrige un bug qui pouvait montrer les données d'un compte à un autre » sont toutes deux une phrase, et toutes deux font tout le travail dont une lectrice paniquée a besoin avant de lire quoi que ce soit d'autre.

Le passage d'édition habituel s'applique-t-il encore quand il n'y a pas le temps d'en faire un ?

L'instinct de compresser survit même quand le processus à plusieurs brouillons qui le produit habituellement ne le fait pas. La réécriture décrit le fait de couper un premier brouillon verbeux jusqu'à sa phrase essentielle ; sous pression de temps il n'y a souvent pas de premier brouillon à couper, ce qui signifie que la discipline doit tourner dans votre tête pendant que vous écrivez plutôt que comme passage séparé après. La façon la plus rapide de l'approximer : écrivez la phrase que vous diriez à voix haute à quelqu'un qui demande « qu'est-ce que je dois savoir », puis arrêtez-vous, parce que cette phrase est généralement à la fois la plus rapide à produire et la seule qu'une lectrice dans cet état traitera vraiment.

Release note normale	Release note d'urgence
Écrite après revue de code, avant publication	Souvent écrite en même temps que le correctif, avant revue complète
Optimisée pour la lisibilité rapide parmi de nombreuses entrées	Optimisée pour qu'une entrée soit lue isolément, sous stress
Peut renvoyer le détail vers un changelog lié	Devrait mettre en avant le seul fait le plus important
Le cadrage et le contexte sont bienvenus	Le cadrage avant l'action à entreprendre se lit comme un délai

Est-il jamais acceptable de publier une note avant d'être totalement sûr de la cause du problème ?

Oui, si la note est honnête sur cette incertitude au lieu de laisser entendre une confiance que vous n'avez pas. « Nous avons déployé un correctif pour des taux d'erreur élevés au paiement ; nous confirmons encore la cause racine et mettrons à jour cette note » est défendable et gagne du temps correctement ; une note qui affirme une cause spécifique que vous n'avez pas réellement confirmée est le genre d'hypothèse qui devient ce qu'on vous cite plus tard si ça s'avère faux. La discipline qui compte ici n'est pas la vitesse de diagnostic, c'est de ne jamais laisser la confiance de la note dépasser la confiance réelle de l'équipe, parce qu'une affirmation technique fausse dans une note d'urgence fait plus de dégât à la confiance qu'un inconnu admis.

Trop confiant, non vérifié :
"Corrigé : une race condition dans le gestionnaire du
webhook de paiement causait des débits en double."

Honnête sous pression de temps :
"Corrigé : certaines clientes ont été débitées deux fois
pour une même commande. Nous avons arrêté les nouvelles
occurrences et remboursons les comptes concernés sous
24 heures. Enquête sur la cause racine en cours."

Une note d'urgence devrait-elle dire ce qui a causé le problème, ou juste que c'est corrigé ?

Dites ce qui est corrigé et ce que la lectrice devrait faire ; gardez la cause racine pour un suivi une fois qu'elle est vraiment connue, pas devinée. Une lectrice en plein incident veut exactement deux faits, est-ce résolu et est-ce que ça me concerne, et une explication de cause racine, même précise, entre en concurrence avec ces deux faits pour l'attention au pire moment possible pour la perdre. Le post-mortem, publié séparément une fois l'enquête terminée, est là où appartient la cause racine ; mélanger les deux documents sous pression de temps produit une note plus lente à écrire et plus lente à lire, l'inverse de ce dont une urgence a besoin.

Le problème de la mise à jour forcée des applications mobiles s'applique-t-il aussi ici ?

Le même principe, encore plus compressé. Release notes pour les applications mobiles couvre les mises à jour forcées, où la note doit énoncer la raison et l'échéance avant tout parce que la lectrice est déjà agacée de n'avoir aucun choix ; une release note d'urgence web est généralement opt-in pour la lectrice dans le sens où elle choisit si elle agit dessus, mais le même instinct « énoncer la contrainte en premier » s'applique, juste pour une raison différente : pas l'agacement, l'urgence.

Comment éviter qu'une note d'urgence se lise comme un aveu de faute quand elle ne devrait pas ?

Décrivez le correctif et son effet, pas la faute, et résistez à l'envie de trop vous excuser, ce qui se lit comme du remplissage pour une lectrice qui veut les deux faits ci-dessus. « Nous avons trouvé et corrigé un bug affectant certains exports » dit ce qui s'est passé sans lui assigner de drame ; « Nous sommes incroyablement désolés pour ce problème sérieux qui a affecté nos précieuses clientes » retarde l'information utile d'une phrase entière pour livrer un moment émotionnel que la lectrice n'a pas demandé. Une note courte et factuelle n'est pas froide, elle respecte l'état réel de la lectrice, qui sous vraie pression est l'impatience, pas un besoin de réconfort.

FAQ

Une release note d'urgence devrait-elle passer par le même processus de revue qu'une normale ? Un plus léger, pas aucun : une seule revieweuse rapide vérifiant que la note n'exagère pas la certitude vaut les quelques minutes que ça coûte, parce que le risque qu'une affirmation technique non revue soit fausse est plus élevé précisément parce qu'elle a été écrite vite.

Est-ce acceptable de publier une note d'urgence sans aucun lien vers plus de détails ? Seulement brièvement. Une note sans lien fonctionne comme la première chose publiée ; ajoutez-en un vers une page de statut ou un suivi dès que l'un des deux existe, parce qu'une lectrice qui veut plus que la seule phrase que vous lui avez donnée a besoin d'un endroit où aller, même si cet endroit dit « plus de détails bientôt ».

Une note d'urgence devrait-elle jamais être complètement sautée, laissant le correctif se livrer en silence ? Seulement pour des problèmes qu'aucune lectrice n'aurait pu remarquer ni avoir subis ; s'il y a la moindre chance qu'une lectrice ait vécu le problème, la note est ce qui lui dit que c'est terminé, et le silence se lit comme si le problème pouvait encore être actif.

Combien de temps une note d'urgence devrait-elle rester épinglée ou visible après résolution de l'incident ? Jusqu'à ce que la fenêtre d'anxiété immédiate se referme, typiquement un jour ou deux, puis elle peut se replier dans le changelog normal comme n'importe quelle autre entrée ; une note qui reste épinglée pendant des semaines commence à se lire comme une préoccupation non résolue plutôt que résolue.

Changements cassants Protobuf : ce qui survit sur le fil

Tue, 22 Sep 2026 00:00:00 GMT

Une API REST change quand une forme JSON change, et la majeure partie de cette forme est visible dans la réponse qu'on peut lire dans un navigateur. Une API gRPC change quand un fichier .proto change, et le format binaire sur le fil de Protocol Buffers a ses propres règles sur ce qu'un client peut tolérer, qui n'ont rien à voir avec ce que disent les noms de champs. Deux modifications qui paraissent également petites dans un diff, renuméroter un champ contre en ajouter un, tombent des côtés opposés d'une ligne que changements cassants trace en général : l'une est invisible pour chaque client existant, l'autre les casse tous d'un coup. Distinguer les changements cassants Protobuf des changements sûrs veut dire lire les règles propres du format sur le fil, pas deviner d'après l'apparence du changement dans un diff .proto.

Pourquoi la numérotation des champs compte-t-elle plus que le nom du champ dans Protobuf ?

Parce que le format sur le fil encode les champs par numéro, pas par nom. Le code généré dans chaque langage lit et écrit ces numéros ; le nom de champ email dans votre fichier .proto est une commodité pour les humains qui ne touche jamais les octets binaires envoyés sur le réseau. Renommer un champ, email en email_address, est sûr sur le fil binaire tant que le numéro reste le même, ce qui surprend les ingénieures habituées à REST, où une clé JSON renommée est exactement le type de changement qui casse un client. L'exception est ce même cas REST : les formats ProtoJSON et texte sérialisent le nom, donc un renommage casse le transcodage JSON (un grpc-gateway, par exemple), les fichiers au format texte et les field masks. Renuméroter ce même champ, en gardant le nom mais en changeant 1 en 7, est exactement l'inverse : invisible dans une revue de code qui ne montre que les noms, et ça corrompt chaque message qu'un client envoie ou reçoit à partir de ce moment-là.

Changement	Sûr sur le fil	Pourquoi
Renommer un champ, garder son numéro	Binaire oui, JSON et texte non	L'encodage binaire utilise le numéro ; ProtoJSON et le format texte utilisent le nom
Changer le numéro d'un champ	Non	Chaque message existant est maintenant lu comme le mauvais champ
Ajouter un nouveau champ avec un nouveau numéro	Oui	Les anciens clients ignorent les champs qu'ils ne reconnaissent pas
Supprimer un champ, réutiliser son ancien numéro pour autre chose	Non	Les anciennes données se décodent dans le mauvais nouveau champ
Changer le type d'un champ de façon incompatible (ex. `int32` en `string`)	Non	L'encodage sur le fil diffère selon le type

Qu'est-ce qui rend la suppression d'un champ différente de celle dans une réponse JSON REST ?

Le numéro devient radioactif. Les directives de Protobuf elles-mêmes recommandent de marquer le numéro d'un champ supprimé comme reserved plutôt que de le laisser être réutilisé, parce que la réutilisation est où le vrai dégât se produit : un client qui fait encore tourner du code généré du mois dernier envoie un message utilisant l'ancien numéro du champ pour l'ancienne signification, et le serveur, qui s'attend maintenant à ce que ce numéro signifie autre chose, mal-interprète les données en silence au lieu de les rejeter carrément. REST n'a pas de piège équivalent, parce qu'une clé JSON supprimée arrête simplement d'apparaître ; il n'y a aucun moyen pour la requête d'un ancien client d'être silencieusement réinterprétée comme autre chose. Un fichier .proto avec reserved 4, 9, 12; en haut d'un message est une cicatrice permanente, et c'est exactement le but : ça empêche le numéro d'être attribué à un nouveau champ par quelqu'un qui n'en connaissait pas l'histoire.

message Invoice {
  reserved 4; // était `legacy_customer_id`, supprimé le 2026-06-01
  reserved "legacy_customer_id"; // le nom aussi, pour JSON/texte
  string customer_id = 5;
  string status = 6;
}

Ajouter un champ nécessite-t-il jamais une entrée de changelog ?

Généralement pas une entrée de changement cassant, mais souvent une entrée normale, parce que « sûr sur le fil » et « invisible pour une lectrice à qui ça importe » sont deux affirmations différentes. Ajouter un champ à un message de réponse ne coûte rien structurellement, les anciens clients décodent le message et ignorent le nouveau champ automatiquement. Mais quelqu'un qui construit une nouvelle intégration contre ce service n'a aucun moyen de savoir que le champ existe à moins que quelqu'un le lui dise, parce que rien dans un build réussi ou un test qui passe ne rend visible un nouveau champ optionnel. Changelog d'API couvre en général ce qu'une entrée additive doit à quelqu'un qui la lit ; la raison spécifique à gRPC d'en écrire une quand même, c'est qu'il n'y a pas d'équivalent à parcourir une réponse REST dans un débogueur pour remarquer qu'une nouvelle clé est apparue.

En quoi est-ce différent de ce à quoi font face les appelants GraphQL ?

Les règles pour les ajouts sont les mêmes, mais l'exposition diffère. Dépréciation de schéma GraphQL couvre un modèle où un client ne reçoit que les champs qu'il demande explicitement, ce qui rend les changements additifs essentiellement sans risque et les suppressions le seul vrai danger. Les clients gRPC, à l'inverse, reçoivent tout ce que le serveur envoie et décodent tout contre leur propre copie compilée du schéma ; l'exposition d'un client n'est pas limitée par ce qu'il a demandé, seulement par ce que son code généré sait lire. Cette différence compte pour écrire des changelogs : une entrée GraphQL peut raisonnablement supposer que les clients sont protégés des champs qu'ils n'ont pas demandés, et une entrée gRPC ne peut pas du tout supposer ça.

Versionner un service gRPC fonctionne-t-il comme les `/v1/`, `/v2/` de REST ?

Le mécanisme est différent même quand l'intention est la même. Que sont v1 et v2 dans une API REST couvre le versionnage comme des chemins d'URL parallèles servant des contrats différents ; les services gRPC versionnent typiquement via le nom de package dans le fichier .proto lui-même, payments.v1.InvoiceService devenant payments.v2.InvoiceService, ce qui change le nom de service complètement qualifié qu'un client compose plutôt qu'un segment d'URL qu'il demande. Les deux approches résolvent le même problème, laisser un ancien contrat continuer de fonctionner pendant qu'un nouveau existe, mais une équipe venant d'un contexte REST cherche souvent un numéro de version au mauvais endroit et rate que la déclaration de package fait ce travail.

Que devrait vraiment nommer une entrée de changelog gRPC ?

Le message, le numéro de champ, et si c'est additif ou une suppression nécessitant une migration, dans cet ordre d'importance pour une lectrice décidant d'agir ou non. « Ajout de shipping_address (champ 8) à Order » dit à une intégratrice tout ce dont elle a besoin pour mettre à jour le code généré et commencer à l'utiliser. « Champ 4 réservé sur Invoice, legacy_customer_id a disparu » lui dit de vérifier si quelque chose dans son code lit encore ce champ, ce qu'une note style REST « champ supprimé de la réponse » ne communique pas avec la même urgence, parce que les suppressions REST retournent simplement moins de données alors que la réutilisation de champ Protobuf les corrompt activement.

FAQ

Le type d'un champ peut-il jamais être changé sans casser le format sur le fil ? Seulement dans des groupes compatibles spécifiques que Protobuf documente, comme élargir int32 en int64 dans certains cas. Traitez tout changement de type comme cassant à moins de l'avoir vérifié contre la table de compatibilité de Protobuf elle-même ; supposer une compatibilité par analogie avec le système de types d'un langage est comment ça tourne mal.

Déprécier un champ dans Protobuf fonctionne-t-il comme la directive @deprecated de GraphQL ? De façon similaire : Protobuf supporte une option de champ [deprecated = true] que l'outillage peut afficher. Aucune des deux n'est appliquée : un serveur GraphQL répond toujours à une requête sur un champ déprécié, et un client protobuf en encode toujours un. Les deux sont indicatives et nécessitent le même appui de changelog.

Renuméroter est-il jamais sûr si vous contrôlez chaque client ? Dans un système entièrement fermé, en principe, mais ça élimine toute la propriété de sécurité pour laquelle les numéros de champ existent, et « on contrôle chaque client » est une affirmation qui cesse d'être vraie dès qu'un build est mis en cache, qu'un déploiement est retardé, ou qu'un client est ajouté dont personne ne se souvenait. Réservez le numéro plutôt que de le réutiliser, même en interne.

Les services gRPC ont-ils besoin d'une page de changelog comme une API REST publique ? Seulement si des équipes externes les consomment sans lire directement les diffs .proto, le même test « qui est de l'autre côté » que les changelogs d'API interne applique en général. Un service gRPC consommé seulement par d'autres services de la même équipe peut souvent se passer d'un changelog formel en faveur de l'historique des commits, parce que quiconque le lit a déjà le schéma ouvert.

Formats de fichier changelog : JSON, YAML ou juste Markdown

Thu, 17 Sep 2026 00:00:00 GMT

La plupart des équipes commencent un changelog comme fichier Markdown parce que c'est le chemin de moindre résistance : lisible dans le diff d'une pull request, lisible sur GitHub sans rien rendre, et familier pour quiconque a déjà écrit un README. Ce choix fonctionne bien jusqu'à ce que quelque chose d'autre qu'une personne doive lire le fichier, une page, un widget, un digest email, et alors le format cesse d'être gratuit. Automatisation du changelog couvre l'exigence structurelle en général, un type, une date, un corps et un lien ; ceci porte sur quel format de fichier livre réellement cette structure et ce que chacun coûte pour y arriver.

Qu'est-ce qui ne va pas avec un changelog Markdown simple ?

Rien, jusqu'à ce que quelque chose doive le reparser en champs. Un titre, une date et une liste à puces en dessous est trivial à lire pour une personne et vraiment difficile à parser de façon fiable, parce que Markdown n'a pas de schéma : la date pourrait être dans le titre, en gras sur la première ligne, ou totalement absente sur une vieille entrée, et chacune de ces variantes est du Markdown valide qu'une personne lit correctement et qu'un parser non. Les équipes qui automatisent un changelog Markdown finissent généralement par écrire un parser maison basé sur des regex qui casse la première fois que le formatage d'une entrée dérive même légèrement, ce qui arrive souvent, parce que rien n'impose de cohérence à l'écriture.

Qu'est-ce qu'un format structuré apporte réellement ?

Une garantie que chaque entrée a la même forme, vérifiée quand l'entrée est écrite plutôt que devinée quand elle est lue. Un fichier JSON ou YAML avec un schéma défini, type, date, version, audience, corps, lien, échoue bruyamment si un champ requis manque, de la même façon qu'une réponse d'API stricte le ferait ; un fichier Markdown rend simplement ce qui est là, correct ou non. Cette différence est invisible jusqu'au jour où un script a besoin de la date de chaque entrée pour trier un flux, et où la moitié des entrées l'ont à un endroit différent.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Ça veut dire que le fichier lisible par l'humain doit disparaître ?

Non, et essayer de faire jouer à un fichier YAML ou JSON le double rôle de ce qu'une personne lit dans une pull request est généralement une erreur dans l'autre sens : revoir un diff de JSON imbriqué est pire que revoir une phrase de prose, et une relectrice qui doit parser mentalement une structure de données pour repérer une erreur de formulation est une relectrice qui finira par arrêter de repérer les erreurs de formulation. Les deux formats peuvent coexister : les données structurées sont la source de vérité que lit un pipeline d'automatisation, et un rendu Markdown ou HTML généré est ce qu'une personne relit et lit réellement, produit à partir du fichier structuré plutôt que maintenu à la main à côté.

Format	Lisible par l'humain tel quel	Parsable par machine sans code sur mesure	Mode d'échec courant
Markdown	Oui	Non	Forme d'entrée incohérente casse les parsers naïfs
JSON	Faible	Oui	Verbeux ; facile à éditer à la main vers du JSON invalide
YAML	Correct	Oui	Sensible aux espaces ; une mauvaise indentation est une erreur de parsing silencieuse, pas bruyante

Quel format structuré est en réalité plus facile à éditer à la main, JSON ou YAML ?

YAML, pour quiconque écrit des entrées à la main plutôt que via un générateur, parce qu'il élimine le quoting et l'appariement d'accolades que JSON exige pour chaque chaîne et objet imbriqué. Le compromis est que la sensibilité de YAML aux espaces échoue silencieusement d'une façon dont les désaccords d'accolades de JSON ne le font généralement pas : un parser JSON rejette d'emblée une entrée mal formée, tandis qu'un parser YAML peut accepter un fichier mal indenté et simplement le parser dans la mauvaise structure, ce qui est un échec pire parce que rien ne vous dit que c'est arrivé. Si les entrées ne sont jamais écrites que par un script, ce compromis disparaît largement et le parsing plus strict de JSON devient le choix par défaut le plus sûr.

Une page de changelog a-t-elle besoin de son propre format structuré, séparé du fichier qui l'alimente ?

Pas un séparé, le même rendu différemment. Une page de changelog couvre comment rendre la page elle-même lisible par machine via un flux JSON et un balisage schema.org ; ce flux est une sortie générée, pas une seconde source de vérité à garder synchronisée avec le fichier sous-jacent. Maintenir des données structurées à la main à deux endroits, un fichier source et le flux d'une page, est comment les deux finissent par diverger, donc la décision de format de fichier prise ici devrait être la seule chose dont tout ce qui suit, page, widget, email, est généré, jamais copié à la main.

Le coût de migration en vaut-il la peine pour convertir un changelog Markdown existant en format structuré ?

Généralement seulement une fois que l'automatisation est l'objectif réel, pas avant. Un projet d'une seule personne publiant un fichier Markdown dans un README GitHub n'a pas de vrai besoin d'automatisation, et le convertir en YAML n'achète rien d'autre que de la cérémonie. La conversion se rembourse d'elle-même au moment où plus d'un consommateur en aval, une page, un email de digest, un flux public, a besoin de lire les mêmes données, parce que c'est exactement le point où les incohérences d'un parser Markdown commencent à produire une sortie visiblement fausse au lieu d'être juste pénibles à maintenir.

FAQ

Un changelog Markdown peut-il être rendu parsable sans changer complètement de format ? Partiellement, avec du frontmatter : un petit bloc YAML en haut de chaque entrée (date, type, version) à côté d'un corps Markdown pour la prose. Ça obtient les champs structurés dont un parser a besoin sans forcer toute l'entrée en JSON ou YAML, et c'est un terrain d'entente raisonnable pour une équipe pas encore prête pour une migration complète.

Le format du fichier compte-t-il pour le SEO ou pour le classement d'une page de changelog ? Pas directement. Les moteurs de recherche lisent la page rendue, pas le fichier source, donc le format du fichier leur est invisible ; ce qui compte pour la page elle-même est si elle est lisible par machine de son propre droit, ce qui est une question séparée de ce qui la génère.

Chaque entrée de changelog devrait-elle passer par le même fichier, ou les types peuvent-ils être répartis sur plusieurs fichiers ? Un seul fichier est plus simple jusqu'à ce que le volume d'entrées le rende difficile à differ ou relire ; diviser par année ou par catégorie est une soupape de sécurité raisonnable une fois que les diffs d'un seul fichier deviennent trop gros pour être relus sensément, mais ça ajoute une étape de fusion avant que quoi que ce soit en aval puisse lire « toutes les entrées » comme une seule liste.

Existe-t-il un format de fichier changelog standard, comme il existe un standard pour RSS ? Pas un largement adopté. Keep a Changelog propose une convention Markdown, et plusieurs outils ont le leur ; un changeset est un fichier Markdown avec un frontmatter YAML qui nomme le package et le saut de version, ce qui est le modèle de frontmatter décrit plus haut. Aucun n'est un format que d'autres outils lisent d'emblée comme les lecteurs RSS comprennent RSS universellement.

Demandes dupliquées : fusionner sans perdre la voix

Thu, 17 Sep 2026 00:00:00 GMT

Trois clientes demandent la même capacité sur trois semaines différentes, formulée de trois façons différentes, et un processus de triage construit pour intercepter les doublons fait son travail : il les regroupe, les compte comme une seule demande avec trois votes, et le backlog reste propre. C'est la partie facile. Quelles étiquettes valent la peine couvre le regroupement par capacité sous-jacente avant de trier par formulation comme solution mécanique aux doublons ; ce qu'il ne couvre pas, c'est ce qui arrive aux mots eux-mêmes une fois que trois demandes deviennent une seule ligne, et cette perte est généralement plus grande que le problème de comptage des doublons qu'elle a résolu.

Que perd-on réellement quand des doublons sont fusionnés ?

La formulation spécifique utilisée par chaque demandeuse, qui est souvent plus informative que le décompte de votes dans lequel elle s'effondre. Une cliente pourrait demander « un moyen d'exporter des résultats filtrés », une autre « un export CSV qui respecte mes filtres enregistrés », et une troisième « un export qui n'inclut pas les colonnes masquées ». Les trois sont la même demande sous-jacente, correctement regroupée, mais chaque formulation porte une emphase légèrement différente sur ce qui compte pour cette personne, et une fusion qui ne garde que la formulation de la première soumission jette entièrement les deux autres. Le décompte survit ; la texture qui aiderait quelqu'un à construire la bonne version de la fonctionnalité, non.

Pourquoi la texture compte-t-elle si le décompte de votes dit déjà que la demande existe ?

Parce que demande et conception sont des questions différentes, et seule la formulation spécifique répond à la seconde. Dix votes sur « export » dit à une équipe que ça vaut le coup de construire la fonctionnalité ; ça ne dit rien sur si « export » signifie CSV, PDF, un email programmé ou un endpoint API, et une fusion qui écarte neuf des dix soumissions originales en faveur de la formulation de la première peut discrètement rétrécir la spec à ce que la première demandeuse a demandé par hasard, même si les neuf autres voulaient quelque chose de subtilement différent. Ce qu'une demande de fonctionnalité devrait réellement enregistrer couvre exactement ce manque du côté de la réception ; fusionner les doublons est là où ça réapparaît après la réception, précisément au point où une équipe a le plus besoin de l'éventail de ce qui a vraiment été demandé.

À quoi ressemble un processus de fusion qui garde la formulation au lieu de la jeter ?

Ajouter plutôt que remplacer. L'élément canonique garde un titre unique pour la vue du backlog, mais la formulation originale de chaque soumission fusionnée reste attachée à lui, soit comme liste de citations soit comme tickets sources liés, pour que quiconque revoit l'élément plus tard puisse voir l'éventail réel de ce que les gens ont demandé au lieu du résumé d'une personne de l'équipe. Ça ne coûte presque rien à construire, un champ sur le ticket plutôt qu'un nouveau système, et c'est la différence entre une fusion qui compresse l'information et une qui compresse juste son affichage.

Fonctionnalité : Export CSV filtré
Votes : 12
Demandes fusionnées :
  - "un moyen d'exporter des résultats filtrés" (acct_4421)
  - "un export CSV qui respecte mes filtres enregistrés" (acct_8832)
  - "un export qui n'inclut pas les colonnes masquées" (acct_1097)
  ...

Chaque doublon mérite-t-il d'être fusionné, ou y a-t-il de fausses correspondances ?

Certaines sont de fausses correspondances, et traiter « ça sonne similaire » comme « c'est la même demande » est son propre mode d'échec. « Laissez-moi exporter mes données » et « laissez-moi exporter juste la vue filtrée » peuvent être regroupées par une correspondance de mot-clé sur « exporter » alors qu'elles décrivent en réalité deux périmètres différents de la même capacité générale ; les fusionner gonfle soit le décompte de votes pour la mauvaise chose, soit, pire, livre la version plus étroite parce qu'elle est arrivée en premier par hasard. Un passage humain sur le regroupement, même rapide, attrape ça avant que ça ne s'accumule ; une correspondance de similarité automatique seule sur-fusionnera sur le vocabulaire et sous-fusionnera sur l'intention.

À quel moment la détection de doublons doit-elle tourner, à la réception ou plus tard ?

Les deux, pour des raisons différentes. Vérifier à la réception attrape le cas évident, une nouvelle demande qui reformule quelque chose déjà ouvert, avant qu'elle ne devienne sa propre ligne non suivie ; une recherche de similarité contre les demandes ouvertes au moment de la soumission traite la plupart de ces cas sans aucune intervention humaine. Un second passage plus tard, à un rythme plus lent, attrape le cas que la réception rate : deux demandes formulées avec un vocabulaire assez différent pour échapper à une correspondance de mot-clé ou d'embedding sur le moment, mais qui s'avèrent, une fois qu'une équipe a vu une dizaine de variations, décrire la même capacité sous-jacente. Sauter le second passage laisse des quasi-doublons éparpillés sous des titres séparés indéfiniment, chacun avec son petit décompte de votes qui ne s'additionne jamais au nombre qui aurait suffi à le faire construire.

La demandeuse devrait-elle savoir que sa soumission a été fusionnée dans un élément existant ?

Oui, et c'est la même discipline que boucler la boucle de feedback client appliquée une étape plus tôt que d'habitude : une demandeuse qui a soumis quelque chose et n'en entend jamais reparler conclut que sa demande n'a mené nulle part, même si elle a été correctement fusionnée dans un élément avec onze autres votes qui a fini par être livré. Un accusé de réception court, « nous avons combiné ceci avec une demande existante que d'autres ont faite aussi », coûte un message et évite qu'une cliente resoumette la même demande tous les quelques mois parce qu'elle n'a aucune visibilité sur si elle a jamais été réellement suivie.

La fusion change-t-elle qui est crédité quand la fonctionnalité est livrée ?

Elle devrait inclure tout le monde, pas seulement qui a soumis en premier. Boucler la boucle de feedback couvre le fait d'avertir les demandeuses quand leur demande est livrée ; pour un élément fusionné, ça veut dire chaque compte attaché à la fusion, pas seulement celui dont la formulation est devenue le titre canonique, parce que du point de vue de chaque demandeuse, elle a demandé ceci et ça a été livré, peu importe la formulation qu'un processus de triage a choisi de garder. Avec changeloop, cela veut dire que la pull request nomme chaque issue liée (Fixes #142, fixes #187) ; une issue qu'elle ne nomme pas ne reçoit aucun commentaire.

FAQ

Combien de formulation vaut la peine d'être gardée par demande fusionnée, une citation ou un lien complet vers le ticket ? Une courte citation suffit généralement pour le cas courant, puisque son but est de laisser une relectrice voir l'éventail de formulations d'un coup d'œil ; gardez aussi le lien complet vers le ticket quand l'original avait un contexte supplémentaire significatif, comme une capture d'écran ou une description détaillée de workflow qu'une citation d'une ligne aplatirait.

Garder la formulation de chaque doublon rend-il le backlog plus difficile à parcourir ? Pas si c'est replié par défaut. Le titre canonique est ce que voit une relectrice qui parcourt rapidement ; la formulation fusionnée est à un clic ou un dépliage de distance, présente pour qui fait une recherche plus approfondie mais sans encombrer la vue de qui compte juste les votes.

Que faire si deux demandes semblent identiques mais s'avèrent vouloir des choses différentes une fois construites ? Reséparez-les dès que ça devient clair, et traitez la fusion originale comme une décision raisonnable prise avec l'information disponible à l'époque, pas comme une erreur à éviter de répéter. Un système de regroupement qui ne défusionne jamais rien finira par avoir quelques mauvaises fusions gravées en permanence.

Y a-t-il un seuil de votes à partir duquel une demande fusionnée devrait recevoir une revue humaine de la formulation sous-jacente ? Pas un nombre fixe, mais toute demande approchant une décision de construction le mérite peu importe le décompte de votes, parce que c'est le point où la différence entre « export » et « export en CSV avec filtres enregistrés » cesse d'être une nuance et commence à être la spec.

Dépréciation GraphQL sans numéro de version

Thu, 17 Sep 2026 00:00:00 GMT

Une API REST peut publier /v2/ à côté de /v1/ et laisser chaque appelant migrer à son propre rythme. GraphQL a un schéma sur un endpoint, et chaque client, l'app mobile sur le build de l'année dernière et le dashboard interne déployé ce matin, interroge le même graphe. Il n'y a pas d'URL à forker. Déprécier un champ signifie le marquer comme déprécié sur place, dans un schéma dont tout le monde dépend déjà, ce qui rend la discipline différente de REST même si le problème sous-jacent, dire aux appelants que quelque chose va disparaître, est le même que couvre dépréciation d'API en général.

Comment GraphQL marque-t-il un champ comme déprécié, s'il n'y a pas de version à incrémenter ?

Avec la directive @deprecated, appliquée directement au champ :

type Product {
  price: Float @deprecated(reason: "Use priceV2 for multi-currency support.")
  priceV2: Money
}

Le champ reste interrogeable. Il ne disparaît pas, ne renvoie pas de 404, ne change pas de comportement ; il porte juste une note lisible par machine que la plupart des outils GraphQL, GraphiQL, Apollo Studio, les linters de schéma, montreront à quiconque parcourt le schéma ou écrit une requête contre lui. C'est tout le mécanisme. Il n'y a pas d'endpoint de dépréciation séparé, pas d'en-tête, pas de document compagnon exigé par la spec, ce qui est à la fois l'attrait et le piège : la directive est facile à ajouter et facile à ignorer, parce que rien ne force un client à la regarder.

Est-ce que quelqu'un voit vraiment la raison de la dépréciation ?

Seulement ceux qui utilisent le schéma directement, par introspection ou un éditeur conscient du schéma, et c'est un public plus petit que les lecteurs habituels d'un changelog d'API. Une app mobile construite contre une requête il y a six mois a déjà cuit cette requête dans son binaire ; elle continuera à demander price et continuera à recevoir une réponse, déprécié ou non, jusqu'à ce que quelqu'un reconstruise l'app avec le nouveau champ et publie une mise à jour. La directive dit à une développeuse qui écrit du nouveau code de ne pas utiliser l'ancien champ. Elle ne fait rien pour le client déjà déployé et en fonctionnement.

Mécanisme	Qui il atteint
Directive `@deprecated`	Développeuses parcourant le schéma ou écrivant de nouvelles requêtes
Échecs CI du linter de schéma	L'équipe propriétaire du code client, si elle en fait tourner un
Une entrée de changelog	Quiconque la lit, y compris une équipe cliente sans linter
Rien (le champ fonctionne juste)	Un client déjà construit utilisant l'ancien champ

Un champ déprécié devrait-il quand même avoir une entrée de changelog ?

Oui, et elle fait plus de travail que la directive seule, parce qu'un changelog atteint des gens que la directive ne peut pas : une équipe partenaire qui consomme le graphe sans parcourir son schéma, un client construit contre une copie en cache du schéma vieille de plusieurs mois, quiconque ne le remarquerait qu'en lisant de la prose. Changelog d'API couvre en général ce qu'une entrée doit à un appelant ; une entrée GraphQL doit une chose que REST n'a rarement besoin d'expliciter, parce que les appelants REST la déduisent du numéro de version : si l'ancien champ fonctionne encore aujourd'hui, fonctionne encore avec un avertissement, ou a effectivement cessé de renvoyer des données. La directive seule ne répond à rien de tout ça pour une lectrice qui n'a jamais ouvert le schéma.

Quand est-il vraiment sûr de retirer un champ du schéma ?

Seulement une fois que les logs de requêtes montrent que personne ne le demande plus, ce qui est une question d'usage, pas de calendrier. Un champ peut porter @deprecated pendant un an et rester structurant pour un client jamais reconstruit ; le retirer selon un calendrier fixe, comme le fait souvent un Sunset REST, casse ce client sans aucun avertissement sur lequel il puisse agir, parce que GraphQL ne lui donne rien sur quoi agir au-delà de la directive qu'il n'a jamais lue. Journalisez l'usage au niveau du champ avant de vous engager sur une date de retrait, et traitez tout compte de requêtes non nul comme une pause, pas un compte à rebours.

Ajouter un champ porte-t-il le même risque que dans une API REST ?

Moins, pour un nouveau champ, parce qu'un client GraphQL ne reçoit que les champs qu'il demande explicitement. Ajouter priceV2 à côté de price ne peut pas casser une requête existante de la façon dont ajouter un champ à une réponse JSON REST peut casser un désérialiseur strict, parce que rien ne force le client à demander le nouveau champ. Ajouter une valeur à une énumération existante est l'exception qui vaut la peine d'être nommée dans le même souffle : un client qui teste exhaustivement chaque valeur d'énumération, ce que les langages fortement typés encouragent, casse dès qu'une nouvelle valeur arrive, que ce soit demandé par une requête ou non. La sécurité ne vaut que pour les champs et les membres d'union auxquels un client choisit d'adhérer ; elle ne vaut pas pour un ensemble fermé qu'un client énumère à la main dans son code.

Qu'est-ce qu'une entrée de changelog GraphQL a besoin que n'a pas une entrée REST ?

La forme de la requête, pas seulement le nom du champ, parce que « le champ price est déprécié » manque de la pièce dont un appelant a réellement besoin : quels types et quelles requêtes le touchent. Une entrée utile nomme le type, le champ, le champ de remplacement et, si vous pouvez le générer, les requêtes réelles en production qui demandent encore l'ancienne forme. Cette dernière pièce, relier l'avis de dépréciation à l'usage réel, est ce que les appelants REST obtiennent gratuitement des logs serveur sur une URL et que les appelants GraphQL n'obtiennent pas, parce que chaque requête frappe le même endpoint quoi qu'elle demande.

Autre chose qu'un champ peut-il porter la directive `@deprecated` ?

Les valeurs d'énumération, en utilisant la même directive directement sur la définition de la valeur plutôt que sur celle du champ :

enum ShippingMethod {
  STANDARD
  EXPRESS
  OVERNIGHT @deprecated(reason: "Use EXPRESS with priority: true instead.")
}

La spec définit @deprecated pour exactement deux emplacements, une définition de champ ou une valeur d'énumération, et rien d'autre à ce jour dans la version stable ; la dépréciation au niveau des arguments et des champs d'entrée n'existe que dans un langage de brouillon plus récent, pas dans ce que la plupart des serveurs implémentent aujourd'hui. Une valeur d'énumération marquée ainsi reste une valeur légale qu'un serveur peut encore renvoyer ou accepter, la même promesse de non-rupture que fait un champ déprécié, ce qui la rend sûre à livrer avant de vraiment retirer la valeur.

FAQ

GraphQL supporte-t-il quelque chose comme un en-tête Sunset pour tout un endpoint ? Non, parce qu'il n'y a généralement qu'un seul endpoint. Le calendrier de dépréciation vit au niveau du champ, dans le texte de raison de la directive @deprecated et dans quel que soit le changelog ou guide de migration qu'une équipe publie à côté, pas dans un en-tête de réponse qu'un client peut lire de façon programmatique.

Un champ déprécié peut-il être retiré puis réajouté plus tard avec un type différent ? Seulement sous un nouveau nom de champ. Réintroduire le même nom de champ avec un type changé est exactement le changement cassant que le cycle de dépréciation existe pour éviter ; donnez au remplaçant son propre nom, comme le fait priceV2, et laissez l'ancien s'éteindre complètement avant que le nom soit libre pour réutilisation.

Le texte de raison @deprecated devrait-il pointer vers l'entrée de changelog ? Oui, quand l'outillage de schéma le supporte. Le champ raison accepte une simple chaîne de caractères, et une URL à l'intérieur de cette chaîne est le chemin le plus court entre une développeuse fixant une sortie d'introspection et l'explication plus complète qu'une entrée de changelog peut donner.

Un changement de schéma GraphQL est-il jamais rétrocompatible d'une façon dont REST ne l'est pas ? Les changements additifs de champ, oui, pour la raison ci-dessus : les clients n'obtiennent que ce qu'ils demandent. Les nouvelles valeurs d'énumération sont l'exception, parce qu'un client qui énumère un ensemble fermé peut casser sur une valeur qu'il n'attendait pas. Les retraits et les changements de type sont exactement aussi cassants que leurs équivalents REST.

Comment écrire un guide de migration d'API

Mon, 07 Sep 2026 00:00:00 GMT

Un guide de migration d'API est le document qui transforme un changement incompatible en checklist plutôt qu'en panne : ce qui a changé, quoi faire, et avant quand. Une entrée de changelog peut nommer un changement incompatible en deux phrases ; un guide de migration est ce qu'une appelante ouvre vraiment quand ces deux phrases disent « ça te casse » et qu'elle a besoin de savoir exactement quoi modifier. Publier l'entrée sans le guide, c'est comment une appelante apprend un changement incompatible par un ticket de support plutôt que par le document écrit pour l'éviter.

Qu'est-ce qu'un guide de migration d'API ?

Un document étape par étape qui fait passer une appelante de l'ancienne forme d'une API à la nouvelle, écrit pour quelqu'un qui a du code à changer, pas pour quelqu'un qui décide encore d'adopter l'API. Cette distinction compte : un guide de migration suppose une intégration existante et du trafic de production existant, donc il doit couvrir le rollback, la migration partielle, et comment savoir si la migration a réussi, rien de tout cela n'étant nécessaire à un guide de première intégration.

Document	Suppose	Répond à
Guide de migration	Une intégration existante	Comment passer de l'ancienne forme à la nouvelle ?
Entrée de changelog	Rien, juste que la lectrice vérifie	Qu'est-ce qui a changé, et quand ?
Référence API	Rien, ou une première intégration	Que fait cet endpoint ?
Avis de dépréciation	Une intégration utilisant l'ancien	Quand ça arrête de fonctionner ?

Un guide de migration se situe généralement entre les deux derniers : un avis de dépréciation lance un compte à rebours, et le guide de migration est ce qu'une appelante suit avant que ce compte n'expire.

Quand un changement a-t-il besoin d'un guide de migration, pas seulement d'une entrée de changelog ?

Quand il y a plus d'une étape entre l'ancien comportement et le nouveau, ou quand le changement touche assez de points d'appel pour qu'une appelante bénéficie d'un exemple travaillé plutôt que d'une description. Qu'est-ce qu'un changement incompatible, et comment le livrer couvre le test pour savoir si un changement est incompatible ; une fois la réponse oui, la seconde question est de savoir si la correction est une modification d'une ligne ou une vraie migration. Un champ renommé, une appelante peut le gérer avec la seule entrée de changelog. Un changement à l'authentification, à la pagination ou à la gestion des erreurs mérite presque toujours un guide, parce que le code de remplacement correct n'est pas évident à partir d'une description d'une phrase.

Que doit contenir un guide de migration ?

Cinq choses, et en sauter une seule est ce qui transforme un guide en une page qu'une appelante lit une fois puis abandonne pour procéder par essais-erreurs. L'ancien code, montré tel qu'il apparaîtrait vraiment dans un projet. Le nouveau code, montré de la même façon, pas comme une description abstraite de la différence. Ce qui casse si rien ne change, dit clairement, parce que « rien » est une réponse valide et courante qu'une appelante a quand même besoin d'entendre explicitement. Un moyen de vérifier que la migration a fonctionné, comme un champ de réponse ou un code de statut à vérifier. Et un calendrier : quand l'ancien comportement arrête de fonctionner, et si les deux formes sont disponibles entre-temps.

## Migration des champs monétaires de float vers entier (v3.0.0)

Avant :
  { "amount": 19.99 }

Après :
  { "amount": 1999 }  // plus petite unité monétaire (centimes)

Ce qui change : `amount` est maintenant un entier dans la plus petite
unité de la devise du compte. Le code qui lit `amount` comme un float
lira une valeur 100 fois trop grande à partir du 1er octobre 2026.

Vérifier : après migration, un débit de 19,99 € devrait se lire
`amount: 1999`, pas `amount: 19.99`.

Calendrier : v2 continue de renvoyer des floats jusqu'au 15 janvier
2027. v3 renvoie des entiers dès le lancement. Les deux versions sont
actives maintenant.

Chacune de ces cinq choses répond à une question qu'une appelante devrait sinon deviner ou poser au support, et c'est exactement le coût qu'un guide de migration économise.

Qui devrait l'écrire, et quand ?

Qui a conçu le changement, au moment même où il est livré, pas une équipe support qui le reconstitue plus tard à partir de tickets. Qui a pris la décision sait sur quelles parties de l'ancien comportement personne n'aurait dû compter et lesquelles étaient un contrat accidentel ; un guide écrit plus tard par quelqu'un sans ce contexte a tendance soit à trop expliquer l'évident, soit à manquer le seul cas limite qui casse vraiment les gens. Le guide et l'entrée de changelog qui annonce le changement incompatible devraient sortir ensemble, l'entrée renvoyant vers le guide plutôt que de le répéter.

Comment cela se rattache-t-il au versionnage et au changelog d'API ?

Directement : un guide de migration est la version détaillée de ce qu'une entrée MAJOR dans semantic versioning et votre changelog ne résume qu'en une phrase. L'entrée de changelog dit qu'un changement est incompatible et grosso modo ce qui a changé ; le guide de migration est le lien que cette entrée devrait porter. Changelog d'API : quoi publier et qui le lit liste le guide de migration comme l'un des cinq documents qu'une API maintient, chacun répondant à une question différente ; celui-ci répond à « comment je passe vraiment de A à B », et il mérite sa propre page précisément parce que cette réponse est généralement trop longue pour une entrée de changelog.

Combien de temps un guide de migration devrait-il rester publié ?

Au moins aussi longtemps que l'ancien comportement reste accessible, et idéalement après aussi. Une appelante qui migre dix-huit mois trop tard, après avoir ignoré trois avis de dépréciation, a quand même besoin du guide, et le supprimer le jour où l'ancien comportement est coupé garantit seulement que l'appelante qui en a le plus besoin ne le trouve pas. Gardez-le à une URL stable et mettez à jour la section calendrier plutôt que de retirer la page. Le guide de mise à niveau de Stripe est un exemple public de ce schéma : une seule page, tenue à jour release après release, plutôt qu'un nouveau document par version qui devient obsolète dès que la suivante sort. Votre propre guide mérite un endroit tout aussi facile à trouver, à côté de la documentation qu'une appelante lit déjà, plutôt qu'enterré dans des archives de blog.

FAQ

Chaque changement incompatible a-t-il besoin d'un guide de migration ? Non. Un changement qu'une appelante peut corriger avec la seule entrée de changelog, comme un champ renommé avec un remplacement évident, n'a pas besoin d'un guide séparé. Un changement qui touche plusieurs points d'appel ou nécessite un exemple travaillé, oui.

Un guide de migration devrait-il vivre avec la documentation de l'API ou dans le changelog ? Avec la documentation, lié depuis l'entrée de changelog. L'entrée est ce qu'une abonnée voit en premier ; le guide est ce dont elle a besoin une fois qu'elle a décidé d'agir, et il appartient juste à côté du matériel de référence qu'une appelante utilise déjà.

Quelle est la différence entre un guide de migration et un avis de dépréciation ? Un avis de dépréciation indique que quelque chose va disparaître et avant quand. Un guide de migration, ce sont les instructions pour agir en conséquence. Un avis de dépréciation sans guide de migration lié donne à une appelante une échéance sans lui dire comment la respecter.

Faut-il documenter à la fois l'ancien et le nouveau comportement pendant une fenêtre de migration ? Oui, sur la même page si possible, pour qu'une appelante voie exactement ce qui a changé plutôt que de le reconstituer à partir de deux documents séparés écrits à des moments différents.

Un check de changelog pour GitHub Actions

Mon, 07 Sep 2026 00:00:00 GMT

Chaque équipe qui tient un changelog à la main a eu la même conversation après le même incident : une release est sortie sans entrée, quelqu'un demande pourquoi, et la réponse honnête est que la personne qui l'aurait écrite allait vite et l'étape du changelog ne vivait que dans la mémoire. L'automatisation du changelog couvre ce qu'un pipeline peut automatiser en sécurité et ce qui a encore besoin d'une personne ; un check de changelog en CI est l'autre moitié de ce problème, parce qu'automatiser l'écriture n'aide pas si personne n'est obligé de la déclencher en premier lieu. GitHub Actions est là où la plupart des équipes font déjà tourner leurs checks de pull request, donc c'est là que celui-ci vit aussi.

Pourquoi « on demande aux gens d'ajouter une entrée » échoue-t-il selon un schéma prévisible ?

Parce que ça rivalise pour l'attention avec tout le reste dans une pull request, et c'est la seule partie sans conséquence immédiate à la sauter. Les tests échouent bruyamment et bloquent le merge. Une entrée de changelog manquante ne bloque rien, donc elle perd dès que quelqu'un est pressé, ce qui en pratique est la plupart du temps. Une politique imposée par la mémoire se dégrade exactement au rythme attendu : bien pendant les premières semaines après l'accord de tous, puis silencieusement abandonnée dès que la personne qui s'en souciait part en vacances ou change d'équipe.

Que vérifie vraiment un check CI pour une entrée de changelog ?

Pas la qualité de la rédaction, seulement qu'une entrée existe et qu'elle est bien formée, ce qui est le bon périmètre pour un check de changelog qui tourne en CI plutôt que dans la tête de quelqu'un. Une forme courante : le check regarde le diff de la PR et exige soit un nouveau fichier dans un répertoire de changesets (le modèle qu'utilisent Changesets et des outils similaires) soit une ligne modifiée dans un fichier de changelog, et fait échouer le build si aucun des deux n'existe. La revue de ce que dit vraiment l'entrée continue de se passer là où elle s'est toujours passée, en code review, parce que ce jugement n'a pas sa place dans un script.

Ce que vérifie le check CI	Ce qu'il ne vérifie pas
Un changeset ou une ligne de changelog existe dans le diff	Si la formulation est claire
L'entrée référence le bon package, dans un monorepo	Si le changement mérite vraiment une entrée
Le fichier est syntaxiquement valide (front matter, forme JSON)	Si l'entrée est honnête sur l'impact

Chaque PR en a-t-elle besoin, ou certains changements sont-ils exemptés ?

Certains sont exemptés, et la liste des exemptions est là où ces systèmes se construisent ou s'abandonnent vraiment. Une montée de dépendance sans effet visible, un changement uniquement de tests, un refactor interne sans changement de comportement : aucun de ceux-là ne devrait forcer une contributrice à inventer une entrée de changelog pour quelque chose dont personne lisant le changelog ne se soucie. Le modèle qui fonctionne est une étiquette ou un flag qu'une contributrice peut appliquer (no-changelog-needed) et qui satisfait le check CI sans fichier, revu par qui approuve la PR, pour que l'exemption elle-même passe le même contrôle qu'une entrée.

Que se passe-t-il pour les exceptions légitimes, comme un hotfix urgent ?

Le gate appartient au merge, pas au déploiement : un hotfix sous vraie pression de temps peut merger avec une entrée provisoire ou un ticket de suivi, pourvu que le check CI soit satisfait par l'intention plutôt que seulement par un paragraphe fini ; certaines équipes acceptent un stub d'une ligne qu'une mainteneuse peaufine avant la prochaine coupe de release. Ce que le gate ne devrait jamais permettre, c'est de sauter l'étape en silence, parce qu'un stub qu'on oublie est un échec plus petit qu'une entrée qui n'a jamais existé, et un stub laisse au moins une trace que quelqu'un peut retrouver plus tard.

# .github/workflows/changelog-check.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  changelog:
    if: >-
      !contains(github.event.pull_request.labels.*.name,
      'no-changelog-needed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # le diff a besoin de la branche de base
      - name: Require changelog entry
        run: |
          base="origin/${{ github.base_ref }}"
          if ! git diff --name-only "$base"...HEAD \
              | grep -q '^\.changeset/'; then
            echo "No changeset. Add one, or have a maintainer"
            echo "apply the no-changelog-needed label."
            exit 1
          fi

Comment savoir que le check lui-même est correct avant qu'il ne bloque de vraies PR ?

Ouvrez d'abord une pull request de test contre une branche jetable : une avec un changeset, une sans, et une portant l'étiquette d'exemption, et confirmez que les trois obtiennent le résultat attendu avant que le check ne s'applique au travail de quelqu'un d'autre. Un check de changelog qui échoue ouvert, laissant passer chaque PR parce qu'une condition a été écrite à l'envers, est pire que l'absence de check, parce que ça ressemble à une couverture qui n'existe pas. workflow_dispatch sur le même fichier, exécuté manuellement contre quelques PR récemment mergées, attrape la plupart de ces erreurs sans avoir besoin d'une vraie pull request.

La même idée fonctionne-t-elle en dehors de GitHub Actions ?

La forme se transpose, seule la syntaxe change. GitLab CI exprime la même règle comme un bloc rules de job qui vérifie $CI_MERGE_REQUEST_LABELS au lieu d'un if GitHub Actions, et une approbation de merge request obligatoire peut remplacer l'étape de revue d'exemption. Le check que cet article décrit est GitHub Actions parce que c'est la plateforme sur laquelle la plupart des lectrices sont déjà, mais l'exigence sous-jacente, un gate vérifié par une machine plutôt qu'une convention qu'on se contente de demander, est la même partout où une CI tourne avant un merge.

Est-ce que ça fonctionne pareil dans un monorepo ?

Il faut une pièce de plus : pour quel package est l'entrée. Les changelogs de monorepo couvre pourquoi un seul fichier pour tout le repo cesse de fonctionner dès que les packages sont livrés indépendamment ; le check CI hérite de la même exigence ; un changeset qui ne nomme pas de package n'est pas une preuve utile que le bon changelog sera mis à jour, seulement qu'un fichier a changé quelque part dans le diff. Les outils construits pour ça (Changesets est celui courant dans l'écosystème JavaScript) demandent à la contributrice de choisir le package concerné et un bump de semver au moment même où le changeset est créé, donc le check CI obtient les deux pièces gratuitement au lieu de les inférer plus tard.

FAQ

Le check CI devrait-il bloquer le merge, ou juste avertir ? Bloquer. Un avertissement est fonctionnellement identique à demander gentiment, ce qui a déjà échoué. L'étiquette d'exemption existe précisément pour qu'un cas d'avertissement authentique ait quand même un chemin légitime à travers le même gate strict.

Qui vérifie qu'une étiquette d'exemption a été appliquée correctement ? Qui que ce soit qui approuve la pull request, dans le cadre de la revue qu'elle fait déjà de toute façon. L'étiquette ne devrait jamais être auto-appliquée sans revue, sinon elle devient le même contournement silencieux que le gate était censé fermer.

Exiger ça en CI remplace-t-il le besoin d'un pipeline d'automatisation de changelog ? Non, ça l'alimente. L'automatisation du changelog couvre comment transformer des entrées structurées en une page, un flux et un email ; le check CI est ce qui garantit que ces entrées structurées existent pour être automatisées en premier lieu.

Quelle est la plus petite version de ça qui vaut la peine d'être construite en premier ? Un seul check qui échoue si aucun fichier n'a changé sous un répertoire de changelog désigné, avec une étiquette d'exemption. Le routage par package et l'inférence de semver pour un monorepo peuvent venir plus tard ; l'habitude centrale, une entrée existe ou quelqu'un a explicitement dit qu'elle n'était pas nécessaire, vaut la peine d'être là dès le premier jour.

Refuser une demande de fonctionnalité sans perdre la cliente

Mon, 07 Sep 2026 00:00:00 GMT

Boucler la boucle veut souvent dire dire à quelqu'un que sa demande a été livrée. La moitié difficile, celle pour laquelle la plupart des systèmes de suivi n'ont aucun processus, c'est dire non. La plupart des demandes de fonctionnalités ne sont jamais livrées, ce qui signifie que la majeure partie du bouclage de boucle qu'un produit doit vraiment à ses utilisatrices est un refus, pas une annonce, et un refus mal géré coûte plus de bonne volonté que le silence n'en aurait coûté. Bien géré, il peut ne coûter presque rien, parce que ce que la demandeuse veut vraiment le plus souvent, ce n'est pas la fonctionnalité, c'est de savoir qu'elle a été entendue.

Pourquoi bien refuser compte-t-il autant que bien livrer ?

Parce que le silence se lit comme un refus sans explication, et un non expliqué se lit comme de l'attention. Celle qui n'entend rien suppose que la demande a été ignorée ou perdue, et les deux conclusions lui apprennent à arrêter de se donner la peine de demander, ce qui est le même résultat qu'obtient un produit avec un vrai refus, juste atteint plus lentement et avec plus de ressentiment en chemin. Une réponse qui dit non, clairement et avec une raison, boucle la boucle aussi complètement qu'une fonctionnalité livrée, et le fait plus vite.

Réponse	Ce que la demandeuse apprend	Coût pour la relation
Silence	Personne n'a lu, ou personne ne s'en soucie	Élevé, et s'accumule à chaque demande future
Réponse automatique sans raison	C'est en file d'attente quelque part, indéfiniment	Moyen ; gagne du temps mais pas de confiance
Refus avec raison	C'était lu, considéré et répondu	Faible, si la raison est honnête
Refus avec alternative	Le vrai besoin a été vraiment entendu	Le plus faible ; construit souvent de la confiance

Qu'est-ce qui fait mal atterrir un refus ?

Presque toujours trois choses, combinées. La généricité : un « merci pour votre retour » tout fait qui ne fait pas référence à ce qui a vraiment été demandé se lit comme n'ayant pas été lu du tout, même si ça l'était. Le délai : un refus qui arrive six mois après la demande, une fois que la demandeuse a oublié avoir demandé, se sent pire qu'un non rapide, parce qu'il implique que la demande est restée sans y toucher plutôt que d'avoir été considérée et refusée. Et une raison qui ne tient pas : « pas sur notre roadmap » ne répond à rien, tandis que « cela nécessiterait de repenser comment fonctionnent les permissions, ce que nous ne prévoyons pas de toucher cette année » donne à la demandeuse quelque chose qu'elle peut vraiment évaluer et, si ça compte assez, escalader ou contourner.

Que devrait vraiment dire un bon refus ?

Quatre choses, dans cet ordre : une reconnaissance qui nomme la demande spécifique, pas une paraphrase générique ; la vraie raison, énoncée honnêtement même quand la raison honnête est « ça ne correspond pas à la direction que prend le produit » plutôt qu'une excuse plus douce ; si la porte est fermée ou juste pas ouverte maintenant, parce que ça nécessite des tons très différents ; et, quand il en existe une, une alternative qui répond au besoin sous-jacent même si ce n'est pas la fonctionnalité demandée à la lettre.

Bonjour Jamie,

Merci pour la demande d'ajouter l'import CSV en masse pour les
invitations d'équipe. On a regardé, et on ne va pas la construire :
notre flux d'invitation repose sur la revue individuelle de chaque
nouveau membre pour des raisons de sécurité, et l'import en masse
irait à l'encontre de ça par conception, pas par oubli.

Si le vrai problème est d'inviter rapidement une grande équipe, l'API
prend en charge les invitations individuelles scriptées, ce qui vous
donne presque toute la rapidité sans contourner la revue : [lien].
Content de vous aider à mettre ça en place si vous voulez.

Remarquez ce que ça fait qu'un modèle ne peut pas : ça nomme la vraie fonctionnalité, donne une raison liée à une vraie décision de conception plutôt qu'à une politique vague, et propose un chemin qui résout le problème sous-jacent plutôt que de simplement fermer le ticket.

En quoi est-ce différent de boucler la boucle sur une fonctionnalité livrée ?

La mécanique est similaire, le ton non. Boucler la boucle de feedback avec le client couvre le cas livré, où le message est une bonne nouvelle et le risque principal est d'oublier de l'envoyer. Un refus est une mauvaise nouvelle, ou du moins une nouvelle non désirée, et il nécessite plus de soin dans la raison donnée et moins d'automatisation dans la livraison : une notification de fonctionnalité livrée peut être un commentaire tout fait déclenché par un changement de statut, mais un refus qui se lit comme tout fait est exactement l'échec que toute cette approche cherche à éviter. Les deux partagent une exigence, cependant : la demande originale doit rester liée à la demandeuse, la même discipline de suivi que couvre le suivi des demandes de fonctionnalités, sinon il n'y a aucun moyen d'envoyer l'un ou l'autre message individuellement.

Un refus devrait-il être public, comme un statut sur une roadmap publique ?

Généralement pas la raison spécifique, même si le statut l'est. Roadmap publique couvre les étiquettes de statut qu'une demandeuse peut consulter sans redemander, et un statut « refusé » ou « non prévu » peut faire partie de ce système. Mais la raison détaillée, surtout quand elle touche à des priorités internes ou à un contexte peu flatteur, vaut généralement mieux dans la réponse individuelle que sur une page de statut publique, où la même formulation doit fonctionner pour chaque lectrice au lieu de la seule personne qui a vraiment demandé.

Chaque demande refusée mérite-t-elle une réponse individuelle ?

Chaque demande d'une personne nommée et joignable, oui, au moins une courte. Les demandes à fort volume, dupliquées ou anonymes sont l'exception : regrouper des demandes similaires et répondre une fois par groupe, ou mettre à jour une étiquette de statut partagée, est raisonnable quand les réponses individuelles ne passent vraiment pas à l'échelle. La ligne à tenir, c'est que « on ne peut pas répondre à tout le monde individuellement » devrait être une vraie contrainte opérationnelle, vérifiée contre le volume réel, pas une excuse par défaut pour sauter une réponse qui aurait pris deux minutes.

FAQ

Vaut-il mieux refuser rapidement avec une raison faible, ou prendre le temps pour une bonne ? Rapidement, avec une raison honnête, bat les deux pris séparément. Une réponse rapide avec une vraie raison, même courte, surpasse une réponse lente avec une raison polie ; le délai lui-même fait partie de ce qui abîme la confiance.

Un refus devrait-il jamais promettre de reconsidérer la demande plus tard ? Seulement si c'est vraiment probable et qu'il y a un mécanisme pour vraiment la reconsidérer, comme une étiquette qui la refait remonter à un cycle de planification. Un vague « on va y penser » sans un tel mécanisme équivaut fonctionnellement au silence, juste formulé plus gentiment.

Et si la raison honnête est quelque chose que l'entreprise ne peut pas partager, comme une préoccupation concurrentielle ? Dites-le directement plutôt que d'inventer une raison plus douce. « On ne peut pas partager le raisonnement précis ici, mais ce n'est pas quelque chose qu'on prévoit de construire » est plus honnête, et plus respecté, qu'une explication inventée qui s'effondre à la première relance.

Refuser une demande signifie-t-il qu'elle devrait être supprimée du suivi ? Non. Gardez-la, étiquetée comme refusée avec la raison, pour qu'elle fasse partie du motif contre lequel la prochaine demande similaire sera regroupée, et pour qu'un contexte modifié plus tard (une nouvelle intégration, une nouvelle priorité d'équipe) puisse la faire ressurgir plutôt que de repartir de zéro dans l'évaluation.

Release notes de feature flag : quoi dire, et quand

Mon, 07 Sep 2026 00:00:00 GMT

Fermer la boucle sur une demande de fonctionnalité suppose un moment net où la chose a été livrée. Un feature flag supprime ce moment, et c'est ce qui rend les release notes de feature flag si délicates à caler dans le temps. Le code est fusionné, le flag existe, et pendant des jours ou des semaines la fonctionnalité est à la fois en production et invisible pour presque tout le monde qui pourrait vouloir l'utiliser, y compris, souvent, la personne qui l'a demandée à l'origine. Prévenir trop tôt la fait tomber sur une fonctionnalité qui n'est pas encore là. Prévenir trop tard fait que la boucle censée construire la confiance se lit, au contraire, comme oubliée.

Pourquoi un flag casse-t-il la séquence habituelle « livrer, prévenir » ?

Parce qu'il divise un événement en au moins deux : le code qui devient actif, et le flag qui s'active pour un compte donné. Tout processus de fermeture de boucle de feedback suppose que ces deux choses arrivent ensemble, ce qui est vrai pour la plupart des livraisons et faux pour tout ce qui se trouve derrière un flag utilisé pour un déploiement progressif, du ciblage ou comme interrupteur d'urgence. Fermer la boucle de feedback client décrit le fait de prévenir la demandeuse au moment précis où une entrée de changelog est approuvée et publiée ; cette étape est écrite pour le cas où publier l'entrée et la fonctionnalité devenant utilisable sont le même moment, et un flag est exactement le cas où ils ne le sont pas.

Moment	Ce qui est vrai	Faut-il déjà prévenir la demandeuse
Code fusionné, flag éteint partout	La fonctionnalité existe, personne ne peut l'utiliser	Non
Flag activé pour le compte de la demandeuse	La fonctionnalité existe, elle peut spécifiquement l'utiliser	Oui
Flag activé pour un pourcentage de déploiement qui l'exclut	La fonctionnalité existe, elle ne peut toujours pas l'utiliser	Non
Flag entièrement supprimé, la fonctionnalité est simplement active	La fonctionnalité existe pour tout le monde	Oui, si pas déjà prévenue

Quelle est la règle réelle pour savoir quand prévenir quelqu'un ?

Prévenir quand le flag est activé pour son compte, pas quand le code est fusionné et pas quand le flag est créé. Cette seule règle couvre chaque ligne du tableau ci-dessus, parce qu'elle relie la notification au seul fait qui compte vraiment pour la demandeuse : peut-elle, là maintenant, aller utiliser la chose. Une notification liée à la fusion ou à la création du flag est en réalité un rapport d'avancement technique, et quelqu'un qui a demandé une fonctionnalité ne veut pas un rapport d'avancement, elle veut savoir quand aller regarder.

Est-ce que ça veut dire que la demandeuse a besoin d'un accès anticipé ou spécial ?

Pas forcément, et forcer ça crée son propre problème. Si le flag est déployé progressivement pour des raisons de charge ou de stabilité, faire passer un compte en tête de file juste pour fermer une boucle plus vite sape la raison même pour laquelle le déploiement est échelonné. Les options honnêtes sont : attendre que le compte de la demandeuse atteigne le déploiement naturellement et la prévenir alors, ou, si l'urgence le justifie, l'activer délibérément en avance, comme une vraie décision de qui possède le déploiement, pas comme un effet de bord du désir d'envoyer une notification.

Et si le flag est un interrupteur d'urgence, pas un mécanisme de déploiement ?

Alors l'hypothèse sûre s'inverse. Un flag pensé pour pouvoir désactiver rapidement une fonctionnalité, plutôt que pour échelonner sa sortie, signifie généralement que la fonctionnalité est censée être entièrement active dès sa création, et le flag existe pour la sécurité plutôt que pour le séquencement. Dans ce cas, prévenir la demandeuse au moment du déploiement est correct, comme pour toute livraison sans flag ; la présence du flag est un détail opérationnel qui ne devrait pas changer quand la boucle se ferme. La distinction qui compte, c'est à quoi sert le flag, pas s'il en existe un.

Le flag change-t-il ce que les release notes de feature flag devraient dire ?

Il change quand l'entrée est publiée, pas ce qu'elle contient. Une entrée publiée au moment précis où le flag est activé pour 100 % des comptes se lit exactement comme une entrée de changelog normale, et c'est très bien ainsi ; une lectrice qui la trouve plus tard n'a aucune raison de savoir qu'un flag a un jour été impliqué. Ce qu'elle ne devrait pas faire, c'est être publiée pendant que le flag n'est activé que pour un petit pourcentage de déploiement, parce qu'une entrée de changelog publique envoie tous ceux qui la lisent, y compris les comptes sans le flag, chercher une fonctionnalité qu'ils ne trouveront pas, ce qui est une version pire du même problème, à l'échelle du produit entier plutôt qu'à l'échelle d'une seule demandeuse. Cette règle de timing est toute la différence entre des release notes de feature flag et une entrée ordinaire : le contenu est le même, seule la date de publication bouge. Comment écrire des release notes couvre la discipline du « aucune action nécessaire » qui s'applique aussi ici : il faut dire à la lectrice si ça la concerne, pas juste que ça existe quelque part.

Les e-mails de mise à jour produit devraient-ils traiter une fonctionnalité flaggée différemment ?

Oui, surtout en la retardant plutôt qu'en la réécrivant. Le modèle d'e-mail de mise à jour produit couvre les notifications ciblées face aux digests larges ; une fonctionnalité flaggée est un cas où le timing d'une notification ciblée doit être vérifié contre l'état du flag de la destinataire elle-même avant l'envoi, ce qu'un digest large ne peut pas faire facilement du tout, ce qui est une raison de plus pour laquelle un digest est le mauvais canal pour tout ce qui est encore à mi-déploiement.

FAQ

Faut-il dire à une demandeuse que sa fonctionnalité « arrive bientôt » une fois que le flag existe mais n'est pas encore activé pour elle ? Seulement s'il y a une date réelle et proche, et même là avec parcimonie. Un « bientôt » sans date se lit, passé assez de temps, exactement comme le silence, et crée une seconde promesse qui doit elle aussi être suivie et tenue.

Qui décide quand un flag est assez avancé pour fermer la boucle ? Qui possède le déploiement, pas qui possède la notification. La propriétaire du déploiement sait si « 100 % des comptes » est imminent ou encore à des semaines ; lier l'étape de fermeture de boucle à son état, plutôt qu'à une date fixe du calendrier, garde la notification honnête.

Une fonctionnalité derrière un flag permanent (jamais entièrement supprimé) reçoit-elle un jour une entrée de changelog publique ? Oui, dès qu'elle atteint ce que signifie « disponibilité générale » pour ce produit, même si le flag lui-même reste dans le code pour toujours pour des raisons opérationnelles. L'entrée de changelog parle de la disponibilité pour la lectrice, pas du détail d'implémentation de la façon dont cette disponibilité est réalisée.

Et si le flag est supprimé et que la fonctionnalité est tuée au lieu d'être livrée ? C'est un refus, pas une notification de livraison, et ça mérite le même soin que n'importe quel autre refus. Comment refuser une demande de fonctionnalité couvre ce que ce message devrait dire ; fermer la boucle honnêtement signifie parfois la fermer avec un non.

Les release notes de feature flag ont-elles besoin d'un modèle séparé d'une entrée normale ? Aucun changement de modèle, seulement une étape de vérification avant publication : vérifier l'état du flag pour le compte qui a demandé, pas seulement que le code a été fusionné, et retenir l'entrée jusqu'à ce que cette vérification passe. Tout le reste de l'entrée, la formulation, la longueur, la discipline de la FAQ, reste identique à n'importe quelle autre release note.

Quand une demande de fonctionnalité est en fait un bug

Mon, 07 Sep 2026 00:00:00 GMT

« Pouvez-vous ajouter un réglage pour augmenter la limite d'export ? » se lit comme une demande de fonctionnalité, et la plupart des systèmes de triage l'étiquettent ainsi sur le champ. Parfois c'en est une. Parfois l'export échoue à un nombre inférieur à la limite documentée à cause d'un bug, et la cliente, incapable de voir le code, a inventé la solution la plus plausible qu'elle sait décrire : donnez-moi un nombre plus grand et peut-être que ça marchera. Quelles étiquettes valent la peine couvre l'étiquette de type qui divise un backlog en demandes de fonctionnalités et bugs ; voici le cas où les mots mêmes d'une cliente pointent l'étiquette dans la mauvaise direction, et le coût de se tromper est une dérive lente vers un backlog plein de demandes que personne ne veut vraiment une fois qu'on regarde en dessous.

À quoi ressemble une demande de fonctionnalité qui est en fait un bug ?

Elle nomme un contournement au lieu du problème. Une vraie demande de fonctionnalité décrit généralement un résultat que le produit ne supporte pas du tout : « laissez-moi programmer ça pour plus tard », « ajoutez un mode sombre ». Un bug mal classé décrit un nombre, un seuil ou un comportement spécifique qui sonne comme un réglage manquant mais qui est en fait un symptôme : « augmentez le timeout », « ajoutez une option de retry », « laissez-moi exporter plus de lignes à la fois ». Le signe révélateur est que la demandeuse propose une implémentation, un réglage, un interrupteur, une surcharge, plutôt que de décrire un objectif, parce qu'elle a déjà essayé la fonctionnalité telle que documentée et elle n'a pas fait ce que la documentation dit qu'elle devrait faire.

Signal	Demande de fonctionnalité	Bug déguisé en demande de fonctionnalité
Ce que décrit la demandeuse	Un résultat que le produit ne peut pas faire	Un paramètre qu'elle veut changer
Si le comportement documenté couvre déjà ça	Non, vraiment manquant	Oui, mais ça ne fonctionne pas comme documenté
Si plus d'effort fait disparaître la demande	Non	Parfois, si le bug dépend d'un seuil
Où ça devrait être routé	Backlog produit	File des bugs

Pourquoi est-ce plus important que ça n'y paraît ?

Parce que les deux files ont des responsables, des délais et des critères de succès différents, et un bug classé comme demande de fonctionnalité est priorisé contre les demandes de fonctionnalités, rivalisant pour l'attention avec de vrais manques produit au lieu d'être corrigé selon le délai qu'un bug mérite. Comment suivre les demandes de fonctionnalités couvre pourquoi mélanger bugs et fonctionnalités dans une seule file laisse les plaintes les plus bruyantes passer devant les vraies demandes ; une demande de fonctionnalité qui est secrètement un bug fait le dommage inverse, reste dans le backlog produit à accumuler des votes pour une « fonctionnalité » qui disparaîtrait dès que le bug sous-jacent serait corrigé, ce qui gaspille le signal de priorisation pour quiconque lit ce backlog.

Comment distinguer quand les mots mêmes de la cliente pointent dans la mauvaise direction ?

Demandez ce qu'elle s'attendait à voir se passer, pas ce qu'elle veut que vous ajoutiez. « L'export plafonnait à 500 lignes et j'en ai besoin de 2 000, pouvez-vous augmenter la limite » sonne comme une demande de fonctionnalité d'augmentation de limite jusqu'à ce que la question de suivi, « 500 est-elle la limite documentée », révèle que le nombre documenté était 5 000 et que l'export échoue tôt. Cette seule question, ce qu'elle attendait contre ce qui s'est passé, fait la majeure partie du travail de tri, parce qu'une vraie demande de fonctionnalité n'a pas de comportement documenté auquel elle manque ; il n'y a rien à attendre parce que la capacité n'existe pas encore.

Les agentes de support ou les ingénieures devraient-elles trancher ?

Les agentes de support font le premier passage, parce qu'elles voient le ticket en premier, mais l'étiquette devrait être facile à changer et bon marché à se tromper, pas une décision unique qui fixe l'élément dans la mauvaise file pour toujours. Une seconde vérification légère, une ingénieure qui parcourt chaque semaine les nouvelles étiquettes « demande de fonctionnalité » à la recherche de ce qui sent le bug déguisé, attrape celles qu'une agente de support sans contexte du code n'aurait pas pu reconnaître. Ça n'a pas besoin d'être formel ; c'est plus un coup d'œil de cinq minutes qu'un processus de revue.

Boucler la boucle change-t-il une fois le vrai bug trouvé ?

Oui, et ça améliore le message que vous pouvez envoyer. Boucler la boucle de feedback client couvre le fait d'avertir la demandeuse quand ce qu'elle a demandé est livré ; un bug recatégorisé reçoit une meilleure version de ce message, parce que « nous avons trouvé et corrigé le bug derrière ça » sonne comme de la compétence, alors que « nous avons construit la fonctionnalité que vous avez demandée » n'aurait été vrai que par accident, parce que la vraie demande de fonctionnalité, une limite d'export vraiment plus haute, pourrait n'être jamais construite une fois le bug parti et la limite originale de 5 000 lignes suffisante.

Que se passe-t-il si la mauvaise classification n'est jamais repérée ?

Le backlog se remplit de demandes qui ressemblent à une vraie demande et qui n'en sont pas, et les décisions de priorisation prises contre ce backlog héritent de la distorsion. Une « fonctionnalité » avec quarante votes pourrait en réalité être quarante personnes tombant sur le même bug, et construire la demande littérale, un réglage pour augmenter une limite qui n'a jamais vraiment été la contrainte, livre de la complexité qui ne corrige rien, tandis que le bug sous-jacent continue de générer de nouvelles « demandes de fonctionnalités » de clientes qui n'ont pas encore trouvé ce fil.

FAQ

Vaut-il la peine d'ajouter une étape formelle pour vérifier chaque demande de fonctionnalité contre les bugs connus ? Pas une étape formelle, plutôt une habitude : quiconque trie une nouvelle demande de fonctionnalité devrait demander « le comportement documenté prétend-il déjà faire ça » avant d'appliquer l'étiquette, parce que cette seule question attrape la plupart des mauvaises classifications sans ajouter de surcharge de processus.

Et si la cliente insiste que c'est une demande de fonctionnalité même après que le bug a été trouvé ? Expliquez ce que vous avez trouvé et pourquoi le réglage qu'elle proposait ne serait plus nécessaire une fois le bug corrigé. La plupart des clientes demandent un contournement parce qu'elles ont supposé que le vrai correctif n'était pas disponible, pas parce qu'elles voulaient spécifiquement ce réglage.

Un élément recatégorisé perd-il les votes ou commentaires qu'il a accumulés en tant que demande de fonctionnalité ? Il devrait les conserver, visibles, parce que ces votes sont la preuve qui a mené à trouver le bug en premier lieu, et cacher cette trace rend la même mauvaise classification plus difficile à repérer la prochaine fois, sur un ticket différent.

Ça peut arriver dans l'autre sens, un bug qui est en fait une demande de fonctionnalité ? Moins souvent, mais oui : « c'est cassé » signifie parfois « ça ne fait pas ce que j'ai supposé que ça ferait », ce qui est une capacité manquante, pas un défaut. La même question, ce qu'elle attendait contre ce qui est documenté, trie aussi dans cette direction.

Suivre les demandes de fonctionnalités sans les perdre

Mon, 07 Sep 2026 00:00:00 GMT

Le suivi des demandes de fonctionnalités échoue presque toujours d'une de deux façons. Soit les demandes n'ont nulle part où aller, et vivent dans des boîtes mail et des fils Slack où elles sont oubliées une par une, soit elles ont un endroit où aller que personne ne revisite, et sont oubliées collectivement. Un système qui fonctionne doit résister aux deux échecs : il faut un seul endroit où chaque demande atterrit, et une raison de rouvrir cet endroit le mois prochain.

D'où viennent vraiment les demandes de fonctionnalités ?

De plus de canaux que la plupart des systèmes de suivi ne le prévoient. Un ticket de support qui inclut un « ce serait bien si ». Un commentaire sur une roadmap publique. Un appel commercial où une prospecte nomme la seule chose qui bloque la vente. Un widget dans le produit. Chaque canal a sa propre responsable et ses propres outils, et c'est justement pour ça que les demandes se dispersent : la file de tickets du support et le backlog de l'équipe produit sont rarement le même système, et une demande qui n'atteint qu'un des deux n'a, en pratique, atteint qu'un seul département.

Source	Responsable typique	Où elle disparaît le plus souvent
Tickets de support	Équipe support	Fermé comme résolu, jamais revisité
Appels commerciaux	Ventes / gestion de comptes	Un champ CRM que personne en produit ne lit
Widget dans le produit	Produit	Un formulaire envoyé sans suivi
Commentaires sur la roadmap	Qui a construit la roadmap	Le fil de commentaires lui-même
Réseaux sociaux / avis	Marketing ou personne	Capturé une fois en screenshot, puis disparu

La solution n'est pas un formulaire d'entrée unique pour chaque canal, que personne n'adopte. C'est une destination où chaque canal se déverse, même si le routage se résume d'abord à cinq minutes de copier-coller par jour jusqu'à ce que ce soit automatisé.

Qu'est-ce qui casse vraiment le suivi des demandes ?

Presque toujours deux choses. La première est une destination manquante : les demandes obtiennent une réponse dans le canal où elles sont arrivées et ne sont jamais enregistrées durablement nulle part, si bien que la même demande venant de trois clients différents ressemble à trois réponses isolées sans lien plutôt qu'à un seul signal. La seconde, plus fréquente, est une destination qui se remplit et cesse d'être lue. Un tableur de 400 lignes sans filtrage n'est plus un système de suivi ; c'est une archive qui se trouve être modifiable.

Le second échec est le plus dangereux, parce qu'il donne l'impression que le suivi fonctionne. Les demandes sont enregistrées. Rien ne semble cassé jusqu'à ce que quelqu'un demande « combien de personnes ont demandé X » et que la réponse honnête soit « il faudrait lire les 400 lignes pour le savoir ».

Que devrait vraiment enregistrer une demande de fonctionnalité ?

Assez pour répondre à trois questions plus tard sans relire le message d'origine : ce qui a été demandé, si possible avec les mots exacts de la demandeuse ; qui a demandé, et comment la contacter si la réponse finit par être « on l'a construit » ; et ce qu'il faudrait pour savoir si c'est une demande courante ou un cas isolé. Une citation exacte vaut plus qu'une paraphrase, parce qu'une paraphrase écrite par qui a trié la demande porte déjà sa propre lecture, et c'est justement cette lecture qu'une deuxième personne ne peut plus vérifier six mois plus tard.

Quelles étiquettes valent la peine ?

Deux, et elles répondent à des questions différentes. Une étiquette de type distingue une demande de fonctionnalité d'un rapport de bug, parce que les deux ont besoin de responsables et de délais différents, et les mélanger dans une seule file laisse les plaintes les plus bruyantes passer devant les demandes. Une étiquette de priorité, limitée à un petit ensemble comme low, medium et high, distingue « bloque quelqu'un dans l'usage du produit » de « ce serait sympa », parce que les deux méritent des délais de réponse très différents et qu'aucune ne devrait hériter du rythme de l'autre. Bien mettre l'étiquette de type suppose que la demande est ce qu'elle prétend être ; quand une demande de fonctionnalité est en fait un bug couvre le cas où les mots mêmes d'une cliente pointent cette étiquette dans la mauvaise direction.

Le triage automatisé peut appliquer les deux dès que la demande arrive. Chez changeloop, une soumission via le widget reçoit l'étiquette feature-request ou bug et une étiquette priority:low|medium|high dans la même passe, plus un tag from-widget pour que la source soit visible sans ouvrir l'élément. Cela suffit pour filtrer le backlog en une minute plutôt qu'un après-midi : montre-moi chaque demande de fonctionnalité haute priorité venue du widget ce mois-ci.

Une troisième étiquette vaut la peine dès qu'il existe une roadmap publique : un statut que la demandeuse peut vérifier elle-même. Roadmap publique couvre en entier les statuts planned, building et shipped ; en bref, cette étiquette transforme une file privée en quelque chose que la demandeuse peut consulter sans redemander.

Comment décide-t-on ce qu'il faut construire ensuite ?

Regrouper avant de compter. Dix demandes formulées différemment pour la même capacité sous-jacente se lisent comme dix lignes éparpillées dans un tableur, et comme un signal fort une fois regroupées, et ce regroupement est généralement l'étape manquante, pas le comptage. Un compte brut sans regroupement tend à récompenser la fonctionnalité au nom le plus accrocheur, pas celle qui a la plus forte demande réelle derrière elle.

Pondérer selon qui demande, pas seulement combien demandent. Une demande venant d'un compte proche du renouvellement porte une urgence différente de la même demande venant d'un essai gratuit, et un système de suivi qui jette ce contexte au profit d'un chiffre brut optimise pour le nombre le plus facile à calculer, pas le plus utile.

Chaque décision ici produit aussi des demandes qui perdent, et elles méritent une réponse aussi ; comment refuser une demande de fonctionnalité couvre quoi dire à celles dont la demande n'a pas été retenue. Regrouper et pondérer n'est que la moitié de "quoi construire ensuite" ; prioriser les demandes de fonctionnalités couvre les vrais cadres, RICE, la pondération par revenu et les comptes bruts, et où chacun se casse.

Comment boucler la boucle une fois qu'une fonctionnalité est livrée ?

C'est l'étape que les systèmes de suivi sautent le plus souvent, et celle que les demandeuses remarquent vraiment. Boucler la boucle de feedback avec le client couvre le mécanisme en entier ; ce qui revient ici : boucler la boucle ne fonctionne que si la demande d'origine est restée liée à la personne qui l'a faite. Un modèle de demande de fonctionnalité construit à partir d'une issue GitHub, avec l'identité de la demandeuse attachée à l'issue plutôt qu'enterrée dans un commentaire, est ce qui rend possible une notification automatique « livré » plutôt qu'une que quelqu'un doit se rappeler d'envoyer. Modèle de demande de fonctionnalité montre le modèle concret et à quoi sert chaque champ.

FAQ

Quel outil utiliser pour suivre les demandes de fonctionnalités ? Ce que l'équipe consulte déjà quotidiennement bat n'importe quel outil dédié que personne n'ouvre. Un tracker d'issues GitHub fonctionne bien si l'ingénierie vit déjà là ; un tableau léger fonctionne bien si le produit vit là. L'outil compte moins que le fait d'être rouvert.

Comment éviter que les demandes de fonctionnalités se dupliquent ? Regrouper par capacité sous-jacente avant de trier par formulation. Une recherche dans les demandes existantes avant d'en créer une nouvelle intercepte la plupart des doublons ; un regroupement mensuel intercepte le reste. Fusionner les doublons sans perdre la voix originale couvre quoi faire de la formulation une fois le regroupement lui-même fait, pour que la fusion ne rétrécisse pas discrètement la demande à quelle que soit la soumission arrivée en premier.

Chaque demande de fonctionnalité devrait-elle recevoir une réponse ? Chacune devrait recevoir un accusé de réception, même court, mais pas chacune n'a besoin d'une décision immédiate. Un statut visible, comme une étiquette de roadmap que la demandeuse peut vérifier elle-même, remplace la plupart des réponses individuelles qu'une équipe devrait sinon.

Quelle est la différence entre le suivi des demandes et une roadmap publique ? Le suivi est le registre interne de chaque demande, y compris celles qui ne seront jamais livrées. Une roadmap publique est le sous-ensemble auquel une équipe s'engage publiquement, avec un statut que la demandeuse peut voir sans redemander.

Tickets support vs. demandes : qui croire ?

Mon, 07 Sep 2026 00:00:00 GMT

Un tableau de demandes de fonctionnalités capture ce que les utilisatrices demandent quand elles ont le temps de s'asseoir et de décrire ce qu'elles veulent. Un ticket support capture ce sur quoi les utilisatrices sont bloquées maintenant, souvent agacées, souvent sans le vocabulaire pour décrire proprement la demande sous-jacente. Les deux sont un signal réel, et les équipes qui ne regardent que l'un des deux finissent par résoudre le mauvais problème avec assurance, parce que chaque canal surreprésente systématiquement un type différent d'utilisatrice et un type différent de besoin. Prioriser les demandes de fonctionnalités couvre le classement de ce qui est déjà sur le tableau ; ceci concerne l'écart entre ce qui arrive sur le tableau et ce qui n'apparaît jamais que comme ticket support.

Pourquoi le même problème sous-jacent apparaîtrait-il dans un canal et pas dans l'autre ?

Parce que les deux canaux ont des coûts d'activation différents, et la taille de ce coût détermine qui le franchit. Déposer une demande de fonctionnalité demande de l'initiative : une utilisatrice doit croire que la demande vaut la peine d'être articulée, trouver le tableau, et écrire quelque chose de cohérent, ce qui sélectionne des utilisatrices engagées et patientes déjà investies dans le produit. Déposer un ticket support demande presque aucune initiative en comparaison, souvent juste un clic sur "aide" en plein milieu d'une tâche, ce qui signifie qu'il capture des utilisatrices frustrées sur le moment, y compris celles qui ne se seraient jamais donné la peine avec un tableau de demandes. Un vrai manque dans le produit peut être invisible sur le tableau de fonctionnalités et bruyant dans le support simplement parce que les utilisatrices qui y sont confrontées sont celles les moins susceptibles de déposer une demande formelle.

Le volume de tickets pour une fonctionnalité manquante signifie-t-il la même chose que le nombre de votes pour elle ?

Non, parce qu'ils mesurent des populations différentes dans des conditions différentes. Une demande de fonctionnalité avec cent votes représente cent personnes qui ont pris le temps de trouver et soutenir une demande existante, ce qui est un signal fort de demande durable et réfléchie. Cent tickets support sur le même manque sous-jacent, déposés sur la même période, représentent probablement des utilisatrices qui se heurtent à un mur sur le moment, dont certaines oublieraient complètement une fois la friction immédiate passée. Traiter les deux comme un signal équivalent de "cent personnes veulent ça" surpondère le volume de tickets, parce que les tickets sont bon marché à générer et les votes non.

Tableau de demandes	Tickets support
Demande de l'initiative pour déposer	En demande presque aucune
Capture une demande réfléchie et durable	Capture une frustration sur le moment
Penche vers des utilisatrices engagées et patientes	Capture des utilisatrices qui n'utiliseraient jamais le tableau
Un compte de votes est un vrai signal d'engagement	Un compte de tickets reflète la friction, pas toujours le désir

Que signifie-t-il quand une fonctionnalité a des tickets support mais presque aucun vote sur le tableau ?

Souvent, que la demande existe mais que les utilisatrices qui y sont confrontées ne savent pas que le tableau existe, ne croient pas que voter changerait quoi que ce soit, ou rencontrent le problème trop rarement pour se donner la peine de changer de canal pour l'enregistrer formellement. C'est exactement la population qu'un tableau de demandes rate structurellement, et un faible compte de votes ici n'est pas une preuve de faible demande, c'est une preuve d'un écart de mesure. La solution n'est pas de se méfier des tickets, c'est de traiter un groupe de tickets support autour d'une fonctionnalité manquante comme son propre signal, à enregistrer vous-même sur le tableau, au nom des utilisatrices, pour qu'il ne reste pas invisible à qui priorise seulement à partir des comptes de votes.

Le tableau lit comme priorité basse :
"Export to CSV" : 4 votes sur 6 mois

Le support raconte une autre histoire :
"Export to CSV" : 31 tickets sur la même période, chacun
d'un compte différent, chacun fermé avec "pas
actuellement supporté, nous transmettrons le retour"

Un pic de tickets support signifie-t-il toujours que le problème sous-jacent est une fonctionnalité manquante ?

Non, et c'est là que les deux canaux peuvent induire en erreur dans la direction opposée. Un pic de tickets est tout aussi souvent causé par une interface confuse autour d'une fonctionnalité qui existe déjà, un bug, ou un changement sorti sans explication adéquate, rien de tout cela ne se résolvant en construisant quelque chose de nouveau. Lire chaque pic de tickets comme "les utilisatrices veulent une fonctionnalité que nous n'avons pas" produit une roadmap remplie de choses qui étaient en réalité des manques de documentation ou des problèmes d'utilisabilité déguisés. Le ticket support vous dit où est la friction ; il ne vous dit pas à lui seul si la solution est une nouvelle fonctionnalité, un changement d'interface, ou un meilleur article d'aide, et confondre cela gaspille du temps d'ingénierie sur la mauvaise solution.

Comment les deux signaux devraient-ils vraiment être combinés pour décider quoi construire ?

Utilisez les tickets pour trouver où est la friction, et utilisez le tableau de demandes, plus un contact direct là où le tableau est maigre, pour confirmer à quoi ressemble vraiment le résultat souhaité. Un groupe de tickets identifie un problème réel et ressenti ; il spécifie rarement la solution avec assez de précision pour construire dessus, parce qu'une utilisatrice frustrée dans une conversation de support décrit des symptômes, pas des spécifications. Le tableau de demandes, quand il a assez de votes sur le même problème sous-jacent, tend à porter plus du détail de "qu'est-ce qui satisferait vraiment ça", parce qu'écrire une demande est déjà un acte de spécifier ce qu'on veut, pas juste de rapporter ce qui ne va pas.

Les agentes support devraient-elles enregistrer elles-mêmes les tickets comme demandes de fonctionnalités ?

Oui, et c'est le correctif à plus fort levier pour l'écart entre les deux canaux. Une agente qui reconnaît un ticket comme une demande de fonctionnalité déguisée, plutôt que de simplement le résoudre et passer à autre chose, peut l'enregistrer sur le tableau au nom de la cliente, ce qui comble directement l'écart de mesure plutôt que d'exiger que la cliente découvre et utilise un second canal. Cela ne fonctionne que si l'enregistrement prend des secondes, pas des minutes, pour l'agente, pour que la friction de le faire soit inférieure à la friction de simplement fermer le ticket et passer au suivant.

FAQ

Les votes de demandes de fonctionnalités devraient-ils jamais être décomptés s'ils viennent tous d'un seul compte ou d'une seule équipe ? Oui, pondérez par comptes ou organisations distincts plutôt que par compte brut de votes, parce que cinq votes de cinq personnes de la même entreprise représentent les priorités d'une cliente, pas cinq confirmations indépendantes de demande.

Vaut-il la peine de construire une fonctionnalité qui apparaît beaucoup dans les tickets mais a presque aucun vote ? Souvent oui, à condition que le volume de tickets vienne vraiment de comptes distincts et que le besoin sous-jacent soit confirmé plutôt que supposé ; traitez le faible compte de votes comme un artefact de mesure du coût d'activation du tableau, pas comme une preuve que la demande n'est pas réelle.

Comment distinguer d'un coup d'œil un ticket de confusion d'interface d'un vrai ticket de fonctionnalité manquante ? Regardez si la résolution consiste à expliquer une capacité existante ou à s'excuser pour une manquante. Un motif de résolutions "oh, c'est en fait juste là" pointe vers un problème d'interface ou de découvrabilité ; un motif de "on ne supporte pas encore ça" pointe vers un vrai manque.

Cette distinction compte-t-elle autant avec un très petit volume de support ? Moins mécaniquement, puisqu'une poignée de tickets est facile à lire individuellement sans avoir besoin d'analyse agrégée, mais le biais sous-jacent, les tickets surreprésentent les utilisatrices frustrées et sous-représentent les patientes, est présent à toute échelle et vaut la peine d'être gardé à l'esprit même quand vous lisez chaque ticket vous-même.

Tags git, releases et votre changelog

Mon, 07 Sep 2026 00:00:00 GMT

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 ?

Enregistrement	Vit dans	Écrit pour
Tag git	Le dépôt, en tant que référence	Quiconque récupère ce commit exact
Release	L'hébergeur de code (GitHub, GitLab)	Quiconque télécharge un build
Entrée de changelog	Le changelog propre au produit	Quiconque utilise le produit, pas que le dépôt

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.

Changelogs d'API internes : ce qui change

Mon, 07 Sep 2026 00:00:00 GMT

Chaque autre article de ce hub suppose que l'appelant d'une API est extérieur à l'entreprise : l'ingénieure d'une cliente, une partenaire, quelqu'un qui a trouvé la doc tout seul. Beaucoup d'API ont un type d'appelant complètement différent, une équipe dans le bureau d'à côté ou deux étages plus loin, et ça change le calcul de ce qu'un changelog lui doit, parce qu'un message Slack l'atteint et qu'aucun ticket de support n'est généralement jamais ouvert. La plupart des équipes en concluent que les API internes n'ont pas besoin de changelog. Ce dont elles ont vraiment besoin, c'est d'un différent.

Qu'est-ce qui rend le changelog d'une API interne différent de celui d'une API publique ?

Le public est joignable directement, ce qui supprime la raison principale d'exister de la plupart des changelogs d'API publiques : diffuser vers des appelants qu'on ne peut pas contacter individuellement. L'équipe propriétaire d'une API interne sait généralement exactement quelles autres équipes l'appellent, parfois jusqu'au service précis. Ça fait d'un message ciblé, pas d'un flux public, le choix par défaut naturel, et c'est pour ça que les API internes finissent si souvent sans aucun changelog : l'équipe propriétaire prévient les deux ou trois équipes dont elle se souvient, en supposant que ça couvre tout le monde.

	Changelog d'API publique	Changelog d'API interne
Qui le lit	N'importe quel appelant externe, généralement injoignable directement	Un petit ensemble, généralement connu, d'équipes internes
Canal par défaut	Une page et un flux	Un message aux équipes appelantes, idéalement aussi une page
Plus gros risque	Un appelant rate l'entrée complètement	L'équipe propriétaire oublie un appelant dont elle ne se souvient plus
Ce qui remplace « on ne sait pas qui nous appelle »	Rien ; publier largement	Un vrai registre des appelants, tenu à jour

Pourquoi « on préviendra juste les équipes qui nous appellent » s'effondre-t-il ?

Parce que l'ensemble des appelants n'est jamais aussi petit ni aussi statique que l'équipe propriétaire s'en souvient. Un service construit pour une consommatrice gagne un second appelant six mois plus tard, via une intégration que personne n'a annoncée, et la liste mentale « qui nous appelle » de l'équipe propriétaire est désormais fausse sans que personne ne le remarque. L'échec est ordinaire et courant, le résultat par défaut de compter sur la mémoire plutôt que sur un registre, pas le signe que quelqu'un a été négligent. Qu'est-ce qu'un breaking change couvre comment décider si un changement d'API compte comme cassant en premier lieu ; le cas interne ajoute une seconde question, plus difficile, par-dessus celle-là, à savoir qui prévenir.

Une API interne a-t-elle même besoin d'une page de changelog façon publique ?

Généralement oui, même si le canal principal est direct. Une page donne au message direct quelque chose vers quoi pointer, si bien que la notification peut rester courte (« breaking change sur /v2/accounts, détails ici ») plutôt que d'essayer de porter l'explication complète dans un message de chat qui va défiler et disparaître. Elle devient aussi ce qu'une nouvelle équipe, ou une qui a raté le message direct, peut consulter quand son intégration casse et qu'elle essaie de comprendre pourquoi. La page n'a pas besoin d'être soignée ni publique ; elle doit être liable et survivre au fil Slack qui l'a annoncée.

Qui maintient réellement la liste des appelants ?

L'équipe propriétaire, et ça doit être traité comme un vrai artefact, pas comme un savoir tribal. La version la moins chère est un fichier dans le dépôt même de l'API, une courte liste de services consommateurs avec une responsable par entrée, mise à jour chaque fois qu'une nouvelle intégration est construite, la même discipline que n'importe quelle déclaration de dépendance. L'alternative, demander autour de soi avant chaque breaking change, fonctionne jusqu'au jour où quelqu'un oublie de demander à la bonne personne, et une API interne qui casse silencieusement pour une équipe est un incident plus petit qu'un incident public, mais ça reste un incident, généralement découvert par l'astreinte de cette équipe plutôt que par la propriétaire de l'API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Un fichier comme celui-ci transforme « qui devons-nous prévenir » d'une question en une simple consultation. Des outils construits exactement pour ce problème, comme le catalogue de services de Backstage, modélisent les API comme des entités de premier ordre avec des consommateurs déclarés, pour la même raison : une fois qu'une organisation a assez de services internes, la mémoire de personne sur qui appelle quoi ne reste plus exacte toute seule, et quelque chose doit tenir le registre à sa place. La documentation de l'outil que vous faites déjà tourner en interne est généralement le bon endroit à vérifier avant d'en construire un sur mesure.

Qu'est-ce qui appartient à une entrée de changelog interne qu'une publique n'aurait pas besoin d'avoir ?

Plus de précision opérationnelle, parce que la lectrice est une autre ingénieure qui va agir là-dessus au sein de la même infrastructure, pas le lire comme un résumé. Dans quels environnements le changement est en production et quand, parce que les services internes sont souvent promus par étapes qu'un appelant public ne voit jamais. Si le changement nécessite une mise à jour de configuration ou de bibliothèque client côté consommatrice, formulée comme une commande s'il y en a une. Et, parce que les appelants internes peuvent souvent coordonner le correctif directement avec l'équipe propriétaire, un contact nommé plutôt qu'un canal de support : « préviens @maria si ça casse quelque chose » est une ligne parfaitement raisonnable dans une entrée interne et une ligne étrange dans un changelog d'API publique.

Est-ce que ça s'applique de la même façon à un changelog dans un monorepo ?

Ça aiguise le même problème plutôt que de le remplacer. Changelogs de monorepo couvre quand un package a besoin de son propre changelog ; une API interne qui n'est qu'un package parmi d'autres dans un monorepo a quand même besoin que ses consommateurs soient suivis explicitement, parce que partager le dépôt avec ses appelants ne veut pas dire qu'ils remarqueront un changement à moins que quelque chose ne le leur signale. La proximité dans le dépôt n'est pas la même chose que la proximité dans l'attention.

FAQ

Une API purement interne a-t-elle besoin d'un changelog si elle n'a qu'un seul appelant ? À peine, et un message direct à cette seule équipe suffit généralement. Le changelog se justifie dès qu'il y a plus d'un appelant, ou dès que la liste des appelants a déjà surpris l'équipe propriétaire, parce que c'est le signe que la mémoire seule n'est plus fiable.

Les changements d'API internes devraient-ils passer par la même revue que les publics ? La formulation peut être plus légère, puisque la lectrice est une collègue et non une appelante externe, mais la décision de savoir si un changement est cassant mérite le même soin dans les deux cas. Une appelante interne a quand même du code en production qui dépend de l'ancien comportement.

Comment découvrir qui appelle une API interne si ça n'a jamais été suivi ? Les logs du serveur ou les données de trafic d'un service mesh sont la réponse honnête si aucun registre des consommateurs n'a jamais été tenu ; traitez cette découverte comme le moment d'en commencer un, pas comme un nettoyage ponctuel.

Un message Slack suffit-il, ou un changement interne a-t-il quand même besoin d'une entrée de changelog formelle ? Les deux, pour tout ce qui n'est pas purement additif. Le message est ce qui se lit à temps ; l'entrée est ce qu'une équipe enquêtant sur un problème des semaines plus tard, qui n'a jamais vu le message, peut quand même trouver.

Notes de release internes : qui d'autre doit savoir

Mon, 07 Sep 2026 00:00:00 GMT

Tous les autres articles de ce hub supposent que le lecteur d'une note de release est un client. Le support, les ventes et le customer success lisent aussi, ou essaient, et la plupart apprennent ce qui est sorti parce qu'une cliente le demande en premier. Cet ordre est inversé, et c'est aussi le défaut dans la plupart des entreprises, parce que le processus de release s'arrête au moment où la note orientée client sort, et personne n'a construit une deuxième étape, plus petite, pour les gens qui doivent répondre à des questions dessus une heure plus tard.

Qu'est-ce qu'une note de release interne, et en quoi diffère-t-elle d'une note orientée client ?

C'est un document plus court, écrit pour des gens qui connaissent déjà le produit en profondeur, qui leur dit ce qui a changé et quoi en faire dans leur travail concret. Un agent de support n'a pas besoin du cadrage soigné qu'utilise une annonce orientée client ; il doit savoir à quoi ressemble le changement dans le produit en ce moment, quelle sera la question la plus probable à son sujet, et si des tickets ouverts sont concernés. Une note orientée client vend le changement. Une note interne équipe quelqu'un pour le gérer.

Public	Ce qu'il doit savoir	Où il en a besoin
Support	Ce qui a changé dans l'interface, questions probables, tickets ouverts concernés	Là où il cherche déjà des réponses
Ventes	Ce que ça débloque pour une affaire, ce que ça ne fait pas encore	Là où il se prépare aux appels
Customer success	Quoi dire aux clientes existantes, et qui l'a demandé	Là où il planifie les contacts
Direction	Ce qui est sorti par rapport à ce qui était promis, et quand	Un résumé court et récurrent, pas par release

Pourquoi les équipes internes apprennent-elles les lancements en retard ?

Parce que le processus de release est généralement construit autour d'un seul artefact, la note orientée client ou l'entrée de changelog, et tout ce qui est interne est censé découler de la lecture de ce document unique. Ce n'est pas le cas. Les agents de support sont occupés avec le ticket devant eux, pas en train de parcourir un changelog pour trouver du contexte, et une note écrite pour une cliente omet souvent justement le détail opérationnel dont un agent a besoin, comme à quel plan la fonctionnalité est réservée ou à quoi ressemble le message d'erreur quand ça échoue. Le temps qu'une cliente pose la question, l'agent lit la même note publique que la cliente vient de lire, sans aucune longueur d'avance.

Qu'est-ce qu'une note interne devrait dire qu'une note orientée client ne dit pas ?

Les détails opérationnels qu'une note orientée client omet délibérément. Quels plans ou comptes l'ont. À quoi ça ressemble quand quelque chose tourne mal, et quoi dire à une cliente qui tombe dessus. Si ça ferme des demandes ou tickets ouverts, et lesquels, pour qu'un agent travaillant sur un ticket lié sache qu'il doit vérifier. Qui dans l'équipe en est responsable si une question va au-delà de ce que couvre la note. Rien de tout ça n'appartient à la version orientée client, écrite pour être lue une fois par quelqu'un en dehors de l'entreprise ; tout ça est exactement ce dont a besoin quelqu'un qui répond à la même question quarante fois par semaine.

Note interne : export CSV en masse (sortie le 08/09/2026)

- Réservé aux plans Team et Enterprise. Free et Pro ne voient
  aucun changement.
- Échec fréquent : les exports de plus de 50k lignes expirent ;
  problème connu, correctif suivi séparément. Dire à la cliente
  de filtrer par plage de dates.
- Ferme 14 demandes ouvertes étiquetées `bulk-export`. Modèle de
  réponse dans le document partagé.
- Responsable : équipe platform, #platform-eng pour tout ce qui
  dépasse cette note.

Quatre lignes qu'un agent de support peut utiliser immédiatement, dont aucune n'appartiendrait à l'entrée publique du changelog pour la même fonctionnalité.

Qui devrait l'écrire, et quand ?

Qui écrit la note orientée client est généralement la bonne personne, parce qu'elle a déjà tout le contexte, mais ça devrait être un passage court et séparé plutôt qu'une tentative de faire servir un seul document aux deux publics. Les fusionner produit une note orientée client encombrée de détails internes, ou une note interne trop soignée pour être vraiment utile, et c'est plus rapide en pratique d'écrire deux documents courts que de négocier un seul document pour servir deux publics à la fois. Le timing compte plus que l'auteur : la note interne doit sortir avant celle orientée client, ne serait-ce que de quelques heures, pour que le support n'apprenne jamais un changement au même endroit qu'une cliente.

Où devrait-elle vivre pour que le support la trouve vraiment au moment d'un ticket ?

Là où l'équipe cherche déjà les choses quand un ticket arrive, pas dans un changelog séparé que personne n'a de raison d'ouvrir de son propre chef. Une équipe de support qui utilise une base de connaissances partagée a besoin de la note là, liée depuis l'endroit où les tickets sur cette partie du produit sont déjà étiquetés. Une équipe qui vit dans un canal partagé en a besoin publiée là, cherchable, au moment où c'est pertinent, plutôt qu'enterrée dans un digest quotidien qu'elle parcourt une fois. Le schéma orienté client de notification ciblée contre digest s'applique aussi ici : une note interne sur un changement précis et imminent devrait atteindre l'équipe directement, pas attendre un récapitulatif hebdomadaire qui arrive après que le premier ticket existe déjà.

A-t-elle besoin de la même rigueur de révision que l'externe ?

Moins, et c'est voulu. Une note orientée client représente l'entreprise publiquement et mérite un passage d'édition soigné ; une note interne existe pour être rapide et précise, et lui imposer le même niveau de finition est généralement exactement ce qui pousse les équipes à arrêter de l'écrire du tout. Une note interne rapide et un peu brute qui sort une heure avant le lancement bat une note polie qui arrive le lendemain, quand le premier ticket de support est déjà arrivé perdu.

FAQ

Les notes de release internes devraient-elles suivre le même processus d'approbation que celles orientées client ? Non. Un passage plus léger et plus rapide est justement le but. Exiger la même révision transforme une note interne du jour même en une de la semaine suivante, quand le support a déjà répondu à la question sans elle.

Qui est responsable des notes de release internes s'il n'y a pas de rôle dédié à la communication interne ? Qui écrit la note orientée client, comme un deuxième passage court juste après. Ça n'a pas besoin d'une personne responsable séparée, juste l'habitude de ne pas traiter la note orientée client comme le seul artefact que produit une release.

Les notes de release internes ont-elles besoin de leur propre changelog ou archive ? Un endroit cherchable bat une archive chronologique que personne ne parcourt. Si le support a déjà une base de connaissances, la note appartient là, étiquetée à la fonctionnalité, plutôt que dans un changelog interne séparé qui n'aide que quelqu'un qui connaît déjà la date de sortie.

Quel est le risque de sauter les notes de release internes pour les petits changements ? Les petits changements sont justement ceux pour lesquels le support reçoit des questions sans prévenir, parce qu'un petit changement reçoit rarement une annonce à l'échelle de l'entreprise. La taille de la note de release devrait s'adapter à la taille du changement ; elle ne devrait jamais tomber à zéro juste parce que le changement était mineur.

Release notes mobiles : ce que la limite fait sauter

Mon, 07 Sep 2026 00:00:00 GMT

Tout ce que ce hub dit sur l'écriture de release notes suppose une page qu'on contrôle entièrement : n'importe quelle longueur, des liens qui fonctionnent, une mise en forme qui s'affiche. Les release notes d'une app mobile vivent dans la boîte de quelqu'un d'autre. Apple donne environ 4 000 caractères mais n'affiche que les premières lignes avant qu'on touche « plus » ; Google donne un espace similaire avec le même problème d'aperçu, et aucune des deux plateformes n'affiche de lien cliquable dans le texte. Les règles de comment écrire des release notes que les gens lisent vraiment s'appliquent toujours : dire ce qui a changé et ce que la lectrice doit faire, mais l'espace pour le faire est une fraction de ce que permet une page de changelog, et les coupes doivent être délibérées, pas accidentelles.

Qu'est-ce qui entre vraiment dans l'aperçu visible ?

Les une à deux premières lignes, environ 80 à 170 caractères selon l'appareil et la taille de police, avant que la lectrice doive toucher pour développer. C'est tout le budget pour la partie de la release note qui décide si quelqu'un va lire le reste, et ça veut dire que la phrase la plus importante doit venir en premier, pas le numéro de version, pas une salutation, pas un en-tête de catégorie. Une release note qui commence par « Nouveautés de cette version : » a déjà dépensé un tiers de son espace visible sur quatre mots qui ne disent rien à la lectrice.

Plateforme	Limite totale approximative	Aperçu effectif avant « plus »
App Store (iOS)	~4 000 caractères	2-3 lignes, environ 80-170 caractères
Google Play	~500 caractères par langue, certains champs plus courts	2-3 lignes, similaire à iOS
Les deux	Aucun lien cliquable dans le champ release notes	N/D

La règle « ce que vous pouvez faire maintenant, ce qu'on vous doit » fonctionne-t-elle toujours à cette longueur ?

Oui, et elle devient plus stricte, pas différente. Une phrase par entrée, verbe en premier, sans mise en contexte : « Exportez vos données en CSV depuis Paramètres. » bat « Nous avons ajouté la possibilité pour les utilisateurs d'exporter désormais leurs données au format CSV » en utilisant un tiers des mots pour dire la même chose. À la longueur d'une page de changelog, une phrase un peu bavarde coûte une demi-seconde à la lectrice. À la longueur d'une release note mobile, cette même verbosité peut pousser la phrase entière hors de l'aperçu visible, si bien que la lectrice ne voit jamais le verbe qui lui aurait dit ce qui a changé.

Mauvais, gaspille l'aperçu sur l'emballage :
"Nous sommes ravis de vous apporter une nouvelle mise
à jour pleine d'améliorations ! Lisez la suite pour
les détails."

Bon, toute la valeur dans la première ligne :
"Exportez vos données en CSV. Le mode sombre respecte
désormais le réglage système. Correction d'un plantage
à l'ouverture de liens partagés."

Qu'est-ce qui doit être coupé qu'une entrée de changelog web garderait normalement ?

Les liens, d'abord, parce qu'aucun des deux stores ne les rend cliquables, donc une URL dans le texte est un poids mort que la lectrice devrait retaper. Si l'entrée a besoin d'une destination, dites plutôt quoi toucher dans l'app : « Voyez les nouveaux filtres sous Paramètres > Recherche » fonctionne ; « Lisez-en plus sur example.com/blog/filtres » ne fonctionne pas, sur cette surface. Ensuite, tout ce qui est conditionnel ou spécifique à un public : un changelog web peut dire « si vous utilisez l'API, ça vous concerne », mais une fiche de store atteint chaque utilisatrice installée en même temps, donc une ligne conditionnelle se lit comme du bruit pour les 95 % à qui ça ne s'applique pas. Mettez le détail conditionnel dans un message in-app à la place, déclenché pour les comptes que ça concerne réellement.

Chaque version devrait-elle avoir ses propres notes, ou est-ce correct de réutiliser « corrections de bugs et améliorations de performances » ?

Réutilisez-le pour les versions qui sont vraiment ça, mais vérifiez à quelle fréquence c'est vraiment vrai. Comment écrire des release notes couvre déjà pourquoi cette phrase trahit une note écrite de l'intérieur plutôt que pour la lectrice ; sur mobile, elle fait un double dégât, parce que les release notes du store sont l'un des rares endroits où certaines utilisatrices voient quoi que ce soit entre deux mises à jour, et une longue série de « corrections de bugs et améliorations de performances » se lit comme si l'app ne changeait pas, ce qui est une impression pire qu'aucune note du tout pour cette période.

Les release notes influencent-elles si les gens mettent à jour l'app ?

Indirectement, via la visibilité plutôt que la persuasion. La plupart des utilisatrices mettent à jour automatiquement et ne lisent jamais les notes avant de le faire ; les notes comptent le plus pour la minorité qui vérifie les mises à jour manuellement, et pour les critiques ou la presse qui parcourent l'historique d'une fiche de store. Écrire pour ce public plus restreint est quand même rentable, parce qu'une fiche avec un vrai historique d'entrées spécifiques et datées se lit comme une app activement maintenue, et une fiche avec un an de « corrections de bugs et améliorations de performances » non, peu importe ce qui a réellement été livré durant cette période.

Et une mise à jour forcée, où la note doit expliquer pourquoi l'utilisatrice n'a pas le choix ?

Indiquez la raison et l'échéance dans la première ligne, avant tout le reste, parce qu'une mise à jour forcée est le seul cas où la lectrice est agacée avant même de commencer à lire. « Cette mise à jour est nécessaire pour continuer à synchroniser vos données. Mettez à jour avant le [date] pour éviter une interruption. » dit quoi faire et pourquoi en une seule phrase ; enterrer cette raison sous trois lignes de notes de fonctionnalités sans rapport se lit comme si l'app cachait la partie gênante.

FAQ

Les release notes mobiles devraient-elles correspondre au changelog web de la même version ? Couvrir les mêmes changements sous-jacents, mais pas mot pour mot. Le changelog web peut se permettre l'explication complète ; la note mobile a besoin des mêmes faits compressés en une phrase avec le verbe en premier, ce qui veut généralement dire que c'est une réécriture, pas un copier-coller.

Vaut-il la peine de localiser les release notes mobiles pour chaque langue supportée ? Oui, plus que pour un changelog web, parce que la fiche du store est souvent la seule surface localisée que certaines utilisatrices voient entre deux sessions, et les deux plateformes supportent des release notes par locale sans travail d'ingénierie supplémentaire au-delà de la traduction elle-même.

Quelle longueur devrait avoir une release note mobile s'il n'y a pas de limite forçant la concision ? Courte quand même. Le plafond de 4 000 caractères sur iOS est rarement la vraie contrainte ; c'est l'aperçu de 2-3 lignes qui l'est, et écrire au-delà de ce que cet aperçu montre veut juste dire que moins de gens lisent la partie qui comptait.

Les release notes ont-elles besoin du numéro de version dans le texte visible ? Non. Le store affiche déjà le numéro de version à côté des notes. Le répéter dans le texte dépense des caractères visibles sur une information que la lectrice a déjà sous les yeux.

Changelogs de monorepo : un seul, ou un par package ?

Mon, 07 Sep 2026 00:00:00 GMT

Un monorepo héberge plusieurs éléments déployables séparément dans un seul dépôt, et un changelog doit d'abord répondre à une question : le lecteur s'intéresse-t-il au repo, ou à un package particulier à l'intérieur ? La plupart des équipes ne décident jamais ça délibérément. Elles commencent avec un changelog parce qu'il y a un repo, ajoutent des packages au fil du temps, et finissent avec un journal où quelqu'un utilisant la CLI doit défiler devant quarante entrées backend sans rapport pour trouver celle qui a livré son correctif. Ce qui décide la bonne forme, ce n'est pas la structure du dépôt, mais qui lit le journal et ce qu'il sait déjà chercher.

Qu'est-ce qui rend le changelog d'un monorepo différent de celui d'un repo unique ?

Un changelog de repo unique a un public implicite : tous ceux qui utilisent l'unique chose que ce repo construit. Le public d'un monorepo se divise par package, et les packages du même repo sont souvent livrés selon des calendriers différents, à des consommateurs différents, à des niveaux de stabilité différents. Une bibliothèque publiée dans un registre et un outil d'administration interne peuvent vivre dans le même monorepo et n'avoir presque rien en commun pour qui lit le changelog.

Forme du repo	Lecteur typique	Changelog adapté
Une seule app déployable	Tous ceux qui utilisent le produit	Un journal, pour tout le repo
Workspace de bibliothèques (plusieurs packages publiés)	Qui dépend d'un package particulier	Un journal par package
App plus outillage interne	Deux publics distincts sans recouvrement	Divisé par public, pas par dossier
App plus son propre SDK	Utilisateurs du produit, et intégrateurs du SDK	Deux journaux : un pour le produit, un pour le SDK

Chaque package a-t-il besoin de son propre changelog ?

Seulement ceux avec un public indépendant. Un package publié dans un registre a besoin de son propre journal, parce que la personne qui l'installe n'a aucune raison de lire quoi que ce soit d'autre dans le repo, et les outils de release de monorepo comme Lerna et Changesets écrivent un CHANGELOG.md par package, à côté de son package.json. Un utilitaire interne avec un seul consommateur, l'app déjà présente dans le même repo, n'a pas besoin d'un journal séparé ; intégrer ses changements dans les entrées de cette app est plus utile qu'un second fichier que personne en dehors de l'équipe n'ouvre.

Le test est le même que celui qui décide si une entrée quelconque appartient à un changelog : le lecteur le remarquerait-il ou s'en soucierait-il, et peut-il agir en le sachant. Applique-le par package, pas par dossier, et un repo avec douze packages peut finir avec deux vrais changelogs et dix packages qui n'en ont tout simplement pas besoin.

Comment sait-on quel package a causé quelle entrée de changelog ?

Étiquette chaque entrée avec son package au moment où elle est écrite, pas après coup en inspectant quels fichiers un commit a touchés. Un commit qui corrige une bibliothèque interne partagée peut produire une entrée de changelog dans chaque package qui en dépend, et les chemins de fichiers seuls ne peuvent pas dire laquelle de ces entrées en aval le lecteur doit vraiment voir ; seule une personne qui décide "ceci est visible pour qui utilise le package A et pas pour qui utilise le package B" le peut. Les conventional commits aident ici mécaniquement, en nommant le package dans chaque commit, mais le scope ne produit toujours qu'un brouillon. La même règle à deux niveaux de cet article s'applique par package : un brouillon avec le bon scope a quand même besoin d'un passage humain avant d'être formulé pour le lecteur réel de ce package.

De quoi un changelog partagé a-t-il besoin qu'un changelog de repo unique n'a pas ?

Une étiquette de package sur chaque entrée, en tout premier, avant la description, pour qu'un lecteur qui parcourt le journal puisse sauter en une seule passe tout ce qui ne le concerne pas. Sans cette étiquette, un journal partagé se lit comme un flux aléatoire, et un lecteur qui s'intéresse à un package n'a aucun moyen de le filtrer sauf mémoriser quelles lignes comptent, ce que personne ne fait après la première semaine.

## 2026-09-07

### [cli] Ajouté
- `acme push --dry-run` montre ce qui serait envoyé sans
  l'envoyer réellement.

### [core] Corrigé
- Le backoff des tentatives ne se réinitialise plus sur une
  requête réussie qui renvoie un corps vide.

Deux entrées, deux publics, un coup d'œil pour les distinguer. Un workflow façon Changesets intègre cet étiquetage directement dans le processus de release : un contributeur écrit une note courte, avec le scope du package, à côté de son changement, et l'outil assemble les changelogs par package et les montées de version à partir de ces notes au moment de la release, plutôt que d'essayer de reconstruire les frontières des packages après coup à partir d'un historique de commits fusionné.

Comment le versioning s'articule-t-il avec un changelog de monorepo ?

Les packages versionnés indépendamment ont besoin de leur propre changelog parce qu'ils ont leur propre numéro de version, et un changelog partagé ne peut pas exprimer "le package A est passé de 2.1 à 2.2 pendant que le package B est resté à 1.4" sans devenir deux journaux dans un seul fichier. Semantic versioning et votre changelog couvre comment un numéro de version devrait correspondre aux catégories de changelog ; dans un monorepo, cette correspondance doit s'appliquer par package, parce qu'un changement cassant dans un package n'en est pas un pour un package frère qui n'en dépend pas.

Un repo qui livre un produit comme une seule unité déployable, même s'il est construit à partir de nombreux packages internes, n'a pas ce problème : les packages partagent une version parce qu'ils sont toujours livrés ensemble, et un changelog unique est correct.

Comment les tags git s'intègrent-ils dans un monorepo ?

La même règle de tags git, releases et votre changelog s'applique, par package : un package avec sa propre version a besoin de son propre préfixe de tag, typiquement nom-du-package@1.4.0 plutôt qu'un v1.4.0 nu qui ne peut pas dire à quel package il appartient. Un monorepo tagué seulement avec des numéros de version nus ne peut pas répondre plus tard "qu'y avait-il dans core quand cli a livré la 2.2", parce que rien sur le disque n'enregistre à quel package ce tag appartenait réellement.

FAQ

Ai-je besoin d'un changelog séparé pour chaque package d'un monorepo ? Seulement pour les packages avec un public indépendant, généralement tout ce qui est publié dans un registre. Un package avec un seul consommateur interne déjà présent dans le même repo peut s'intégrer dans le journal de ce consommateur plutôt que d'en maintenir un propre.

Qu'est-ce qui étiquette une entrée de changelog avec le bon package ? La personne qui écrit l'entrée, au moment où elle l'écrit, pas un scan automatique des chemins de fichiers modifiés. Un changement dans une bibliothèque partagée peut produire une entrée différente dans chaque package qui en dépend, et seule une personne peut décider ce que chacune de ces entrées en aval devrait vraiment dire.

Un monorepo devrait-il utiliser un seul numéro de version pour tout ? Seulement si chaque package est toujours livré avec les autres. Si les packages sont un jour publiés indépendamment, ils ont besoin de versions indépendantes, et les versions indépendantes ont besoin de changelogs indépendants pour avoir un sens.

Un outil de changelog de monorepo remplace-t-il l'étape d'édition humaine ? Non. Des outils comme Changesets automatisent la collecte et l'assemblage des notes par package au moment de la release ; la note elle-même, écrite dans le langage du lecteur plutôt que celui du contributeur, reste le travail d'une personne, comme dans n'importe quelle autre pipeline de changelog.

Comment annoncer une nouvelle fonctionnalité (sans silence)

Mon, 07 Sep 2026 00:00:00 GMT

La plupart des annonces de fonctionnalités meurent dans un canal que personne ne lit deux fois : un tweet qui défile, un email du jour de sortie enterré sous les douze autres qu'une abonnée a reçus cette semaine-là, un message Slack dans un canal que la moitié de l'équipe a coupé il y a des mois. La fonctionnalité est sortie. Presque personne parmi celles qui l'auraient utilisée ne l'a su. Corriger ça tient moins à écrire une meilleure annonce qu'à choisir le bon canal pour la bonne lectrice, et à atteindre directement celles qui l'ont explicitement demandée plutôt que de compter sur le fait qu'elles remarquent une annonce générale.

Où une nouvelle fonctionnalité devrait-elle vraiment être annoncée ?

À plus d'un endroit, parce que « tout le monde lit le même canal » n'est jamais vrai. Une entrée de changelog ou de flux sert la lectrice qui vérifie à son propre rythme et veut le registre permanent et daté. Un avis in-app sert la lectrice déjà en train d'utiliser le produit qui utiliserait la fonctionnalité aujourd'hui si elle savait qu'elle existe. L'email sert la lectrice qui n'est pas actuellement dans le produit mais reviendrait pour la bonne mise à jour. Les réseaux sociaux servent une portée au-delà des utilisatrices existantes, avec presque aucun ciblage.

Canal	Idéal pour	Faiblesse
Changelog / flux	Le registre permanent ; lectrices à leur propre rythme	Passif ; inutile pour qui ne vérifie jamais
Avis in-app	Utilisatrices déjà présentes, qui agiraient aujourd'hui	N'atteint personne d'actuellement déconnecté
Email	Utilisatrices inactives qui reviendraient pour cela	Facile à enterrer sous d'autres emails ; besoin d'un vrai objet
Réseaux sociaux	Portée au-delà des utilisatrices actuelles	Presque aucun ciblage ; durée de vie courte

Aucun des quatre ne suffit seul. Le changelog est le seul document qui devrait porter chaque release quelle que soit sa taille, parce que c'est le registre vers lequel tout le reste renvoie ; les trois autres sont une amplification ajoutée par-dessus, choisie selon l'ampleur réelle de la fonctionnalité.

Que devrait dire l'annonce en premier ?

Le résultat, pas le mécanisme. « Nous avons ajouté une couche de cache à l'endpoint des rapports » décrit ce que l'équipe a construit. « Les rapports se chargent désormais en moins d'une seconde » décrit ce qui a changé pour la lectrice, et c'est la phrase qui obtient le clic, parce qu'elle répond à « qu'est-ce que ça m'apporte » dans la première proposition plutôt que la troisième. Le mécanisme appartient à l'entrée de changelog ou à la page de détail, pas au titre.

Du concret avant des adjectifs. « Une expérience de rapports plus rapide et plus puissante » ne dit rien à la lectrice sur quoi agir ; « les rapports se chargent désormais en moins d'une seconde et peuvent être filtrés par statut » lui dit exactement ce qui a changé et quoi essayer. La seconde version paraît aussi plus crédible, parce qu'une affirmation vague sonne exactement comme sonne un texte marketing quand il n'y a rien de concret à dire.

En quoi diffère-t-elle d'un email de mise à jour produit ?

Elles se recoupent sans être identiques. Email de mise à jour produit couvre le canal email spécifiquement, y compris la cadence, les objets, et quand un digest bat un envoi ponctuel. Une annonce de nouvelle fonctionnalité est l'événement sous-jacent ; l'email est l'un des quatre canaux ci-dessus qui pourrait la porter, choisi quand la fonctionnalité est assez grande pour justifier un envoi dédié plutôt que de voyager dans le prochain digest. Une petite fonctionnalité mérite une entrée de changelog et peut-être un avis in-app. Une fonctionnalité importante mérite les quatre canaux, coordonnés dans le temps.

Comment atteindre les personnes précises qui l'ont demandée ?

C'est l'annonce au meilleur rapport effort/impact, et presque toutes les équipes la sautent. Si dix clientes ont demandé une fonctionnalité par son nom, ces dix personnes méritent une note directe et personnelle au moment où elle sort, indépendamment de toute annonce plus large qui part par ailleurs. Boucler la boucle de feedback avec le client couvre le mécanisme en entier ; le résumé ici est que cela ne fonctionne que si la demande d'origine est restée liée à la demandeuse, ce qui relève plus d'un problème de suivi que d'un problème d'annonce. Chez changeloop, quand un retour via le widget est devenu une issue GitHub et que la pull request mergée la ferme (fixes #142), approuver l'entrée de changelog poste une seule fois le commentaire « Shipped — » sur cette issue, qui renvoie vers l'entrée en direct, et la personne qui a envoyé le retour voit l'entrée livrée dans le widget. Personne n'a à se rappeler de le lui dire. Les issues créées à la main, et les dépôts GitLab ou Bitbucket, ne reçoivent pas le commentaire.</p> <h2>Comment écrire l'entrée elle-même ?</h2> <p>La même discipline que toute autre entrée de notes de version : commencer par ce que la lectrice peut désormais faire, poursuivre avec la configuration nécessaire, sauter la justification interne. <a href="https://changeloop.dev/blog/fr/how-to-write-release-notes/">Comment rédiger des notes de version</a> couvre la méthode complète ; une annonce de nouvelle fonctionnalité est le cas aux enjeux les plus élevés, parce que c'est l'entrée la plus susceptible d'être capturée en screenshot, transférée, et lue par quelqu'un qui n'a jamais vu le changelog du produit.</p> <h2>Quand ne faut-il pas annoncer largement ?</h2> <p>Quand la fonctionnalité est encore en déploiement vers un sous-ensemble de comptes, qu'il s'agit vraiment d'une bêta, ou qu'elle est tarifée ou verrouillée de telle façon que neuf lectrices sur dix d'une annonce large ne pourraient pas encore l'utiliser. Une annonce large pour une fonctionnalité que neuf lectrices sur dix ne peuvent pas utiliser se lit comme un appât, et grille la confiance dans la prochaine annonce plus qu'elle ne crée d'enthousiasme dans celle-ci. La solution n'est pas le silence, c'est la portée : informer directement les comptes éligibles et retenir les canaux larges jusqu'à ce que la disponibilité rattrape l'annonce.</p> <h2>FAQ</h2> <p><strong>Chaque nouvelle fonctionnalité mérite-t-elle sa propre annonce ?</strong> Chacune mérite une entrée de changelog. Seules celles assez significatives pour changer la façon dont quelqu'un utilise le produit, ou explicitement demandées par leur nom, méritent les canaux plus larges comme l'email ou les réseaux sociaux.</p> <p><strong>Quel est le meilleur canal pour une petite fonctionnalité ?</strong> Le changelog seul, plus un avis in-app si la fonctionnalité est découvrable dans un flux où l'utilisatrice se trouve déjà. L'email et les réseaux sociaux valent la peine pour des fonctionnalités qui justifient de demander de l'attention.</p> <p><strong>Comment annoncer une fonctionnalité aux personnes qui l'ont spécifiquement demandée ?</strong> Garder la demande liée à la demandeuse dès son enregistrement, puis notifier individuellement à la sortie, séparément de toute annonce plus large. Une étiquette de statut partagée que la demandeuse peut vérifier elle-même réduit aussi le nombre de messages individuels nécessaires en premier lieu.</p> <p><strong>Une annonce de fonctionnalité a-t-elle besoin d'un screenshot ?</strong> Pour tout ce qui est visuel, oui ; une fonctionnalité décrite mais non vue est sautée bien plus souvent qu'une dont les lectrices peuvent voir un aperçu. Pour une API ou une capacité backend, un court exemple de code fait le même travail qu'un screenshot pour un changement d'interface.</p> </article> <article> <h1>Prioriser les demandes de fonctionnalités qui s'accumulent</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Suivre les demandes de fonctionnalités résout où elles vivent. Ça ne résout pas laquelle sort en premier, et cette deuxième question est celle sur laquelle les équipes restent vraiment coincées. Un backlog de trois cents demandes, regroupées et étiquetées, a quand même besoin d'une règle de décision, parce que "construis la chose la plus demandée" ne fonctionne que jusqu'à ce que deux demandes soient proches et qu'une troisième ait une défenseuse bruyante, ce qui arrive la plupart des semaines. Les cadres ci-dessous ne sont pas des réponses concurrentes à la même question. Chacun convient à un type différent de demande, et en utiliser un seul pour toutes est généralement la vraie erreur.</p> <h2>Qu'est-ce qui rend prioriser les demandes de fonctionnalités différent de prioriser une roadmap ?</h2> <p>Une décision de roadmap part de la stratégie et demande quoi construire. Une décision sur une demande de fonctionnalité part d'une demande qui existe déjà et se demande s'il faut agir dessus, et les deux tirent dans des directions différentes assez souvent pour qu'une demande ait une forte demande et reste quand même mauvaise à construire, ou ait une faible demande et vaille quand même la peine parce qu'elle débloque un compte stratégique. Traiter chaque demande comme un vote de roadmap saute cette vérification.</p> <table> <thead> <tr> <th>Cadre</th> <th>Ce qu'il pèse</th> <th>Où il se casse</th> </tr> </thead> <tbody><tr> <td>Compte brut de demandes</td> <td>Combien de gens ont demandé</td> <td>Récompense les noms accrocheurs plutôt que la vraie demande</td> </tr> <tr> <td>RICE</td> <td>Portée, impact, confiance, effort</td> <td>Nécessite des estimations que personne n'a pour une demande fraîche</td> </tr> <tr> <td>Pondéré par le revenu</td> <td>Qui a demandé, selon la valeur du compte</td> <td>Ignore les demandes de comptes qui ne valent pas encore grand-chose</td> </tr> <tr> <td>Votes publics</td> <td>Signal visible, faible effort</td> <td>N'atteint que les utilisateurs qui savent déjà où regarder</td> </tr> </tbody></table> <h2>Qu'est-ce que RICE, et ça marche pour les demandes de fonctionnalités ?</h2> <p><a href="https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/">RICE</a> note une idée sur la portée, l'impact, la confiance et l'effort, puis divise les trois premiers par le quatrième pour obtenir un chiffre comparable. C'était conçu pour des idées de roadmap auxquelles une équipe croit déjà, où la partie difficile est de comparer des paris différents entre eux. Les demandes de fonctionnalités arrivent déjà avec un chiffre de portée, le compte de gens qui ont demandé, ce qui est plus concret que la portée qu'a habituellement une idée de roadmap toute fraîche. Là où RICE est mis sous tension par une demande, c'est la confiance et l'impact : une équipe peut être sûre qu'une demande est réelle et n'avoir quand même aucune base pour savoir combien elle bougera une métrique, parce que "l'impact" pour une demande qui a déjà un nom et une trace d'utilisateurs réels est un type d'estimation différent de l'impact pour une idée que personne en dehors de la salle n'a encore vue.</p> <p>Utilise RICE pour les demandes sérieusement envisagées et pas encore tranchées. Ne l'applique pas à chaque demande entrante ; l'effort de notation ne se justifie que sur celles assez proches pour avoir besoin d'un départage.</p> <h2>Faut-il pondérer par le revenu, ou par qui a demandé ?</h2> <p>Par qui a demandé, mais pas seulement par le revenu. Un compte proche du renouvellement, un compte qui a déjà fait une escalade, et un compte dont la demande débloque une affaire en cours portent une urgence qu'un chiffre de revenu plat ne capture pas à lui seul, et une demande venant d'un essai gratuit peut quand même compter si elle bloque une décision qui devient bientôt du revenu. La pondération par revenu est la plus facile à calculer de toutes celles-ci, et pour cette raison même la plus facile à surestimer : elle retire correctement le bruit des comptes sans véritable enjeu, et elle peut tout aussi facilement déclasser une demande qui amènerait un compte bien plus grand encore dans le pipeline.</p> <h2>Quel rôle jouent vraiment les votes ?</h2> <p>Un signal bon marché et continu pour des demandes qui existent déjà, et une mauvaise façon de découvrir quelles demandes devraient exister en premier lieu. Un compte de votes n'atteint que les utilisateurs qui ont déjà trouvé la demande et jugé qu'elle méritait un clic, ce qui veut dire que le total des votes d'une roadmap publique reflète autant la visibilité que la demande : une ancienne demande près du haut de la liste continue d'accumuler des votes en partie parce qu'elle est facile à trouver, et une demande plus récente et tout aussi réelle part de zéro. L'article sur la <a href="https://changeloop.dev/blog/fr/public-roadmap/">roadmap publique</a> plaide pour laisser complètement les votes hors de la roadmap. Traite les votes comme un signal qui a besoin d'être regroupé et pondéré par récence, pas comme un classement à construire dans l'ordre. <a href="https://changeloop.dev/blog/fr/feedback-signal-quality/">Tickets support vs. demandes</a> couvre l'autre angle mort des comptes de votes : un vrai manque peut générer presque aucun vote si les utilisatrices qui y sont confrontées ne trouvent jamais le tableau, tout en apparaissant bruyamment dans le support.</p> <h2>Quand la cliente la plus bruyante gagne-t-elle, et est-ce un problème ?</h2> <p>Parfois, et ce n'est un problème que si personne ne le remarque. Une cliente qui fait souvent des escalades, écrit des tickets détaillés ou a une ligne directe avec quelqu'un de l'équipe verra ses demandes examinées plus vite qu'une cliente plus discrète avec une demande tout aussi valable, et un processus de priorisation qui ne le vérifie jamais favorisera systématiquement qui insiste le plus, pas qui a le dossier le plus solide. Les clientes bruyantes ne sont pas le problème à corriger ; leurs demandes sont souvent réellement importantes. La correction est une habitude : passer en revue le backlog par source périodiquement et vérifier si la même poignée de comptes explique la majorité de ce qui a été livré récemment, et se demander si ça correspond à où se trouve vraiment la demande.</p> <h2>Comment transformer une décision de priorisation en réponse ?</h2> <p>Chaque décision ici produit des gagnantes et des perdantes, et les deux méritent une réponse qui nomme le raisonnement réel, pas juste un changement de statut sans explication. <a href="https://changeloop.dev/blog/fr/declining-feature-requests/">Comment refuser une demande de fonctionnalité</a> couvre quoi dire à une demande qui a perdu, d'une façon qui garde la relation intacte plutôt que de sonner comme un refus générique. Le travail de regroupement et d'étiquetage qui rend tout ça possible en premier lieu est couvert dans <a href="https://changeloop.dev/blog/fr/feature-request-tracking/">suivi des demandes de fonctionnalités</a> ; la priorisation ne fonctionne que sur des demandes déjà enregistrées et regroupées assez bien pour être comparées.</p> <h2>FAQ</h2> <p><strong>Quel est le meilleur cadre pour prioriser les demandes de fonctionnalités ?</strong> Aucun seul. Utilise les comptes bruts pour trouver le signal le plus bruyant, RICE pour comparer une courte liste de candidates sérieuses, et une vérification du revenu ou du compte pour repérer les cas où une demande silencieuse d'un compte stratégique pèse plus qu'un groupe plus bruyant mais moins important.</p> <p><strong>Les demandes de fonctionnalités devraient-elles être priorisées comme les idées de roadmap ?</strong> Non. Les idées de roadmap partent de la stratégie ; les demandes de fonctionnalités partent d'une demande qui existe déjà. Les noter ensemble fait qu'un pari stratégique bien argumenté mais avec peu de demande existante perd constamment face à une demande qui a simplement plus de gens qui l'ont formulée.</p> <p><strong>Les votes sur une roadmap publique reflètent-ils fidèlement la demande ?</strong> Seulement parmi les gens qui ont déjà trouvé la demande. Les demandes plus anciennes et plus visibles accumulent des votes plus vite, indépendamment de la demande réelle derrière une plus récente, donc traite les totaux de votes comme un signal, regroupé et pondéré par récence, pas comme un classement à construire dans l'ordre.</p> <p><strong>À quelle fréquence les priorités des demandes de fonctionnalités devraient-elles être réévaluées ?</strong> Selon un cycle fixe, pas seulement quand quelqu'un fait une escalade. Une passe mensuelle ou trimestrielle qui regroupe les demandes et revérifie la pondération détecte les dérives, comme une poignée de comptes qui domine ce qui est livré, qu'un processus purement réactif ne fait jamais apparaître de lui-même.</p> </article> <article> <h1>Release notes enterprise : ce qui change pour un compte</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Un produit SaaS public envoie les mêmes release notes à tout le monde, parce que tout le monde est sur la même version. Une cliente enterprise sur une version épinglée, une instance dédiée, ou un sous-ensemble du produit avec des feature flags brise cette hypothèse : les release notes qui décrivent ce qui a changé pour elle ne sont pas les mêmes que sur votre blog public, et envoyer les publiques quand même la confond soit avec des changements qu'elle n'a pas encore, soit, pire, lui parle d'une fonctionnalité que l'équipe de compte d'une autre cliente enterprise vous a explicitement demandé de garder secrète encore un mois pour la sienne. <a href="https://changeloop.dev/blog/fr/release-notes-best-practices/">Bonnes pratiques pour les release notes</a> couvre l'artisanat général ; ceci concerne l'écriture de release notes enterprise pour le problème de calibrage qui n'apparaît que lorsque vous avez des clientes qui ne sont pas toutes sur le même build.</p> <h2>Pourquoi une cliente enterprise ne peut-elle pas simplement lire le changelog public ?</h2> <p>Parce qu'il décrit une version qu'elle n'exécute peut-être pas encore, des fonctionnalités auxquelles elle n'a peut-être pas accès, et un calendrier qui ne correspond pas au sien. Une cliente épinglée à un cycle de release trimestriel qui lit une fonctionnalité sortie pour le niveau public la semaine dernière n'a aucun moyen de savoir, à partir du seul changelog public, si cette fonctionnalité lui arrivera la semaine prochaine ou le trimestre prochain. Le changelog public répond à "qu'est-ce qui a changé dans le produit" ; la vraie question d'une cliente enterprise est "qu'est-ce qui a changé dans la version que j'exécute, et quand est-ce que j'obtiens le reste", ce que le changelog public n'a jamais été écrit pour répondre.</p> <h2>De quoi une release note privée a-t-elle besoin qu'une publique n'a pas ?</h2> <p>Un identifiant de version ou d'environnement contre lequel la cliente peut vraiment vérifier, et une déclaration explicite de ce qui ne lui est pas encore arrivé. "Cette version inclut les améliorations d'export en masse de notre release publique 4.3, mais pas le nouveau modèle de permissions, qui arrive dans votre prochaine mise à jour planifiée" dit à une administratrice enterprise exactement où en est son instance par rapport au produit dans son ensemble. Une release note publique n'a jamais besoin de ce cadrage parce qu'il n'y a qu'une seule instance par rapport à laquelle être relative ; une privée est dénuée de sens sans lui.</p> <table> <thead> <tr> <th>Release notes publiques</th> <th>Release notes privées (enterprise)</th> </tr> </thead> <tbody><tr> <td>Une version, une audience</td> <td>Plusieurs versions, audiences segmentées</td> </tr> <tr> <td>Suppose que la lectrice a chaque fonctionnalité décrite</td> <td>Doit énoncer ce que la lectrice a et n'a pas</td> </tr> <tr> <td>Calée sur la release publique</td> <td>Calée sur la propre fenêtre de mise à jour de la cliente</td> </tr> <tr> <td>Peut être rendue entièrement publique immédiatement</td> <td>Peut devoir retenir des éléments que d'autres clientes n'ont pas encore</td> </tr> </tbody></table> <h2>Est-il jamais acceptable de simplement retarder l'envoi des release notes publiques aux clientes enterprise plutôt que d'en écrire des séparées ?</h2> <p>Seulement si sa version correspond vraiment à la publique à ce moment-là, ce qui est plus rare qu'il n'y paraît dès que vous avez plus de quelques comptes enterprise sur des rythmes différents. Retarder les notes publiques fonctionne comme solution temporaire pour une cliente qui a une version de retard et est sur le point de rattraper ; cela s'effondre au moment où deux clientes enterprise sont sur des versions différentes l'une de l'autre, parce qu'il n'y a alors plus une seule "les notes" à retarder, seulement une matrice de ce que chacune a. À ce stade, calibrer les notes par compte, même si ce n'est qu'une vue filtrée des mêmes entrées sous-jacentes, cesse d'être optionnel.</p> <pre><code>Notes publiques, envoyées à un compte enterprise qui n'a pas encore la fonctionnalité : "New: Bulk export now supports custom column ordering." (Confus : l'admin l'essaie et elle n'est pas là.) Notes enterprise calibrées pour le même compte : "Available in your next update (scheduled for 2026-10-15): bulk export with custom column ordering. Not yet available on your current version (3.8)." </code></pre> <h2>Qui dans l'organisation de la cliente lit vraiment ceci, et cela change-t-il l'écriture ?</h2> <p>Habituellement une administratrice IT ou une contact customer success plutôt qu'une utilisatrice finale, et cela change ce qui compte comme utile. Une utilisatrice finale veut savoir ce qui a l'air différent sur son écran ; une administratrice enterprise veut savoir ce qui a changé dans les permissions, la gestion des données, la configuration SSO, ou quoi que ce soit qui affecte la façon dont elle gère le déploiement pour ses propres utilisatrices, parce que c'est elle qui répondra aux questions internes. Une release note privée qui se lit comme un changelog grand public, tout en boutons neufs et brillants et sans détail opérationnel, force l'administratrice à creuser pour l'information dont elle avait vraiment besoin.</p> <h2>Comment cela interagit-il avec une roadmap publique ou un changelog public qui liste déjà la même fonctionnalité ?</h2> <p>Avec prudence, parce qu'une cliente qui lit les deux remarquera toute incohérence. Si votre changelog public a déjà annoncé une fonctionnalité qu'un compte enterprise spécifique n'a pas encore, sa release note privée doit reconnaître cet écart plutôt que faire comme si l'entrée publique n'existait pas ; une administratrice qui a vu l'annonce publique et reçoit des notes privées qui l'ignorent supposera soit que vous l'avez oubliée, soit que quelque chose est cassé. <a href="https://changeloop.dev/blog/fr/public-roadmap/">Roadmap publique</a> couvre comment garder une roadmap honnête sur ce qui est sorti par rapport à ce qui est planifié ; la version enterprise de cette honnêteté dans les release notes consiste à nommer directement l'écart entre ce qui est public et ce qui est le sien.</p> <h2>Une petite entreprise avec seulement une ou deux clientes enterprise a-t-elle besoin de toute cette structure ?</h2> <p>Pas le système entièrement segmenté, mais la discipline centrale, énoncer clairement sur quelle version se trouve la cliente et ce qu'elle a et n'a pas, compte à n'importe quelle échelle dès que vous avez ne serait-ce qu'une cliente qui n'est pas sur votre build le plus récent. Le mode d'échec que cela évite, une administratrice confuse quant à savoir si une annonce publique s'applique à elle, coûte un ticket de support et un coup à la confiance, que vous ayez deux comptes enterprise ou deux cents.</p> <h2>FAQ</h2> <p><strong>Les release notes privées devraient-elles jamais mentionner des fonctionnalités que d'autres clientes ont déjà mais pas celle-ci ?</strong> Seulement si c'est pertinent pour son propre calendrier, formulé comme "arrive dans votre prochaine mise à jour" plutôt que comme une comparaison à d'autres clientes. Nommer ce qu'une autre cliente spécifique a franchit un territoire qui n'est pas le vôtre à divulguer ; nommer ce qui arrive spécifiquement à cette cliente est exactement l'information dont elle a besoin.</p> <p><strong>Les mêmes entrées de changelog sous-jacentes peuvent-elles alimenter à la fois les release notes publiques et privées ?</strong> Oui, et c'est habituellement l'approche la plus maintenable : étiquetez les entrées avec les versions ou niveaux auxquels elles s'appliquent, puis filtrez par audience au moment de la publication plutôt que d'écrire deux documents entièrement séparés qui divergent inévitablement.</p> <p><strong>Que faire si une cliente enterprise demande explicitement d'être sur les release notes publiques plutôt que sur un flux privé ?</strong> Respectez-le, mais confirmez qu'elle comprend que les notes publiques supposent la version publique, et signalez vous-même par écrit l'écart si sa version diverge de ce qui est décrit. Cette confirmation écrite est ce qui vous protège plus tard si elle agit sur des notes publiques qui ne s'appliquaient pas réellement à son build.</p> <p><strong>Combien de temps à l'avance une cliente enterprise devrait-elle être informée d'une fonctionnalité à laquelle elle aura accès dans la prochaine release ?</strong> Dès que la date est confirmée, pas seulement au moment de la release, parce que les administratrices enterprise doivent souvent planifier leur propre communication interne ou formation autour d'une fonctionnalité qui arrive, et une notification le jour même ne leur laisse aucune marge pour cela.</p> </article> <article> <h1>Semantic versioning et votre changelog</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>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 <code>2.4.1</code> à <code>2.5.0</code> signifie : nouvelle capacité, rien ne casse. Passer de <code>2.5.0</code> à <code>3.0.0</code> 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.</p> <h2>Que promet vraiment chaque chiffre d'une version ?</h2> <p>Le <a href="https://semver.org/">semantic versioning</a> définit trois chiffres, <code>MAJOR.MINOR.PATCH</code>, 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.</p> <table> <thead> <tr> <th>Saut</th> <th>Signification</th> <th>L'entrée devrait se lire comme</th> </tr> </thead> <tbody><tr> <td>MAJOR (<code>1.x.x</code> -> <code>2.0.0</code>)</td> <td>Un changement incompatible</td> <td>« Une action est requise avant de mettre à jour »</td> </tr> <tr> <td>MINOR (<code>1.2.x</code> -> <code>1.3.0</code>)</td> <td>Nouvelle capacité compatible</td> <td>« Disponible dès maintenant, rien d'autre ne change »</td> </tr> <tr> <td>PATCH (<code>1.2.3</code> -> <code>1.2.4</code>)</td> <td>Un correctif compatible</td> <td>« Se comporte désormais comme documenté »</td> </tr> </tbody></table> <p>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é.</p> <h2>Qu'est-ce qui compte comme incompatible pour le versionnage ?</h2> <p>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. <a href="https://changeloop.dev/blog/fr/breaking-changes/">Qu'est-ce qu'un changement incompatible, et comment le livrer</a> 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.</p> <h2>Comment une entrée de changelog devrait-elle correspondre à un saut de version ?</h2> <p>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.</p> <pre><code>## 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. </code></pre> <p>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.</p> <h2>La règle du changement incompatible s'applique-t-elle de la même façon avant la 1.0.0 ?</h2> <p>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, <code>0.y.z</code>, 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 <code>0.4.0</code> à <code>0.5.0</code> 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 <code>1.0.0</code>. 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.</p> <h2>Et si votre produit ne livre pas de versions discrètes ?</h2> <p>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.</p> <h2>Comment cela s'applique-t-il spécifiquement à un changelog d'API ?</h2> <p>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. <a href="https://changeloop.dev/blog/fr/api-changelog/">Changelog d'API : quoi publier et qui le lit</a> 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 <code>v1</code> et <code>v2</code> 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.</p> <h2>Que dit Keep a Changelog sur le versionnage ?</h2> <p>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. <a href="https://changeloop.dev/blog/fr/keep-a-changelog-implemented/">Keep a Changelog, en pratique</a> 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.</p> <h2>FAQ</h2> <p><strong>Chaque entrée de changelog a-t-elle besoin d'un numéro de version ?</strong> 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.</p> <p><strong>Quelle est la différence entre un saut MAJOR et une entrée de changement incompatible ?</strong> 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é.</p> <p><strong>Une release PATCH peut-elle être incompatible ?</strong> 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 <a href="https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version">FAQ SemVer</a> 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.</p> <p><strong>Les changements purement internes ont-ils besoin d'un saut de version ?</strong> 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.</p> </article> <article> <h1>L'en-tête sunset d'API, et quand l'envoyer</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p><code>Sunset</code> est un en-tête de réponse unique, défini dans la <a href="https://www.rfc-editor.org/rfc/rfc8594">RFC 8594</a>, qui indique à un appelant quand une ressource va cesser de répondre. <a href="https://changeloop.dev/blog/fr/api-deprecation/">Dépréciation d'API</a> couvre le calendrier complet annonce-rappel-brownout-retrait et les avis qui l'accompagnent ; ceci concerne le seul signal lisible par machine dans ce calendrier, ce qu'il dit réellement, et le seul cas où la RFC elle-même dit de ne pas l'envoyer.</p> <h2>Que dit l'en-tête Sunset, et que ne dit-il pas ?</h2> <p>Il porte une seule date HTTP, le moment où la ressource devrait cesser de répondre :</p> <pre><code>Sunset: Sat, 31 Dec 2028 23:59:59 GMT </code></pre> <p>La RFC l'appelle un indice, pas une garantie : elle ne promet pas que la ressource continuera de fonctionner jusqu'à cet horodatage, et elle ne dit rien sur la forme que prendra l'échec ensuite. Les appelants peuvent recevoir un 4xx, une redirection, ou aucune réponse du tout ; l'en-tête ne fait pas de distinction. Un horodatage déjà passé signifie « maintenant, ou n'importe quand » plutôt qu'une erreur dans la valeur. Rien de tout cela n'est imposé par le protocole. Un client qui ne lit jamais l'en-tête se comporte exactement comme avant, et découvre que la ressource a disparu de la même façon qu'il l'aurait découvert de toute façon.</p> <h2>Quand devriez-vous réellement l'envoyer ?</h2> <p>Seulement une fois que la ressource va vraiment cesser de répondre, pas simplement lorsqu'elle n'est plus le choix recommandé. La RFC est explicite : la dépréciation se déroule en deux étapes, et le champ d'en-tête Sunset n'appartient qu'à la seconde : l'API reste pleinement opérationnelle pendant la première étape, l'annonce qu'une version n'est plus préférée, et le champ d'en-tête ne s'y applique pas. Il s'applique une fois que la version est réellement programmée pour cesser de répondre.</p> <p>Cela correspond directement au calendrier de dépréciation : l'en-tête <code>Deprecation</code> part dès le premier jour, à l'étape d'annonce ; <code>Sunset</code> décrit la date à laquelle l'ancien comportement va réellement s'arrêter, qui est la même date que <a href="https://changeloop.dev/blog/fr/api-deprecation/">le calendrier en quatre étapes</a> appelle le retrait. Envoyer <code>Sunset</code> dès le premier jour n'est pas une erreur, puisque la date est déjà fixée à ce moment-là, mais l'envoyer sans avoir aussi annoncé une dépréciation, ou le définir pour une version que vous ne vous êtes pas réellement engagé à retirer, dit aux appelants quelque chose que vous n'avez pas encore décidé.</p> <h2>Interagit-il avec le cache ?</h2> <p>Non, et la RFC le dit directement : <code>Sunset</code> et le cache HTTP résolvent des problèmes sans rapport et devraient être lus comme complémentaires, pas comme se recouvrant. Les en-têtes de cache disent quand une copie en cache peut être réutilisée sans risque ; <code>Sunset</code> ne dit rien sur l'état actuel de la ressource, seulement que la ressource elle-même va cesser d'exister. Une réponse peut être entièrement cacheable jusqu'au moment précis où elle atteint son sunset. N'utilisez pas l'un pour approximer l'autre, et ne supposez pas qu'un <code>max-age</code> long annule une date de sunset qui approche, ni l'inverse.</p> <h2>Un seul en-tête peut-il faire disparaître plusieurs endpoints ?</h2> <p>L'en-tête s'applique à la ressource qui l'a renvoyé, mais la RFC permet à un service de documenter une portée plus large : une date Sunset sur la ressource d'accueil d'une API peut être définie pour signifier que l'API entière disparaît, pas seulement cette URL. Le piège, c'est que ça ne fonctionne que pour les appelants qui connaissent déjà votre règle de portée. Un appelant qui lit l'en-tête au pied de la lettre voit un sunset sur la seule ressource qu'il a demandée et rien d'autre, donc une portée plus large doit être écrite quelque part où un appelant peut la trouver, pas seulement sous-entendue.</p> <h2>Qu'est-ce qui devrait accompagner l'en-tête ?</h2> <p>Un lien vers l'endroit où le retrait est expliqué. La RFC 8594 enregistre sa propre relation de lien <code>sunset</code> exactement pour ça : pointer vers une ressource qui décrit la politique de retrait, la date à venir, ou comment migrer, séparément de l'horodatage brut de l'en-tête.</p> <pre><code>HTTP/1.1 200 OK Sunset: Sat, 31 Dec 2028 23:59:59 GMT Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Faire pointer ce lien vers vos propres <a href="https://changeloop.dev/changelog-examples">exemples de changelog</a> ou une page de migration dédiée transforme un en-tête que le code client de presque personne n'inspecte en quelque chose qu'un humain qui va chercher trouve immédiatement. Combinez-le avec la relation <code>successor-version</code> des <a href="https://changeloop.dev/blog/fr/api-deprecation/#which-headers-should-a-deprecated-endpoint-send">en-têtes de dépréciation</a> et un appelant obtient à la fois où aller et ce qui remplace celui-ci, depuis la réponse seule.</p> <h2>À quoi ça ressemble de bout en bout ?</h2> <p>Disons que <code>v1</code> disparaît le 1er mars 2027. L'annonce de dépréciation le premier jour ajoute <code>Deprecation</code> et <code>Link: rel="successor-version"</code> à chaque réponse <code>v1</code>, selon <a href="https://changeloop.dev/blog/fr/api-deprecation/">les en-têtes de dépréciation</a>, mais retient <code>Sunset</code> jusqu'à ce que la date de retrait soit vraiment fixée plutôt qu'un espace réservé. Une fois que c'est le cas, chaque réponse <code>v1</code> porte :</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Le gateway ou le monitoring d'un appelant peut alerter sur chaque en-tête indépendamment : <code>Deprecation</code> dit qu'une version plus récente existe, <code>Sunset</code> dit que celle-ci a une horloge dessus. Aucun des deux en-têtes n'a besoin de changer avant le 1er mars ; ce qui change, c'est la réponse elle-même, le jour J, et pendant les éventuelles fenêtres de brownout planifiées avant.</p> <h2>Un brownout change-t-il ce que dit l'en-tête ?</h2> <p>La valeur de l'en-tête elle-même n'a pas besoin de bouger pour un brownout planifié : la date de sunset reste la date de sunset, que la ressource échoue par intermittence avant ou non. Ce qui change, c'est la réponse, pas l'en-tête. Planifier de courtes fenêtres de <code>410 Gone</code> dans les semaines précédant la date annoncée, comme le décrit <a href="https://changeloop.dev/blog/fr/api-deprecation/">Dépréciation d'API</a>, est ce qui transforme le premier contact d'un appelant avec l'échec en répétition plutôt qu'en réalité le jour où la date de l'en-tête arrive.</p> <h2>FAQ</h2> <p><strong>Des clients HTTP ou outils réels lisent-ils vraiment l'en-tête Sunset ?</strong> Rarement, côté client. Sa valeur est surtout pour qui exploite l'infrastructure entre vous et l'appelant : une passerelle API ou un outil de monitoring que vous configurez pour surveiller l'en-tête peut alerter votre propre équipe, ou celle d'une partenaire, bien avant que le code de l'appelant ne le remarque jamais. Traitez-le comme un signal autour duquel vous construisez de l'outillage, pas comme un signal dont vous pouvez supposer que l'autre côté dispose déjà.</p> <p><strong><code>Sunset</code> est-il la même chose que <code>Cache-Control: max-age</code> ?</strong> Non. <code>max-age</code> concerne la durée pendant laquelle une copie en cache reste valide ; <code>Sunset</code> concerne le moment où la ressource cesse d'exister complètement. Une réponse peut porter un <code>max-age</code> court et une date <code>Sunset</code> à des années de distance, ou l'inverse, et aucun des deux en-têtes ne contraint l'autre.</p> <p><strong>Puis-je envoyer Sunset pour un seul champ qui disparaît, pas tout l'endpoint ?</strong> Non, l'en-tête est limité à la ressource, c'est-à-dire l'URL, pas à un champ à l'intérieur du corps de sa réponse. Pour un champ, un paramètre ou une valeur d'énumération qui disparaît alors que l'endpoint lui-même reste actif, utilisez plutôt l'en-tête <code>Deprecation</code> et une entrée de changelog ; <a href="https://changeloop.dev/blog/fr/api-deprecation/">Dépréciation d'API</a> couvre l'annonce de ce type de changement précisément.</p> <p><strong>Et si la date de sunset doit bouger ?</strong> Mettez à jour la valeur de l'en-tête et dites-le dans l'entrée de changelog qui l'avait annoncée en premier lieu ; changer silencieusement une date publiée est la façon dont un appelant décide qu'aucune de vos dates n'est réelle. La RFC présente la valeur comme un indice précisément parce que les dates bougent parfois, mais une date déplacée sans explication vous coûte la suivante aussi.</p> </article> <article> <h1>Changelogs de webhooks : le changement cassant non demandé</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Un changelog d'API REST existe parce qu'un appelant peut choisir de rejeter une réponse qu'il ne comprend pas, ou au moins enregistrer une erreur assez bruyante pour que quelqu'un le remarque. Un récepteur de webhook fait rarement l'un ou l'autre. Il reçoit un POST, lit les champs qu'il attend, et si un champ a bougé, changé de type ou disparu, l'endpoint plante soit silencieusement dans une tâche en arrière-plan que personne ne surveille, soit, pire, continue de tourner avec une valeur fausse qu'il n'a jamais validée. <a href="https://changeloop.dev/blog/fr/breaking-changes/">Qu'est-ce qu'un changement cassant</a> couvre la définition générale ; un payload de webhook a besoin de sa propre réponse, parce que le mode d'échec est différent de celui d'un endpoint que quelqu'un appelle exprès.</p> <h2>Pourquoi un changement de payload de webhook casse-t-il différemment d'un changement de réponse d'API ?</h2> <p>Parce que le sens de la requête est inversé. Un appelant REST initie l'appel et peut ajouter un en-tête de version, réessayer sur un 4xx, ou lire un avis de dépréciation dans la réponse. Un récepteur de webhook n'a initié aucune de ces choses : votre serveur a décidé d'envoyer, a décidé quand, et a décidé de la forme du corps. Le seul levier du récepteur est la validation qu'il a écrite quand l'intégration a été construite, et la plupart des intégrations sont construites une fois, fonctionnent, et ne sont jamais revues jusqu'à ce qu'elles cassent. Cette asymétrie est toute la raison pour laquelle un changement de payload de webhook mérite plus de prudence que le même changement dans un corps de réponse qu'un appelant a activement demandé.</p> <h2>Qu'est-ce qui compte vraiment comme changement cassant dans un payload de webhook ?</h2> <table> <thead> <tr> <th>Changement</th> <th>Cassant pour la plupart des récepteurs</th> </tr> </thead> <tbody><tr> <td>Ajouter un nouveau champ</td> <td>Non, si les récepteurs ignorent les champs inconnus (vérifiez cette hypothèse, ne la supposez pas)</td> </tr> <tr> <td>Supprimer un champ</td> <td>Oui, si quelque chose le lit</td> </tr> <tr> <td>Renommer un champ</td> <td>Oui, fonctionnellement identique à supprimer l'ancien</td> </tr> <tr> <td>Changer le type d'un champ (chaîne vers objet)</td> <td>Oui, presque toujours</td> </tr> <tr> <td>Réordonner les champs dans le corps JSON</td> <td>Non, pour tout récepteur qui parse par clé, ce qui devrait être tous</td> </tr> <tr> <td>Changer le nom ou le type d'événement</td> <td>Oui, si les récepteurs filtrent ou routent dessus</td> </tr> </tbody></table> <p>La ligne « ajouter un champ est sûr » est celle sur laquelle les équipes s'appuient le plus et celle qu'il vaut le mieux vérifier plutôt que supposer. Un parser JSON permissif ignore les champs inconnus par défaut, mais un récepteur qui désérialise dans un schéma strict, plusieurs langages typés le font sans configuration supplémentaire, peut rejeter tout le payload dès qu'un champ inattendu apparaît. Ajouter un champ n'est sûr pour votre webhook que si vous savez comment les récepteurs parsent, pas parce que JSON en soi est permissif.</p> <h2>Comment versionner un payload de webhook ?</h2> <p>À peu près comme pour une réponse d'API, avec une nuance : le récepteur n'envoie jamais de requête, il ne peut donc pas demander de version, et c'est l'émetteur qui doit l'indiquer. Elle peut aller dans le corps ou dans un en-tête de requête de la livraison elle-même ; <a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">les livraisons de GitHub</a> portent <code>X-GitHub-Event</code> et <code>X-GitHub-Hook-ID</code>, et la <a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md">spécification Standard Webhooks</a> place ses métadonnées dans des en-têtes <code>webhook-*</code>. Un champ de version dans le payload (<code>"payload_version": 2</code>) est l'option la moins chère et fonctionne quand les récepteurs sont prêts à brancher dessus. Un type d'événement versionné (<code>invoice.updated</code> devient <code>invoice.updated.v2</code> comme un événement distinct auquel un récepteur s'abonne volontairement) demande plus de travail à construire mais signifie que l'ancienne forme continue d'arriver à qui n'a jamais migré, ce qui compte plus ici que pour un endpoint REST parce que vous ne pouvez pas appeler chaque récepteur pour lui dire de mettre à jour. Un réglage par abonnement, choisi à l'enregistrement de l'endpoint du webhook, anticipe la décision au lieu de brancher à chaque livraison, et c'est le bon choix quand vous avez déjà un enregistrement d'abonnement auquel l'attacher.</p> <pre><code>POST /endpoint-recepteur { "event": "invoice.updated", "payload_version": 2, "data": { "invoice_id": "inv_123", "status": "paid" } } </code></pre> <h2>Comment savez-vous même qui écoute ?</h2> <p>Pire que la version équivalente de ce problème dans un changelog d'API, parce qu'un webhook n'a pas de journal de requêtes entrantes de votre côté qui nomme l'appelant ; vous n'avez que votre propre journal de livraison sortante, qui vous dit qu'un endpoint a reçu un 200, pas ce qu'il a fait du corps. Suivez au minimum deux choses : chaque endpoint enregistré avec une responsable, la même discipline que <a href="https://changeloop.dev/blog/fr/internal-api-changelog/">les changelogs d'API interne</a> recommandent pour les consommateurs internes, et votre taux d'échec de livraison par endpoint après un changement de payload. Un pic de réponses 4xx ou 5xx d'un endpoint juste après un changement est ce qui se rapproche le plus d'une stack trace que vous obtiendrez, et c'est souvent le seul signal qu'un récepteur a cassé, parce que l'équipe qui l'exploite peut mettre des jours à le remarquer.</p> <h2>Un changelog de webhooks devrait-il être séparé du changelog d'API ?</h2> <p>Une section séparée sur la même page, pas une publication séparée. <a href="https://changeloop.dev/blog/fr/api-changelog/">Un changelog d'API</a> établit déjà qui le lit et comment on s'y abonne ; un changement de payload de webhook appartient au même flux, étiqueté avec assez de clarté pour qu'une développeuse côté récepteur qui scanne pour « est-ce que ça affecte mon intégration » puisse le filtrer, parce qu'une consommatrice de webhook n'a souvent aucune autre raison de vérifier un changelog d'API général et ne le trouvera que si quelqu'un l'y renvoie directement.</p> <h2>À quoi devrait ressembler une fenêtre de dépréciation raisonnable pour un payload de webhook ?</h2> <p>Plus longue que la dépréciation REST équivalente, parce que la migration côté récepteur signifie généralement qu'une deuxième équipe, avec qui vous n'avez peut-être pas de contact direct, doit le remarquer, le planifier et le livrer sans urgence propre. Un mois est un minimum raisonnable pour un champ que le récepteur parse probablement encore avec une bibliothèque permissive ; trois mois ou plus sont plus sûrs pour une suppression de champ qu'un schéma strict rejetterait complètement. Envoyez l'ancienne et la nouvelle forme ensemble pendant la fenêtre quand c'est faisable (l'ancien champ <code>status</code> et son remplaçant de la version 2 dans le même payload), parce qu'un récepteur qui lit l'ancien champ continue de fonctionner sans toucher à son code, et un qui a déjà migré ignore simplement le champ dont il n'a plus besoin.</p> <h2>FAQ</h2> <p><strong>Les consommateurs de webhooks doivent-ils accuser réception d'un changement de payload avant sa mise en ligne ?</strong> Aucun mécanisme d'accusé de réception n'existe par défaut, et c'est exactement pourquoi la fenêtre de dépréciation compte plus ici que pour une API REST : personne ne confirme être prêt, donc la fenêtre doit être assez longue pour que la plupart des récepteurs migrent à leur propre rythme avant que l'ancienne forme disparaisse.</p> <p><strong>Est-il jamais sûr d'ajouter des champs inconnus sans préavis ?</strong> Seulement une fois que vous avez vérifié, pas supposé, que vos récepteurs parsent de façon permissive. Une entrée de changelog coûte peu et enlève l'incertitude ; ajouter des champs en silence en supposant que « les parsers JSON ignorent les extras » casse tout récepteur avec une désérialisation stricte.</p> <p><strong>Quel est le moyen le plus rapide de détecter un récepteur de webhook cassé après un changement de payload ?</strong> Un taux d'échec de livraison par endpoint, observé dans les heures juste après le changement. Cela ne vous dira pas ce qui a cassé, seulement que quelque chose a cassé, mais c'est le signal le plus précoce et souvent le seul que vous obtiendrez.</p> <p><strong>La logique de retry aide-t-elle les récepteurs à survivre à un changement de payload ?</strong> Non. Un retry renvoie le même nouveau payload ; il ne revient pas à une forme que le récepteur peut parser. Un changement de payload casse un récepteur à la première livraison et à chaque retry suivant de façon identique.</p> </article> <article> <h1>Changelog : définition et exemple d'entrée</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>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.</p> <h2>Qu'est-ce qu'un changelog, exactement ?</h2> <p>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.</p> <p>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. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> 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.</p> <table> <thead> <tr> <th>Document</th> <th>Écrit pour</th> <th>Répond à</th> </tr> </thead> <tbody><tr> <td>Changelog</td> <td>Quiconque utilise le produit</td> <td>Qu'est-ce qui a changé, et quand ?</td> </tr> <tr> <td>Journal de commits</td> <td>L'équipe qui a écrit le code</td> <td>Qu'est-ce qui a été fait, dans quel ordre ?</td> </tr> <tr> <td>Notes de version</td> <td>Utilisatrices décidant de mettre à jour</td> <td>Que puis-je faire maintenant que je ne pouvais pas ?</td> </tr> <tr> <td>Notes de patch</td> <td>Joueuses ou utilisatrices d'un correctif précis</td> <td>Qu'est-ce que cette release a corrigé ?</td> </tr> <tr> <td>Roadmap</td> <td>Quiconque se demande ce qui arrive ensuite</td> <td>Qu'est-ce qui est prévu, et où ça en est ?</td> </tr> </tbody></table> <p>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.</p> <h2>Que contient vraiment une entrée de changelog ?</h2> <p>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.</p> <pre><code>## 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. </code></pre> <p>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.</p> <h2>Qui écrit un changelog, et quand ?</h2> <p>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.</p> <h2>Où un changelog doit-il vivre ?</h2> <p>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.</p> <h2>En quoi diffère-t-il des notes de version ?</h2> <p>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. <a href="https://changeloop.dev/blog/fr/changelog-vs-release-notes/">Changelog vs notes de version</a> 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.</p> <h2>Qu'est-ce qui rend un changelog digne d'être lu ?</h2> <p>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.</p> <p>La discipline de versionnage compte aussi. <a href="https://changeloop.dev/blog/fr/semantic-versioning-changelog/">Semantic versioning et votre changelog</a> 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.</p> <h2>Comment les changelogs sont-ils générés ?</h2> <p>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 <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, et les transforme en entrées sans que personne ne touche à la sortie ; <a href="https://changeloop.dev/blog/fr/conventional-commits-changelog/">des conventional commits au changelog</a> 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.</p> <h2>FAQ</h2> <p><strong>Tout produit a-t-il besoin d'un changelog ?</strong> 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.</p> <p><strong>Qu'est-ce qu'un changelog en termes logiciels ?</strong> 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.</p> <p><strong>Un changelog peut-il être généré automatiquement à partir des commits ?</strong> 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.</p> <p><strong>Un changelog est-il la même chose qu'un historique des versions ?</strong> 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é.</p> </article> <article> <h1>Changelog d'API : quoi publier et qui le lit</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Un changelog d'API est le registre daté de chaque changement qu'un appelant pourrait remarquer, écrit pour ceux qui intègrent l'API plutôt que pour l'équipe qui la livre. Ce public en fait un document différent d'un changelog produit : le lecteur décide si son code fonctionnera encore le mois prochain. La plupart échouent de la même façon, en étant une copie filtrée d'un flux interne de releases, si bien qu'un champ supprimé se retrouve à côté d'une correction de texte avec le même poids, et aucun des deux n'est lu.</p> <h2>Qu'est-ce qu'un changelog d'API ?</h2> <p>C'est le registre public et daté des changements apportés à une interface contre laquelle d'autres ont écrit du code. Le test utile pour savoir si quelque chose y a sa place n'a rien à voir avec l'ampleur du changement en interne. Il demande si un appelant correct, écrit l'an dernier et jamais retouché depuis, pourrait se comporter différemment à cause de lui. Ce test admet certains changements très petits et exclut certains très gros.</p> <p>Tout ce qui suit suppose que l'appelant est extérieur à l'entreprise et effectivement injoignable autrement que via ce document. Quand l'appelant est une autre équipe de la même entreprise, le calcul change assez pour mériter son propre traitement ; <a href="https://changeloop.dev/blog/fr/internal-api-changelog/">changelogs d'API interne</a> couvre ce dont ce public a besoin à la place.</p> <table> <thead> <tr> <th>Document</th> <th>Public</th> <th>Répond à</th> </tr> </thead> <tbody><tr> <td>Changelog d'API</td> <td>Développeurs qui appellent l'API</td> <td>Mon intégration fonctionne-t-elle encore ?</td> </tr> <tr> <td>Notes de version</td> <td>Utilisateurs du produit</td> <td>Que puis-je faire maintenant que je ne pouvais pas ?</td> </tr> <tr> <td>Avis de dépréciation</td> <td>Appelants d'une chose précise</td> <td>Quand cela cessera-t-il de fonctionner ?</td> </tr> <tr> <td>Page de statut</td> <td>Quiconque est touché maintenant</td> <td>Est-ce en panne en ce moment ?</td> </tr> <tr> <td>Guide de migration</td> <td>Appelants qui migrent</td> <td>Comment passer de A à B ?</td> </tr> </tbody></table> <p><a href="https://changeloop.dev/blog/fr/api-migration-guide/">Comment écrire un guide de migration d'API</a> couvre ce dernier document en entier ; en bref, c'est ce vers quoi une entrée de changement incompatible devrait renvoyer plutôt que d'essayer de le remplacer.</p> <p>Les cinq sont des documents séparés avec des cycles de vie séparés. Un avis de dépréciation est une promesse avec une date, et il appartient aussi au changelog, mais une entrée de changelog s'écrit une fois tandis qu'une dépréciation se suit jusqu'à son sunset. Les confondre est la raison pour laquelle les sunsets sont manqués.</p> <h2>Que doit contenir une entrée ?</h2> <p>Six choses, et les trois premières sont celles qui manquent le plus souvent. Le changement, formulé en termes de requête ou de réponse plutôt que du composant interne. S'il casse un appelant correct. Ce que l'appelant doit faire, y compris "rien". La date de prise d'effet. La ou les versions concernées. Un lien vers le guide de migration s'il en existe un.</p> <p>Une entrée qui dit "amélioration de l'endpoint comptes" échoue sur les six. Une entrée qui dit "le champ <code>accounts.type</code> retourne désormais <code>individual</code> là où il retournait <code>personal</code> ; les valeurs existantes restent inchangées pour les comptes créés avant le 2 septembre ; aucune action requise sauf si vous comparez la chaîne" répond aux six en une phrase.</p> <p>Classez les entrées par conséquence, pas par équipe. Trois étiquettes portent presque toute la valeur : breaking, additive et fixed. <a href="https://semver.org/">Semantic Versioning</a> définit déjà précisément les deux premières, et emprunter ses définitions plutôt qu'en inventer d'autres signifie qu'un lecteur qui connaît semver connaît vos étiquettes. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> en propose un jeu plus large si vous le voulez, et sa règle centrale s'applique ici plus fortement que partout ailleurs : le journal est écrit pour des humains, et un déversement de titres de commit n'en est pas un.</p> <h2>En quoi un changelog d'API diffère-t-il des notes de version ?</h2> <p>Les notes de version décrivent ce que le produit peut faire désormais. Un changelog d'API décrit quel est désormais le contrat. Le même travail livré produit souvent une entrée dans les deux, rédigée différemment, car les publics ont besoin de choses différentes : un nouveau format d'export est une fonctionnalité pour un utilisateur et une nouvelle valeur d'enum pour un appelant qui teste ce champ.</p> <p>La conséquence pratique est que les deux ne peuvent pas être le même flux avec un style différent. Un appelant abonné à tout ce que vous livrez finira par se désabonner, et ratera alors le changement cassant. Si vous publiez un flux, filtrez-le ; si vous en publiez deux, resserrez celui de l'API et ne laissez jamais une entrée marketing y entrer. Nous comparons les deux formes côte à côte dans <a href="https://changeloop.dev/blog/fr/changelog-vs-release-notes/">changelog vs notes de version</a>.</p> <h2>Où un changelog d'API devrait-il vivre ?</h2> <p>À côté de la documentation de référence, sur une URL stable, avec chaque entrée adressable individuellement via un fragment ou son propre chemin. Les appelants lient des entrées dans des revues d'incidents et des tickets internes, et une entrée qui ne peut pas être liée finit collée en capture d'écran à la place.</p> <p>Publiez-le aussi en sortie lisible par machine, en plus d'une page. Un flux JSON suivant la <a href="https://www.jsonfeed.org/version/1.1/">spécification JSON Feed</a> ou un <a href="https://www.rssboard.org/rss-specification">flux RSS</a> ne coûte rien une fois les entrées structurées en données, et c'est ce qui permet à un client d'intégrer vos changements dans son propre processus de release. C'est aussi ce qui décide si quelqu'un construit dessus. GitHub documente ses <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versions de la REST API</a> juste à côté de la référence, pour la même raison : la politique de versionnage fait partie de l'interface.</p> <h2>À quoi ressemble une bonne entrée en pratique ?</h2> <p>Trois entrées de la même semaine, sous la forme décrite ci-dessus :</p> <pre><code>2026-09-02 Breaking v2 `POST /invoices` rejette désormais une `currency` qui ne correspond pas à la devise du compte du client, en retournant 422 au lieu de convertir silencieusement. Les appelants qui comptaient sur la conversion doivent envoyer la devise du compte. Concerne uniquement v2 ; v1 reste inchangée jusqu'à son sunset le 2027-01-15. 2026-09-02 Additive v1, v2 `Invoice` gagne un horodatage `settled_at`, null jusqu'au règlement de la facture. Aucune action requise. Les clients qui rejettent les champs inconnus devraient être mis à jour. 2026-08-31 Fixed v2 `GET /invoices?status=` retournait une page vide au lieu d'un 400 pour un statut inconnu. Retourne désormais 400 avec les valeurs acceptées. Les appelants ayant fait une faute de frappe voyaient auparavant zéro résultat et voient désormais une erreur. </code></pre> <p>La troisième est le type le plus souvent omis, car en interne c'est une correction de bug. Pour un appelant qui a construit un retry autour de cette page vide, c'est un changement de comportement, et l'entrée est ce qui évite le ticket de support. L'étiquette dit fixed et le corps dit ce qu'un appelant pourrait remarquer, ce qui est la distinction qui garde le journal honnête sans gonfler chaque correction en changement cassant.</p> <h2>Comment les appelants s'y abonnent-ils ?</h2> <p>Donnez-leur plus d'un canal, car ils ont des tâches différentes. Un flux pour le développeur qui veut tout. Un email pour celui qui ne veut que les changements cassants. Des en-têtes de réponse pour le code lui-même, le seul abonné qui n'oublie jamais de vérifier : l'<a href="https://datatracker.ietf.org/doc/html/rfc8594">en-tête <code>Sunset</code> défini dans la RFC 8594</a> place la date de retrait dans la réponse, où une bibliothèque cliente peut la journaliser.</p> <p>Le canal que la plupart des équipes sautent est le direct. Si un appelant a utilisé le champ que vous changez la semaine dernière, vous savez qui il est, et un email à ces comptes vaut plus que n'importe quelle diffusion générale. C'est la même discipline que <a href="https://changeloop.dev/blog/fr/customer-feedback-loop/">fermer la boucle de feedback client</a>, appliquée à un changement que personne n'a demandé : les personnes concernées sont averties individuellement, et tous les autres reçoivent le flux. Un webhook est un quatrième canal avec son propre mode d'échec à connaître avant de s'y fier : <a href="https://changeloop.dev/blog/fr/webhook-changelog/">les changelogs de webhooks</a> couvre pourquoi un changement de payload là-bas casse en silence, sans appelant pour rejeter la nouvelle forme.</p> <h2>Comment rédiger une entrée pour un changement cassant ?</h2> <p>Commencez par la rupture, pas par la raison. Un appelant qui parcourt dix entrées doit savoir dès la première phrase si celle-ci va lui coûter du travail. Puis la date, les versions concernées, la migration, et l'échéance si l'ancien comportement disparaît plutôt que de changer.</p> <p>Mettez le même contenu dans l'avis de dépréciation, l'en-tête de réponse et l'email direct, formulé de façon cohérente, et donnez aux quatre la même date. Un écart entre eux est l'erreur qui transforme un changement planifié en incident, car l'appelant qui n'a lu que l'un d'eux agit sur la mauvaise date. <a href="https://changeloop.dev/blog/fr/breaking-changes/">Qu'est-ce qu'un changement cassant</a> couvre la décision elle-même, et <a href="https://changeloop.dev/blog/fr/api-deprecation/">comment déprécier une API</a> couvre le calendrier qui suit.</p> <p>Chez changeloop, un changement d'API devient une entrée quand la pull request est fusionnée, une personne édite et approuve le brouillon, et l'entrée est publiée sur le <a href="https://changeloop.dev/docs">flux et le widget</a> au moment même où un appelant dont le retour via le widget est devenu l'issue GitHub que la pull request ferme en est averti sur cette issue. L'étape de relecture est celle qui compte ici : un changelog d'API est un document contractuel, et aucun brouillon ne devrait atteindre un appelant sans qu'une personne l'ait lu.</p> <h2>FAQ</h2> <p><strong>Chaque changement d'API a-t-il besoin d'une entrée de changelog ?</strong> Tout changement qu'un appelant correct pourrait remarquer, oui, y compris ceux que vous jugez internes. Les changements sans effet observable sur la requête ou la réponse non, et les ajouter entraîne les lecteurs à survoler.</p> <p><strong>Le changelog d'API devrait-il vivre dans la doc ou sur le site marketing ?</strong> Dans la doc, juste à côté de la référence. Le lecteur y est déjà la plupart du temps, et un changelog sur le site marketing tend à gagner un public pour lequel il n'a pas été écrit.</p> <p><strong>Jusqu'où devrait-il remonter ?</strong> Indéfiniment. Les entrées sont citées des années plus tard dans des revues d'incidents, et un journal tronqué casse ces liens. Paginez plutôt que d'élaguer.</p> <p><strong>Faut-il un changelog séparé par version d'API ?</strong> Non, un seul journal avec un champ version par entrée est plus facile à lire et à chercher. Filtrer par version est une fonctionnalité de la page, pas une raison de scinder le document.</p> </article> <article> <h1>Construire une page de changelog que l'on suit</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Une page de changelog vaut la peine d'être construite quand quelqu'un y reviendrait. C'est une barre plus haute que d'en avoir simplement une, et c'est la barre où échouent la plupart : une page qui existe, est liée dans le pied de page, se met à jour par rafales et n'est visitée par personne sauf pendant un incident. Les décisions qui séparent les deux se prennent avant qu'aucun mot ne soit écrit, et concernent surtout où vit la page et ce qui d'autre est généré à partir du même contenu.</p> <h2>Qu'est-ce qu'une page de changelog ?</h2> <p>C'est la liste publique et datée de ce qui a changé dans un produit, sur une URL qui vous appartient. C'est l'une des cinq surfaces où peuvent apparaître les mêmes entrées, et la question utile n'est pas laquelle choisir mais laquelle est canonique et lesquelles en sont générées.</p> <table> <thead> <tr> <th>Surface</th> <th>Idéale pour</th> <th>Coût</th> </tr> </thead> <tbody><tr> <td>Page hébergée</td> <td>Recherche, liens, le registre long</td> <td>Une URL et un modèle</td> </tr> <tr> <td>Widget in-app</td> <td>Atteindre les utilisateurs qui ne visitent jamais la page</td> <td>Un embed, et de la retenue</td> </tr> <tr> <td>Section doc</td> <td>Public API et développeurs</td> <td>La garder à côté de la référence</td> </tr> <tr> <td>Flux JSON</td> <td>Clients qui construisent sur vos changements</td> <td>Une structure que vous avez déjà</td> </tr> <tr> <td>Flux RSS</td> <td>Développeurs qui s'abonnent une fois</td> <td>Presque rien</td> </tr> </tbody></table> <p>Choisissez une source canonique, publiez une fois, et générez le reste. Les équipes qui maintiennent la page et le widget séparément à la main finissent avec deux textes qui ne concordent pas, et c'est un client qui découvre l'écart.</p> <h2>Où une page de changelog devrait-elle vivre ?</h2> <p>Sur votre propre domaine, sur un chemin stable, avec chaque entrée adressable individuellement via un fragment ou son propre chemin. Les trois emplacements courants sont un chemin sur le site principal, un sous-domaine, et une section de la documentation. Un chemin sur le site principal est le choix par défaut contre lequel il faut argumenter, pas pour : il hérite de l'autorité du site, ne nécessite ni certificat ni DNS supplémentaire, et garde la page dans la même navigation que tout le reste.</p> <p>Un sous-domaine est la bonne réponse quand la page est servie par un système différent du site marketing et que vous feriez sinon du proxy. Le coût est qu'il accumule de l'autorité séparément. Placer le changelog dans la doc est juste quand le public est développeur, pour la raison couverte dans <a href="https://changeloop.dev/blog/fr/api-changelog/">changelog d'API</a> : le lecteur y est en général déjà.</p> <p>Ce qui compte plus que le choix, c'est que les entrées soient individuellement liables. Les gens lient des entrées dans des revues d'incidents et des tickets internes, et une entrée qui ne peut être liée que comme "le changelog, faites défiler" finit collée en capture d'écran à la place.</p> <h2>De quoi a besoin une page de changelog ?</h2> <p>Cinq choses, et sur les deux premières échouent la plupart des pages. Une entrée datée par changement, la plus récente en premier. Une catégorie ou étiquette par entrée pour pouvoir parcourir selon le type qui intéresse. Un permalien par entrée. Une voie d'abonnement. Une recherche ou un filtre au-delà d'une cinquantaine d'entrées.</p> <p>Tout le reste est optionnel. Les captures d'écran aident et coûtent de l'entretien. Les noms d'auteurs bâtissent la confiance sur certains produits et du bruit sur d'autres. Les numéros de version comptent pour les appelants d'une API et pour presque personne d'autre. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> propose un choix par défaut raisonnable pour les étiquettes si vous n'avez pas de raison d'en inventer, et sa règle centrale est celle à garder même si vous jetez le reste : le journal est écrit pour des humains.</p> <p>Groupez par date plutôt que par version quand votre produit livre en continu. Un lecteur qui scanne "était-ce avant ou après notre incident du neuf" cherche une date, et une page organisée par numéro de version l'oblige à faire du calcul.</p> <h2>Page ou widget in-app ?</h2> <p>Les deux, à partir d'une source. La page est où vivent la recherche, les liens et le registre long. Le widget est comment vous atteignez la majorité des utilisateurs qui ne visiteront jamais la page, et il fonctionne parce qu'il apparaît dans le produit qu'ils utilisent déjà.</p> <p>L'échec du widget est l'interruption. Un badge qui exige de l'attention pour chaque entrée est écarté définitivement en une semaine, ce qui vous coûte le canal pour l'entrée qui comptait vraiment. Comptez les non lues depuis la dernière consultation, semez le compteur en silence à la première visite pour que personne ne soit accueilli par un badge d'un an d'historique, et laissez le lecteur l'ouvrir plutôt que de l'ouvrir pour lui.</p> <h2>Comment rendre une page de changelog lisible par machine ?</h2> <p>Publiez les mêmes entrées comme flux. Un <a href="https://www.jsonfeed.org/version/1.1/">flux JSON</a> est l'option la plus simple pour tout ce qui le consomme en code, et un <a href="https://www.rssboard.org/rss-specification">flux RSS</a> est ce qu'attend un développeur abonné dans un lecteur. Les deux coûtent peu une fois les entrées structurées en données plutôt qu'en HTML écrit à la main, ce qui est l'argument réel pour garder la copie canonique structurée.</p> <p>Balisez aussi la page. Les entrées sont des œuvres avec date et titre, et <a href="https://schema.org/CreativeWork">schema.org</a> fournit le vocabulaire. Cela en vaut la peine pour la même raison que les permaliens : cela rend la page utilisable par des choses qui ne sont pas un navigateur, y compris le propre processus de release d'un client. Rien de tout ça ne fonctionne si les entrées sous-jacentes n'ont jamais été des données structurées dès le départ ; <a href="https://changeloop.dev/blog/fr/changelog-file-formats/">formats de fichier changelog</a> couvre ce que coûte chacun de Markdown, JSON et YAML comme source de vérité dont ce flux et ce balisage sont réellement générés.</p> <h2>Une page de changelog aide-t-elle le SEO ?</h2> <p>Indirectement et lentement. Les entrées individuelles se positionnent rarement, car elles ne visent aucune requête que quelqu'un tape. La page gagne sa place via les liens : les entrées sont citées dans des réponses de support, des forums et des analyses d'incidents, et ces liens s'accumulent sur une URL qui vous appartient. Une page mise à jour chaque semaine pendant deux ans est aussi un signal de fraîcheur crédible pour le produit auquel elle appartient.</p> <p>Ce qui ne fonctionne pas, c'est de traiter les entrées comme du content marketing. Une entrée gonflée à trois paragraphes pour l'allonger est pire dans son vrai travail, qui est de dire à un lecteur en une phrase si quelque chose qu'il utilise a changé. Si vous voulez que le changelog soutienne la recherche, mettez l'effort dans les permaliens, le flux et les liens internes vers lui, et gardez les entrées courtes. Notre propre page d'<a href="https://changeloop.dev/changelog-examples">exemples de changelog</a> rassemble des pages qui trouvent cet équilibre.</p> <h2>Comment les gens s'abonnent-ils ?</h2> <p>Donnez-leur les voies qu'ils utilisent déjà : un flux RSS ou JSON pour les développeurs, un email pour ceux qui ne veulent entendre que les choses importantes, et le widget in-app pour tous ceux qui ne feront jamais ni l'un ni l'autre. Demandez ce qu'ils veulent entendre plutôt que de le supposer, car un lecteur qui veut les changements cassants et reçoit des corrections de texte se désabonne des deux.</p> <p>La voie à ajouter en dernier est celle qui ferme la boucle. Quand une entrée résout ce qu'une personne précise a demandé, dites-le-lui directement plutôt que d'espérer qu'elle lise la page. Chez changeloop, l'entrée est publiée d'un coup sur la <a href="https://changeloop.dev/docs">page, le flux et le widget</a>, et une personne dont le retour via le widget est devenu l'issue GitHub que la pull request a fermée en est avertie sur cette issue, avec un lien vers l'entrée, et voit l'entrée dans le widget. Le mécanisme est le même que n'importe quel abonnement ; la différence est que le destinataire a déjà demandé. C'est l'argument développé dans <a href="https://changeloop.dev/blog/fr/customer-feedback-loop/">fermer la boucle de feedback depuis le changelog</a>.</p> <h2>FAQ</h2> <p><strong>La page de changelog devrait-elle être sur un sous-domaine ou un chemin ?</strong> Un chemin sur le site principal par défaut, car il hérite de l'autorité du site et ne nécessite pas d'infrastructure supplémentaire. Un sous-domaine se justifie quand un système différent sert la page.</p> <p><strong>Combien d'entrées la page devrait-elle montrer à la fois ?</strong> Assez pour remplir un écran et pas plus, avec pagination ensuite. Charger deux ans d'historique dans un document est lent et rend l'entrée la plus récente plus difficile à trouver.</p> <p><strong>Les anciennes entrées devraient-elles jamais être supprimées ?</strong> Non. Elles sont citées depuis l'extérieur de votre site et les liens se cassent. Corrigez une entrée sur place avec une note, et gardez l'URL en vie.</p> <p><strong>Chaque changement doit-il apparaître sur la page ?</strong> Seulement ceux qu'un utilisateur pourrait remarquer. Une page qui journalise des refactorisations internes entraîne les lecteurs à survoler, et une page survolée échoue le jour où elle porte quelque chose d'urgent.</p> </article> <article> <h1>Le modèle d'email de mise à jour produit qu'on lit</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>L'email de mise à jour produit qu'on lit est celui envoyé à quelqu'un qui a demandé exactement ce qu'il annonce. Tout le reste rivalise avec le reste de la boîte de réception en intérêt, une compétition qu'une annonce de release perd la plupart des semaines. Ce seul fait devrait décider de la forme de l'email avant toute rédaction : qui le reçoit, et ce que cette personne a fait pour se retrouver sur la liste.</p> <h2>Qu'est-ce qu'un email de mise à jour produit ?</h2> <p>C'est un message qui dit aux utilisateurs existants ce qui a changé dans un produit qu'ils utilisent déjà. Il en existe quatre types distincts, et les traiter comme une seule liste est la raison pour laquelle les taux d'ouverture déclinent. Chacun a un déclencheur différent, un public différent et une fréquence acceptable différente.</p> <table> <thead> <tr> <th>Type</th> <th>Déclencheur</th> <th>Public</th> <th>Fréquence</th> </tr> </thead> <tbody><tr> <td>Notification ciblée</td> <td>La demande précise de quelqu'un est livrée</td> <td>Une personne</td> <td>Chaque fois que ça arrive</td> </tr> <tr> <td>Avis de changement cassant</td> <td>Un changement qui coûte du travail au lecteur</td> <td>Comptes concernés seulement</td> <td>Chaque fois que ça arrive</td> </tr> <tr> <td>Digest</td> <td>Le passage du temps</td> <td>Utilisateurs opt-in</td> <td>Mensuel au maximum</td> </tr> <tr> <td>Annonce de lancement</td> <td>Un lancement qui mérite une interruption</td> <td>Segment ou tous</td> <td>Rare, et devrait sembler rare</td> </tr> </tbody></table> <p>La plupart des équipes ne construisent que le troisième, l'envoient à tout le monde, et en concluent que les emails de mise à jour produit ne fonctionnent pas. Les deux premiers portent presque toute la valeur, car le lecteur a une raison préalable de s'y intéresser, et le message arrive pendant que cette raison est vivante.</p> <p>Ces quatre lignes sont toutes écrites pour des clientes. Les ventes, le support et le customer success doivent aussi savoir ce qui est sorti, généralement sous une forme différente de ces quatre-là ; <a href="https://changeloop.dev/blog/fr/internal-release-notes/">notes de release internes</a> couvre ce que ce document devrait dire et pourquoi il doit sortir avant la note orientée client.</p> <p>L'email est l'un des plusieurs canaux qu'une annonce de lancement peut utiliser, pas le seul. <a href="https://changeloop.dev/blog/fr/new-feature-announcement/">Comment annoncer une nouvelle fonctionnalité</a> couvre les autres, et comment choisir entre eux selon l'ampleur réelle de la fonctionnalité.</p> <h2>Que contient le modèle ?</h2> <p>Six blocs, dans cet ordre. Le premier est celui qui manque le plus souvent et celui qui fait le travail.</p> <pre><code>Objet : <ce qui a changé, avec les mots du lecteur> 1. Pourquoi vous recevez ceci "Vous avez demandé l'export CSV en mars." ou "Votre intégration appelle /v1/invoices, qui change le 15 janvier." 2. Ce qui a changé Une phrase. Ce qui est désormais possible, ou ce qui casse désormais. 3. Ce que vous devez faire Souvent "rien". Dites-le explicitement, ne le laissez pas implicite. 4. Où le voir Un lien vers l'entrée du changelog, pas vers la page d'accueil. 5. Quand La date de livraison, ou depuis quand cela s'applique. 6. Comment se désabonner Un clic, et respecté immédiatement. </code></pre> <p>Le bloc 1 est la différence entre un message et une diffusion générale. Un lecteur à qui l'on dit, dès la première ligne, que ceci est la résolution de quelque chose qu'il a personnellement demandé, lit le reste. Sans lui, les blocs 2 à 5 sont une newsletter, quelle que soit la qualité de l'écriture.</p> <p>Gardez l'ensemble sous environ 150 mots. L'email est un pointeur vers l'entrée du changelog, et l'entrée est où va le détail. Un email qui reproduit l'entrée entière ne donne au lecteur aucune raison de cliquer, et ne vous donne aucun signal sur l'intérêt que cela a suscité.</p> <h2>Quels objets fonctionnent ?</h2> <p>Nommez le changement, pas la release. "L'export CSV est en ligne" bat "mise à jour de septembre" parce que le premier est un fait que le lecteur peut évaluer et le second un contenant. Les numéros de version dans l'objet sont utiles aux appelants d'une API et du bruit pour tous les autres, autre raison de séparer les publics.</p> <p>Évitez d'affirmer un bénéfice auquel le lecteur n'a pas consenti. "Vos rapports sont désormais plus rapides" affirme quelque chose sur son expérience ; "Les rapports de plus de 10 000 lignes chargent désormais en moins d'une seconde" rapporte un changement et le laisse décider si cela compte.</p> <h2>Quand en envoyer un, et à qui ?</h2> <p>Envoyez une notification ciblée au moment où la chose est livrée, aux personnes qui l'ont demandée, individuellement. Envoyez un avis de changement cassant dès que la date est certaine et à nouveau juste avant, aux comptes réellement concernés plutôt qu'à toute la liste. Envoyez un digest seulement si vous avez assez de changements pour qu'un lecteur en rate sinon, et laissez les gens s'y inscrire séparément.</p> <p>La liste que vous ne devriez presque jamais utiliser est "tous les utilisateurs". Elle transforme un message précis en un message générique, et entraîne au désabonnement. Segmentez selon un comportement que vous stockez déjà : qui l'a demandé, qui utilise cet endpoint, qui est sur ce plan.</p> <h2>Faut-il un consentement pour l'envoyer ?</h2> <p>Pour les clients existants, une mise à jour sur un service qu'ils utilisent est en général une question juridique différente du marketing envers un prospect, et la réponse dépend d'où ils se trouvent et de ce que vous leur avez dit à l'inscription. Dans l'UE, la question pertinente est quelle base légale de l'<a href="https://gdpr-info.eu/art-6-gdpr/">article 6 du RGPD</a> s'applique, et aux États-Unis les messages commerciaux portent des exigences précises fixées dans le <a href="https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business">guide de conformité CAN-SPAM de la FTC</a>. Les deux exigent la même chose en pratique : dites qui vous êtes, précisez l'objet, et laissez les gens pouvoir arrêter.</p> <p>Quelle que soit la base, gardez les flux transactionnel et marketing séparés au niveau de l'envoi. Un avis de changement cassant qu'un client a désabonné parce qu'il partageait une liste avec un digest promotionnel est un incident de support qui attend sa date.</p> <h2>À quoi cela ressemble-t-il une fois rempli ?</h2> <p>La notification ciblée, l'email de mise à jour produit de plus grande valeur et celui que la plupart des équipes ne construisent jamais :</p> <pre><code>Objet : L'export CSV est en ligne Bonjour Dana, vous avez demandé l'export CSV en mars. C'est en ligne depuis ce matin. Les rapports ont désormais un bouton Export qui génère un CSV de la vue actuelle, filtres inclus. Rien à faire de votre côté. C'est déjà activé sur votre compte. Détails : example.com/changelog#csv-export Livré : 2 septembre 2026 Vous recevez ceci parce que vous l'avez demandé. Se désabonner des mises à jour de demandes : <lien> </code></pre> <p>Quatre-vingt-dix mots, et le lecteur sait dès la première ligne pourquoi cela est arrivé. Comparez avec le même changement dans un digest mensuel, où il apparaît comme un point parmi neuf et Dana n'a aucune raison de remarquer que sa propre demande est sortie.</p> <h2>Que devriez-vous mesurer ?</h2> <p>Pas le taux d'ouverture seul. Pour une notification ciblée, la question est de savoir si la personne qui a demandé est revenue et a utilisé la chose, donc le chiffre à surveiller est le clic vers l'entrée et si ce compte utilise la fonctionnalité dans la semaine. Pour un avis de changement cassant, c'est la couverture : quelle part des comptes concernés a ouvert avant la date, et avec qui vous avez fait un suivi individuel.</p> <p>Un digest est le seul des quatre où un taux d'ouverture signifie grand-chose, et même là il est plus utile comme tendance contre son propre historique que contre un benchmark du secteur. Différents types d'emails de mise à jour produit ont des tâches différentes, donc un chiffre moyenné sur tous ne décrit rien sur quoi agir.</p> <h2>En quoi est-ce différent des notes de version ?</h2> <p>Les notes de version sont un document qui reste disponible. L'email est un mécanisme de livraison qui arrive une fois. Le même changement produit les deux, et l'email devrait être plus court que l'entrée vers laquelle il pointe. <a href="https://changeloop.dev/blog/fr/release-notes-best-practices/">Bonnes pratiques des notes de version</a> couvre le document, et <a href="https://changeloop.dev/blog/fr/changelog-vs-release-notes/">changelog vs notes de version</a> couvre lequel vous êtes en train d'écrire.</p> <p>La relation à bien avoir : l'entrée du changelog est le texte canonique et l'email la cite. Quand les deux divergent, le lecteur qui clique trouve une description différente du changement et cesse de faire confiance aux deux. Publier l'entrée d'abord et générer l'email à partir d'elle élimine la dérive par construction. changeloop fonctionne de la même façon de son côté : une entrée est relue et publiée une fois sur la <a href="https://changeloop.dev/docs">page, le flux et le widget</a>, et la personne qui l'a demandée via le widget en est avertie sur l'issue GitHub qu'est devenu son retour, et dans le widget lui-même. changeloop n'envoie pas l'email ; votre outil d'emailing cite l'entrée publiée.</p> <h2>FAQ</h2> <p><strong>À quelle fréquence devrait sortir un email de mise à jour produit ?</strong> Aussi souvent qu'il y a quelque chose de précis que le destinataire veut savoir, ce qui pour une notification ciblée est chaque fois que sa demande est livrée et pour un digest est mensuel au maximum.</p> <p><strong>L'email devrait-il contenir l'entrée entière du changelog ?</strong> Non. Une phrase et un lien. L'entrée est la version canonique, et une copie complète dans l'email signifie deux textes à garder alignés.</p> <p><strong>Quel taux d'ouverture devrais-je attendre ?</strong> Comparez chaque type à lui-même plutôt qu'à un benchmark. Une notification ciblée et un digest mensuel sont des produits différents, et les moyenner cache le seul chiffre qui mérite d'être surveillé.</p> <p><strong>Faut-il une liste séparée pour les changements cassants ?</strong> Oui, et cela devrait être celle dont les gens ne peuvent pas se désabonner par inadvertance sans comprendre la conséquence, car c'est celle qui leur coûte une panne.</p> </article> <article> <h1>Comment déprécier une API sans perdre ses développeurs</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Déprécier une API, c'est annoncer que quelque chose fonctionne encore aujourd'hui et cessera de fonctionner à une date déclarée, puis tenir les deux moitiés de cette promesse. La plupart des dépréciations échouent sur la seconde moitié : la date glisse silencieusement, ou elle arrive et les appelants qui n'ont jamais vu l'avis l'apprennent par une erreur. Une dépréciation est terminée quand chaque appelant concerné a soit migré, soit reçu, individuellement, la confirmation que ce n'est pas le cas.</p> <h2>Qu'est-ce que la dépréciation d'une API ?</h2> <p>La dépréciation est la période entre l'annonce qu'un endpoint, un champ ou une version va disparaître et sa suppression effective. Pendant cette période, l'ancien comportement continue de fonctionner, la documentation dit qu'il s'en va, et chaque réponse porte un avertissement lisible par machine. La suppression est l'événement séparé, ultérieur, souvent appelé sunset. Les deux se confondent, et cette confusion est là où le mal se produit : "deprecated" commence à signifier "peut-être déjà parti", et les appelants cessent de faire confiance aux deux mots.</p> <table> <thead> <tr> <th>Terme</th> <th>Signification</th> <th>Sur quoi les appelants peuvent compter</th> </tr> </thead> <tbody><tr> <td>Deprecated</td> <td>Annoncé comme disparaissant, fonctionne encore</td> <td>Comportement complet jusqu'à la date de sunset</td> </tr> <tr> <td>Sunset</td> <td>La date où ça cesse de fonctionner</td> <td>Rien après cette date</td> </tr> <tr> <td>Retired / supprimé</td> <td>Parti ; les requêtes échouent</td> <td>Une erreur, idéalement qui nomme le remplacement</td> </tr> <tr> <td>Legacy</td> <td>Indéfini. Éviter le mot</td> <td>Rien, ce qui est le problème</td> </tr> </tbody></table> <h2>Quelle devrait être la durée d'une période de dépréciation ?</h2> <p>Assez longue pour qu'un appelant l'apprenne et fasse le travail, mesurée à partir du moment où l'avis l'a atteint plutôt qu'à partir du moment où vous l'avez écrit. Quatre-vingt-dix jours est le plancher courant pour une API web publique. Douze mois est normal pour tout ce qui est embarqué dans un logiciel que les utilisateurs finaux installent, parce que la correction doit aussi passer par leur processus de release. Le guide de versionnage de Google, <a href="https://google.aip.dev/185">AIP-185</a>, demande une période de transition raisonnable et recommande 180 jours avant même de retirer une fonctionnalité bêta, et Kubernetes documente sa <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy/">politique de dépréciation</a> en nombre de releases plutôt qu'en mois, ce qui est la bonne unité quand vos appelants mettent à jour par version.</p> <p>Choisissez une période, écrivez-la comme politique, et arrêtez de la décider par changement. Une politique publiée transforme chaque dépréciation d'une négociation en une application de règle.</p> <p>Écrire la politique de dépréciation couvre le début de la fenêtre ; <a href="https://changeloop.dev/blog/fr/sunsetting-api-version/">mettre fin à une version d'API</a> couvre l'avis séparé nécessaire à la fin, quand la période s'écoule réellement et que la version arrête de fonctionner.</p> <h2>Le calendrier de dépréciation</h2> <p>Quatre dates, annoncées ensemble le premier jour. Chacune est une entrée de changelog séparée à son arrivée, donc l'histoire est racontée quatre fois à qui ne lit que le changelog.</p> <ol> <li><strong>Annoncer.</strong> L'entrée dit ce qui est déprécié, pourquoi, ce qui le remplace, et la date de sunset. La documentation de l'ancienne chose gagne une bannière qui lie vers la migration. Les réponses gagnent les en-têtes décrits ci-dessous.</li> <li><strong>Rappeler, à mi-chemin.</strong> Une seconde entrée, et un message direct à chaque appelant qui utilise encore l'ancien comportement. C'est l'étape qui a besoin de données d'usage : si vous ne pouvez pas lister qui appelle encore l'endpoint déprécié, vous ne pouvez pas le faire, et ça vaut la peine de corriger ça avant la prochaine dépréciation.</li> <li><strong>Brownout, peu avant la date.</strong> Renvoyez des erreurs pour l'ancien comportement pendant une courte fenêtre, une heure ou un jour, puis restaurez-le. Les appelants qui ont manqué tous les avis l'apprennent maintenant, pendant qu'il reste du temps. GitHub a utilisé des brownouts planifiés avant de <a href="https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/">retirer l'authentification par mot de passe pour l'API</a>, et c'est l'étape individuelle la plus efficace de cette liste.</li> <li><strong>Sunset.</strong> Supprimez-le. L'erreur qui le remplace nomme le remplacement et lie le guide de migration. Gardez l'erreur en place longtemps ; un 404 ne dit rien à un appelant.</li> </ol> <h2>Que devrait dire un avis de dépréciation ?</h2> <p>Un avis de dépréciation dit ce qui disparaît, quand ça s'arrête, quoi utiliser à la place, et qui est concerné. Voici la forme, remplie :</p> <blockquote> <p><strong><code>GET /v1/reports/daily</code> est déprécié et cesse de fonctionner le 1er mars 2027.</strong> Il est remplacé par <code>GET /v2/reports?granularity=day</code>, qui renvoie les mêmes données avec un schéma stable et de la pagination. Concerne les 214 intégrations qui ont appelé l'endpoint v1 au cours des 30 derniers jours ; si la vôtre en fait partie, vous recevrez aussi cet avis par email. Guide de migration : [lien]. Rien ne change jusqu'au 1er mars 2027. À partir de cette date, l'endpoint v1 renvoie <code>410 Gone</code> avec un lien vers cette entrée.</p> </blockquote> <p>Chaque phrase porte quelque chose dont la lectrice a besoin. Le nombre d'intégrations concernées dit à chaque lectrice si elle doit continuer à lire. "Rien ne change jusqu'à" est la phrase qui laisse celles qui ne sont pas concernées fermer l'onglet. La page <a href="https://changeloop.dev/changelog-examples">exemples de changelog</a> rassemble des entrées d'équipes qui écrivent cette forme de manière cohérente, et ça vaut la peine d'en lire trois avant d'écrire la première sienne.</p> <h2>Quels en-têtes un endpoint déprécié devrait-il envoyer ?</h2> <p>Envoyez <code>Deprecation</code>, <code>Sunset</code> et un <code>Link</code> vers le successeur, sur chaque réponse de l'endpoint déprécié, dès le jour de l'annonce. L'<a href="https://datatracker.ietf.org/doc/html/rfc9745">en-tête <code>Deprecation</code></a> porte la date à laquelle la dépréciation a pris effet ; l' <a href="https://datatracker.ietf.org/doc/html/rfc8594">en-tête <code>Sunset</code></a> porte la date où l'endpoint cesse de répondre ; <code>Link: <url>; rel="successor-version"</code> pointe vers ce qu'il faut utiliser à la place.</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/changelog/daily-reports>; rel="deprecation" </code></pre> <p>La plupart des appelants ne liront jamais les en-têtes eux-mêmes. Leur valeur est que le client HTTP, le gateway ou le monitoring d'un appelant le peut, ce qui transforme votre dépréciation en alerte de leur côté plutôt qu'en page du vôtre. Les SDK que vous livrez devraient enregistrer un avertissement quand ils en voient un.</p> <h2>Qui a été informé, et comment le savez-vous ?</h2> <p>C'est l'étape qui décide si le sunset se passe calmement ou devient un incident de support, et c'est la plus difficile à faire avec un changelog seul. Une entrée de changelog informe tous ceux qui lisent le changelog. Une dépréciation doit atteindre les personnes spécifiques dont le code va échouer, et la façon habituelle de les trouver, ce sont les mêmes données d'usage dont a besoin le rappel à mi-chemin : les clés API, apps ou comptes qui ont appelé le comportement déprécié récemment.</p> <p>La boucle qu'on exécute : l'entrée est rédigée à partir de la pull request qui ajoute la dépréciation, une personne relit la formulation et la date, et une fois publiée, l'entrée elle-même est la notification. Toute personne dont le retour via le widget sur le problème, ou la demande du remplacement, est devenu une issue GitHub que la pull request ferme reçoit un commentaire sur cette issue disant que c'est livré, avec un lien vers l'entrée. <a href="https://changeloop.dev/docs">Feed et widget</a> servent la même entrée à tous les autres, avec chaque autre entrée du <a href="https://changeloop.dev/blog/fr/api-changelog/">changelog d'API</a>. Ce qu'on ne fait pas, c'est laisser la dépréciation devenir "livrée" avant qu'une personne l'ait publiée ; un avis avec la mauvaise date est pire qu'aucun avis.</p> <p>Quel que soit votre outillage, la question à laquelle vous devez pouvoir répondre le jour du sunset est : quels appelants utilisaient encore ça la semaine dernière, et lesquels d'entre eux avons-nous prévenus directement ? Si la réponse est "on a posté quelque chose à ce sujet", le sunset n'est pas prêt.</p> <h2>Quelle est la différence entre déprécier et versionner ?</h2> <p>Versionner, c'est comment vous gardez disponible l'ancien comportement pendant que le nouveau existe ; déprécier, c'est comment vous retirez l'ancien. Une nouvelle version d'API sans politique de dépréciation pour la précédente est un engagement à faire tourner les deux pour toujours. Une dépréciation sans versionnage est un <a href="https://changeloop.dev/blog/fr/breaking-changes/">changement cassant</a> avec un délai. Vous avez besoin des deux, et la version est la moitié la plus facile. GraphQL est l'exception qui vaut la peine d'être nommée : il n'y a généralement aucun numéro de version à incrémenter, et <a href="https://changeloop.dev/blog/fr/graphql-schema-deprecation/">dépréciation de schéma GraphQL</a> couvre comment un unique schéma partagé retire un champ avec une directive à la place.</p> <h2>FAQ</h2> <p><strong>Un endpoint déprécié devrait-il continuer à fonctionner exactement comme avant ?</strong> Oui, jusqu'à la date de sunset. Les seuls changements permis sont les en-têtes ajoutés et, vers la fin, un brownout planifié annoncé à l'avance.</p> <p><strong>Quel code de statut un endpoint retiré devrait-il renvoyer ?</strong> <code>410 Gone</code>, avec un corps et un en-tête <code>Link</code> pointant vers le remplacement et l'entrée de changelog. <code>404</code> dit que l'URL n'a jamais existé, ce qui est faux et inutile.</p> <p><strong>Peut-on raccourcir une période de dépréciation ?</strong> Seulement pour la sécurité. Si l'ancien comportement est exploitable, dites-le, raccourcissez la période, et prévenez chaque appelant concerné directement plutôt que de compter sur le changelog.</p> <p><strong>Faut-il déprécier un champ, ou seulement des endpoints entiers ?</strong> Champs, paramètres, valeurs d'enum, valeurs par défaut et en-têtes ont tous besoin du même traitement, parce que chacun peut casser un appelant correct. Un champ supprimé est la dépréciation la plus courante et la plus souvent sautée.</p> </article> <article> <h1>Bonnes pratiques de versionnage d'API, pour les appelants</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Le versionnage d'API est la pratique de garder fonctionnel un ancien contrat après l'avoir changé, pour que les appelants puissent avancer selon leur propre calendrier plutôt que le vôtre. Cette phrase contient les deux décisions qui comptent : ce qui compte comme changer le contrat, et combien de temps l'ancien continue de fonctionner. Où vit le numéro de version, sujet de la plupart des débats de versionnage, est la moins importante des trois et la plus facile à réussir.</p> <h2>Quand devrait-on versionner une API ?</h2> <p>Versionnez une API seulement quand un changement casserait un appelant correct. Les changements additifs, nouveaux champs, nouveaux endpoints, nouveaux paramètres optionnels, n'ont pas besoin de version ; les appelants écrits contre l'ancien contrat continuent de fonctionner et la nouvelle capacité est simplement là. Un <a href="https://changeloop.dev/blog/fr/breaking-changes/">changement cassant</a> en a besoin, parce que l'alternative est qu'un appelant l'apprenne par une erreur. Versionner chaque release, y compris les additives, apprend aux appelants que les versions sont du bruit, et ils cessent de lire les avis qui comptent.</p> <p>Le test pratique est celui de l'article sur les changements cassants : si un appelant qui ne comptait que sur le comportement documenté doit changer quelque chose pour continuer à fonctionner, le changement a besoin d'une version. Sinon, livrez-le sous la version actuelle et écrivez une entrée de changelog.</p> <h2>Quel schéma de versionnage d'API devrait-on utiliser ?</h2> <p>Utilisez le schéma que vos appelants peuvent voir et fixer le plus facilement, ce qui pour la plupart des API publiques est une version dans le chemin de l'URL ou un en-tête de version daté. Les quatre schémas courants diffèrent moins en capacité qu'en ce qu'ils demandent à l'appelant, et c'est la bonne base pour choisir.</p> <table> <thead> <tr> <th>Schéma</th> <th>Exemple</th> <th>Ce que l'appelant doit faire</th> <th>Qui l'utilise</th> </tr> </thead> <tbody><tr> <td>Chemin URL</td> <td><code>/v2/invoices</code></td> <td>Changer l'URL en migrant</td> <td>La plupart des API REST publiques</td> </tr> <tr> <td>En-tête de version</td> <td><code>X-GitHub-Api-Version: 2022-11-28</code></td> <td>Envoyer un en-tête, ou accepter le défaut</td> <td>GitHub</td> </tr> <tr> <td>Version de compte datée</td> <td><code>Stripe-Version: 2026-08-26</code></td> <td>Fixer une date par requête ou par compte</td> <td>Stripe</td> </tr> <tr> <td>Paramètre de requête</td> <td><code>/invoices?version=2</code></td> <td>Ajouter un paramètre</td> <td>API plus anciennes ; rarement choisi maintenant</td> </tr> <tr> <td>Type de média</td> <td><code>Accept: application/vnd.example.v2+json</code></td> <td>Négocier les types de contenu</td> <td>Puristes ; peu d'appelants maîtrisent</td> </tr> </tbody></table> <p><strong>Chemin URL</strong> est le plus visible et le moins flexible. Chaque appelant peut voir dans quelle version il se trouve en lisant une ligne de log, et un saut de version est un chercher-remplacer. Le coût : toute la surface bouge d'un coup, vous ne pouvez pas changer le contrat d'un seul endpoint sans frapper une nouvelle version pour tous, donc les versions de chemin tendent à être rares et volumineuses.</p> <p><strong>En-tête de version</strong> garde les URL stables et laisse le serveur choisir un défaut pour les appelants qui n'envoient rien, comme fonctionne le <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versionnage de l'API REST de GitHub</a> : une version nommée par date dans <code>X-GitHub-Api-Version</code>, avec la version supportée la plus ancienne comme défaut pour que les appelants non versionnés ne cassent pas. Le coût : la version est invisible dans une URL et facile à oublier dans un nouveau client.</p> <p><strong>Version de compte datée</strong> est le schéma d'en-tête plus un ajout : la version est stockée contre le compte, donc chaque requête l'obtient sans rien envoyer. Le <a href="https://docs.stripe.com/api/versioning">versionnage d'API de Stripe</a> fixe chaque compte à la version avec laquelle il a été créé et laisse une requête l'écraser avec <code>Stripe-Version</code>. C'est le schéma le plus favorable à l'appelant et celui qui demande le plus de travail à opérer, parce que le serveur doit traduire entre chaque version supportée et l'actuelle. Le fonctionnement détaillé est dans <a href="https://changeloop.dev/blog/fr/stripe-api-versioning/">le versionnage de l'API Stripe</a>.</p> <p><strong>Paramètre de requête</strong> et <strong>type de média</strong> fonctionnent tous les deux et échouent tous les deux le test de visibilité de manière différente : un paramètre de requête se perd facilement en construisant une URL, et une version en type de média est invisible pour presque tout outil avec lequel un appelant déboguerait.</p> <h2>Comment fait-on le versionnage d'API en pratique ?</h2> <p>En pratique, une version est un ensemble nommé de comportements, et le serveur mappe chaque requête sur l'un d'eux. Les étapes sont les mêmes quel que soit le schéma qui porte le nom.</p> <ol> <li><strong>Nommez les versions par date ou par entier, pas par version sémantique.</strong> Une API web n'est pas un paquet. Les appelants ne peuvent pas fixer une version mineure d'une URL, donc <code>v2</code> ou <code>2026-08-26</code> dit tout ce dont un appelant a besoin, et le <a href="https://semver.org/">versionnage sémantique</a> implique une promesse de compatibilité que le schéma ne peut pas tenir.</li> <li><strong>Gardez la version hors des chemins de code qui s'en fichent.</strong> Une version devrait sélectionner une couche de traduction en bordure, pas bifurquer la logique métier. Deux copies complètes de la codebase, c'est comment une version finit non maintenue.</li> <li><strong>Donnez à chaque version un défaut et un document.</strong> Les appelants qui n'envoient pas de version reçoivent la plus ancienne supportée, jamais la plus récente, pour qu'un client non fixé ne casse pas le jour de la release. Chaque version a une page qui dit ce qui a changé par rapport à la précédente.</li> <li><strong>Fixez une fenêtre de support et publiez-la.</strong> Le guide de versionnage de Google, <a href="https://google.aip.dev/185">AIP-185</a>, demande une période de transition raisonnable et bien communiquée, et recommande 180 jours même pour une fonctionnalité bêta. Choisissez une fenêtre, écrivez-la, et appliquez-la sans renégocier par version.</li> <li><strong>Retirez les versions comme vous retirez les endpoints.</strong> Une version passé sa fenêtre reçoit le même traitement que toute <a href="https://changeloop.dev/blog/fr/api-deprecation/">API dépréciée</a> : une annonce, un en-tête <code>Sunset</code> (<a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594</a>) sur chaque réponse, un rappel à mi-chemin aux appelants restants, et une date de suppression qui tient.</li> </ol> <h2>Que sont v1 et v2 dans une API REST ?</h2> <p><code>v1</code> et <code>v2</code> sont des noms pour deux contrats que le même serveur supporte en même temps. Un <code>v2</code> existe parce que quelque chose dans <code>v1</code> ne pouvait pas être changé sans casser ses appelants, donc le changement est allé dans un nouveau contrat et l'ancien a continué de fonctionner. Les numéros n'impliquent pas que <code>v2</code> est complet ou que <code>v1</code> est mort ; les deux ne sont vrais que si la documentation le dit. Un <code>v3</code> qui apparaît chaque trimestre est un signe que des changements additifs sont versionnés, ou que le contrat n'a jamais été conçu pour absorber le changement. gRPC résout le même problème différemment : <a href="https://changeloop.dev/blog/fr/grpc-protobuf-api-changes/">changements d'API gRPC et Protobuf</a> couvre le versionnage via le nom de package dans un fichier <code>.proto</code> plutôt qu'un chemin d'URL, et un format sur le fil où renommer un champ est gratuit mais le renuméroter est un changement cassant qu'aucun appelant REST ne reconnaîtrait comme risqué.</p> <h2>Que devrait annoncer un changement de version ?</h2> <p>Un changement de version devrait annoncer ce qui casse, qui ça concerne, comment migrer, et combien de temps la version précédente continue de fonctionner. L'entrée a la même forme que n'importe quelle autre entrée de changement cassant, plus une ligne indiquant la fenêtre de support. En voici une pour une API versionnée par en-tête :</p> <blockquote> <p><strong>La version d'API 2026-11-01 est disponible. La version 2025-06-15 est supportée jusqu'au 1er novembre 2027.</strong> Nouveau dans 2026-11-01 : <code>GET /invoices</code> renvoie <code>amount</code> en unités minimales comme entier plutôt que comme chaîne décimale, et le champ déprécié <code>customer_name</code> est supprimé au profit de l'objet <code>customer</code>. Concerne les appelants sur 2025-06-15 qui parsent <code>amount</code> comme chaîne, ce qui est le défaut pour les clients non fixés créés avant juin 2025. Migration : parsez <code>amount</code> comme entier et lisez le nom depuis <code>customer.name</code>. Fixez <code>X-Api-Version: 2026-11-01</code> quand vous êtes prêt. Rien ne change pour les appelants qui ne fixent pas de version.</p> </blockquote> <p>La dernière phrase est celle qui laisse la plupart des lectrices arrêter de lire, et elle appartient à chaque annonce de version. La page <a href="https://changeloop.dev/changelog-examples">exemples de changelog</a> inclut des entrées d'API qui versionnent ainsi, et la différence entre les bonnes et le reste tient surtout dans cette dernière phrase.</p> <h2>Qui est prévenu quand une version change ?</h2> <p>Tout le monde sur l'ancienne version, individuellement, et le changelog pour tous les autres. Un changement de version est le seul cas où "on a posté quelque chose à ce sujet" manque garantiment exactement les appelants qui comptent : ceux qui ont fixé une version il y a deux ans et n'ont pas lu de note de release depuis. Les données d'usage répondent qui ils sont ; l'avis doit les atteindre là où est leur code, dans les en-têtes de réponse et dans un message à la propriétaire du compte.</p> <p>Dans la boucle qu'on exécute, l'entrée qui annonce une version est rédigée à partir de la pull request qui la livre, relue par une personne, et publiée sur <a href="https://changeloop.dev/docs">feed et widget</a>, où un client versionné peut la lire en JSON. Toute personne dont le retour via le widget a demandé le changement, ou signalé le bug qu'elle résout, et est devenu une issue GitHub que la pull request ferme, est prévenue sur cette issue dès que l'entrée est publiée. Le mécanisme est le même que pour n'importe quelle entrée ; un saut de version n'est que l'entrée avec l'enjeu le plus élevé.</p> <h2>FAQ</h2> <p><strong>Chaque changement d'API devrait-il obtenir une nouvelle version ?</strong> Non. Seulement les changements cassants. Les changements additifs sont livrés sous la version actuelle avec une entrée de changelog. Versionner les changements additifs apprend aux appelants à ignorer les versions.</p> <p><strong>Le versionnage par URL est-il meilleur que par en-tête ?</strong> Le versionnage par URL est plus facile à voir pour les appelants et plus difficile à faire évoluer petit à petit pour vous ; le versionnage par en-tête est l'inverse. Pour une API publique avec beaucoup de petits clients, le versionnage par URL échoue moins. Pour une grande API avec couche de traduction, la version datée par en-tête passe mieux à l'échelle.</p> <p><strong>Combien de versions devraient être supportées à la fois ?</strong> Le moins possible selon votre fenêtre de support, et jamais un nombre illimité. Deux ou trois versions concurrentes est normal ; plus que ça signifie généralement que les versions ne sont pas retirées.</p> <p><strong>Que devraient recevoir les requêtes non versionnées ?</strong> La version supportée la plus ancienne, pour que les clients existants non fixés continuent de fonctionner, avec un en-tête de réponse leur disant quelle version ils ont reçue.</p> </article> <article> <h1>Changements cassants : ce qui compte, comment en livrer un</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Un changement cassant est un changement qu'un appelant correctement écrit n'aurait pas pu survivre. La définition compte parce que la plupart des débats sur si quelque chose "compte" sont en réalité des débats sur qui le tenait mal. Si un appelant a suivi votre documentation et votre changement a fait cesser de fonctionner son code, le changement était cassant. Ce que vous vouliez dire n'a rien à voir là-dedans.</p> <p>C'est tout le test. Le reste de cet article, c'est ce qui en découle : ce qui y échoue, ce qui le réussit, comment attraper un échec avant le merge, et quoi faire une fois que vous savez que vous en livrez un.</p> <h2>Qu'est-ce qui compte comme changement cassant ?</h2> <p>Appliquez le test à l'appelant, pas au diff. Un changement est cassant quand un appelant qui ne comptait que sur le comportement documenté doit changer son code, sa configuration ou ses données pour continuer à fonctionner. Supprimer un champ, renommer un endpoint, resserrer la validation, changer une valeur par défaut et changer le type d'une valeur se qualifient tous. Ajouter un champ optionnel non. Corriger un bug généralement non, avec une exception importante ci-dessous.</p> <table> <thead> <tr> <th>Changement</th> <th>Cassant ?</th> <th>Pourquoi</th> </tr> </thead> <tbody><tr> <td>Supprimer ou renommer un champ, endpoint, flag ou option</td> <td>Oui</td> <td>Les appelants corrects le référencent</td> </tr> <tr> <td>Ajouter un champ optionnel ou un nouvel endpoint</td> <td>Non</td> <td>Les appels existants ne changent pas</td> </tr> <tr> <td>Rendre obligatoire une entrée optionnelle</td> <td>Oui</td> <td>Les appels qui l'omettaient échouent maintenant</td> </tr> <tr> <td>Resserrer une validation acceptée auparavant</td> <td>Oui</td> <td>Des entrées qui fonctionnaient sont maintenant rejetées</td> </tr> <tr> <td>Changer une valeur par défaut</td> <td>Oui</td> <td>Les appelants qui ne l'ont pas définie reçoivent un nouveau comportement</td> </tr> <tr> <td>Changer un type (string vers nombre, valeur unique vers array)</td> <td>Oui</td> <td>Les parsers écrits pour le type documenté échouent</td> </tr> <tr> <td>Réordonner les clés d'un objet</td> <td>Non</td> <td>Sauf si vous avez documenté l'ordre</td> </tr> <tr> <td>Corriger un bug dont dépendaient les appelants</td> <td>En pratique oui</td> <td>Voir la section sur les contrats accidentels</td> </tr> <tr> <td>Relever une limite de taux ou un plafond de taille</td> <td>Non</td> <td>Rien de ce qui fonctionnait ne s'arrête</td> </tr> <tr> <td>Baisser une limite de taux ou un plafond de taille</td> <td>Oui</td> <td>Du trafic qui allait bien est maintenant limité</td> </tr> <tr> <td>Changer la formulation d'un message d'erreur</td> <td>Ça dépend</td> <td>Cassant si vous l'avez documenté ou si les appelants matchent dessus</td> </tr> </tbody></table> <h2>Qu'est-ce qui n'est pas un changement cassant ?</h2> <p>Un changement est non cassant quand chaque appel qui fonctionnait avant fonctionne toujours, sans modification, et veut toujours dire la même chose. Ajouter un nouvel endpoint, ajouter un paramètre de requête optionnel, ajouter un champ à une réponse, rendre optionnelle une entrée obligatoire, relever une limite et améliorer un message d'erreur sur lequel personne ne matche réussissent tous le test. Ces changements additifs peuvent sortir dans une version mineure avec une entrée de changelog ordinaire.</p> <p>Les changements additifs cassent quand même des appelants dans trois situations. Un client dont le désérialiseur rejette les champs inconnus échoue dès le premier nouveau champ de réponse : indiquez tôt dans la documentation que les appelants doivent ignorer les champs qu'ils ne reconnaissent pas. Une nouvelle valeur d'enum casse tout appelant avec un switch exhaustif (plus bas). Et une réponse qui grossit peut pousser un appelant au-delà d'une limite de taille, d'un timeout ou d'une largeur de colonne auxquels il n'a jamais eu à penser.</p> <p>Quatre lignes du tableau méritent un regard plus attentif, parce que c'est là que naissent les désaccords.</p> <h2>Les quatre changements cassants que les équipes oublient</h2> <p><strong>Contrats accidentels.</strong> Si votre API a renvoyé le même champ non documenté pendant trois ans, un appelant a construit dessus. La <a href="https://www.hyrumslaw.com/">loi de Hyrum</a> est la version courte : avec assez d'utilisateurs, chaque comportement observable de votre système dépendra de quelqu'un. C'est pourquoi "c'était une correction de bug" n'est pas une défense. La correction peut être correcte et quand même cassante. Livrez-la comme telle.</p> <p><strong>Changements de comportement sans changement de schéma.</strong> Le champ est toujours là, le type est le même, et la valeur signifie maintenant autre chose. Un <code>status</code> qui était <code>active</code> ou <code>inactive</code> et renvoie maintenant aussi <code>suspended</code> casse chaque appelant avec un switch exhaustif. Un timestamp qui passe de l'heure locale à UTC casse tous ceux qui n'ont pas relu la doc deux fois. Rien dans un diff du fichier OpenAPI ne montre ça.</p> <p><strong>Validation resserrée.</strong> Vous commencez à rejeter des emails sans TLD, ou des espaces en fin de chaîne, ou des noms de plus de 80 caractères. Chaque appelant qui envoyait exactement ça reçoit maintenant un 400 pour une requête qui fonctionnait la semaine dernière. Les changements de validation sont les plus souvent livrés comme correction de "durcissement".</p> <p><strong>Valeurs par défaut changées.</strong> Personne qui a défini la valeur explicitement ne remarque rien. Tous ceux qui ne l'ont pas fait, ce qui est la majorité des appelants, reçoivent un nouveau comportement sans changer une ligne. Une valeur par défaut changée casse la majorité de vos utilisateurs précisément parce qu'ils n'ont jamais vu le réglage.</p> <h2>Comment détecter un changement cassant avant qu'il sorte ?</h2> <p>Comparez le contrat de la pull request au contrat de la branche principale, en CI, et faites échouer le build sur toute différence cassante. Des outils de diff de schéma existent pour la plupart des formats d'interface, et chacun connaît les règles de cassure de son propre format :</p> <table> <thead> <tr> <th>Interface</th> <th>Outil</th> <th>Ce qu'il compare</th> </tr> </thead> <tbody><tr> <td>REST (OpenAPI)</td> <td><a href="https://github.com/oasdiff/oasdiff">oasdiff</a></td> <td>Deux specs OpenAPI, avec un rapport des changements cassants</td> </tr> <tr> <td>gRPC (Protobuf)</td> <td><a href="https://buf.build/docs/breaking/">buf breaking</a></td> <td>Les fichiers <code>.proto</code>, au niveau du wire ou des sources</td> </tr> <tr> <td>GraphQL</td> <td><a href="https://github.com/kamilkisiela/graphql-inspector">GraphQL Inspector</a></td> <td>Deux schémas, en signalant les changements cassants et dangereux</td> </tr> <tr> <td>Crates Rust</td> <td><a href="https://github.com/obi1kenobi/cargo-semver-checks">cargo-semver-checks</a></td> <td>L'API publique face à la dernière version publiée</td> </tr> <tr> <td>Paquets TypeScript</td> <td><a href="https://api-extractor.com/">API Extractor</a></td> <td>Un rapport versionné de l'API publique du paquet</td> </tr> </tbody></table> <p>Ces outils attrapent de façon fiable les champs supprimés, les opérations renommées et les types changés. Ils ne voient pas les deux premiers des quatre types ci-dessus, un contrat accidentel ou un changement de comportement, parce qu'aucun n'apparaît dans un schéma. Utilisez l'outil pour arrêter les cas évidents, et la question de revue "un appelant correct pourrait-il le remarquer ?" pour le reste. Le même job de CI est un endroit naturel pour exiger une entrée de changelog, comme décrit dans <a href="https://changeloop.dev/blog/fr/changelog-ci-enforcement/">imposer les entrées de changelog en CI</a>, et <a href="https://changeloop.dev/blog/fr/grpc-protobuf-api-changes/">les changements d'API gRPC et Protobuf</a> passe en revue les cas au niveau du wire.</p> <h2>Comment marquer un changement cassant dans un commit ?</h2> <p>Avec <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, un changement cassant se marque par un <code>!</code> avant les deux-points (<code>feat(api)!: remove the legacy export endpoint</code>) ou par un footer qui commence par <code>BREAKING CHANGE:</code> suivi d'une description. L'un ou l'autre correspond à une version majeure. Écrivez le footer comme le premier jet de l'entrée de changelog, en nommant qui est concerné et ce qu'il doit faire. <a href="https://changeloop.dev/blog/fr/conventional-commits-changelog/">Conventional commits et le changelog</a> explique jusqu'où la convention vous mène.</p> <p>La même règle vaut pour les bibliothèques. Une fonction publique supprimée, un type de paramètre rétréci ou une valeur de retour changée donnent une version majeure sous versionnage sémantique. Les bibliothèques ne la suivent pas toujours : une <a href="https://arxiv.org/abs/2110.07889">étude de 119 879 mises à jour sur Maven Central</a> a trouvé que 16,6% rompaient le versionnage sémantique, alors que seulement 7,9% des projets clients étaient touchés, parce que la plupart de ces changements concernaient du code qu'aucun client n'appelait. La casse se mesure chez l'appelant.</p> <h2>Comment livre-t-on un changement cassant ?</h2> <p>Vous le livrez ouvertement, avec une date, avec un chemin. Les étapes ci-dessous sont dans l'ordre, et la dernière est celle que la plupart des équipes sautent : dire aux personnes concernées que ce qu'elles attendaient s'est maintenant produit.</p> <ol> <li><strong>Décidez si c'en est un.</strong> Utilisez le test ci-dessus, pas le diff. Si deux ingénieurs ne sont pas d'accord, c'est cassant ; le désaccord est la preuve qu'un appelant aurait raisonnablement pu compter sur l'ancien comportement.</li> <li><strong>Versionnez-le.</strong> Sous <a href="https://semver.org/">versionnage sémantique</a>, un changement cassant est une version majeure. Si vous exploitez une API datée ou versionnée, ça va dans une nouvelle version et l'ancienne continue de fonctionner jusqu'à une date déclarée. Si vous ne pouvez pas versionner, vous ne livrez pas un changement cassant, vous livrez une panne avec une entrée de changelog. Quel schéma porte la version est le sujet de <a href="https://changeloop.dev/blog/fr/api-versioning-best-practices/">bonnes pratiques de versionnage d'API</a>.</li> <li><strong>Écrivez l'entrée avant que le code soit mergé.</strong> L'entrée a une forme fixe : ce qui change, qui ça concerne, ce qu'ils doivent faire, et pour quand. Si vous ne pouvez pas remplir les quatre, le changement n'est pas prêt. La <a href="https://changeloop.dev/release-notes-template">release notes template</a> met ces entrées en premier, avec une date plutôt qu'un numéro de version, exactement pour ça.</li> <li><strong>Donnez une échéance, pas un numéro de version.</strong> "Supprimé en v5" ne signifie rien pour quelqu'un qui ne suit pas vos versions. "Cesse de fonctionner le 1er novembre 2026" signifie la même chose pour tout le monde.</li> <li><strong>Fournissez la migration.</strong> Un exemple de code de l'ancien appel à côté du nouveau. Si le changement est un renommage, donnez les deux noms dans la même phrase. Si c'est un champ supprimé, dites où sont allées les données.</li> <li><strong>Annoncez-le partout où l'ancien comportement était documenté.</strong> Le changelog, la page docs qui décrit l'endpoint, les release notes du SDK, et l'en-tête de dépréciation dans la réponse si vous en avez un. Annoncé à un seul endroit, c'est annoncé aux gens qui ont eu la chance de regarder là.</li> <li><strong>Fermez la boucle.</strong> Si une cliente a demandé le changement, ou signalé le bug qui y a mené, dites-le-lui quand ça sort. C'est l'étape qui transforme ça d'une chose faite à vos utilisateurs en une chose faite avec eux.</li> </ol> <h2>À quoi ressemble une bonne entrée pour un changement cassant ?</h2> <p>Une bonne entrée nomme l'appelant concerné dans la première ligne, indique la date, et inclut la correction. En voici une pour le cas de validation resserrée, dans la forme qu'on utilise :</p> <blockquote> <p><strong>Les adresses email sans domaine sont rejetées à partir du 1er novembre 2026.</strong> <code>POST /users</code> et <code>PATCH /users/:id</code> acceptent actuellement des valeurs <code>email</code> comme <code>alice@localhost</code>. À partir du 1er novembre, celles-ci renvoient <code>400 invalid_email</code>. Concerne toute intégration qui crée des utilisateurs depuis des annuaires internes. Migration : envoyez une adresse complètement qualifiée, ou omettez le champ et définissez-le plus tard. Aucun changement n'est nécessaire si vos adresses ont déjà un domaine, ce qui est vrai pour 99,4% des comptes créés cette année.</p> </blockquote> <p>Où cet avis a sa place, et ce qui devrait l'accompagner, fait l'objet du <a href="https://changeloop.dev/blog/fr/api-changelog/">changelog d'API</a>.</p> <p>Le pourcentage à la fin n'est pas de la décoration. Il dit à la lectrice si elle doit s'inquiéter, ce qui est la question avec laquelle elle a ouvert l'entrée.</p> <h2>Pourquoi ne pas simplement les éviter ?</h2> <p>Parce que l'alternative est pire. Une API qui ne casse jamais rien accumule chaque erreur qu'elle a jamais faite : le champ mal nommé, la mauvaise valeur par défaut, le timestamp en heure locale. Chacune est une taxe sur chaque nouvel appelant pour toujours, pour protéger des appelants qui auraient pu migrer en un après-midi. Les équipes avec les meilleures réputations de stabilité cassent rarement des choses, selon un calendrier, avec un chemin de migration et un avertissement qui a atteint les gens pour qui il était destiné.</p> <p>La mécanique de cet avertissement est le sujet de l'article compagnon sur <a href="https://changeloop.dev/blog/fr/api-deprecation/">déprécier une API</a>. L'entrée qui l'annonce est rédigée de la même manière que n'importe quelle autre entrée dans le <a href="https://changeloop.dev/docs">flux de changelog</a> : depuis la pull request mergée, retenue pour un humain, puis publiée à l'endroit où les appelants concernés lisent déjà.</p> <h2>FAQ</h2> <p><strong>Quelle est la différence entre un changement cassant et un changement non cassant ?</strong> Un changement cassant force un appelant correct à changer son code, sa configuration ou ses données pour continuer à fonctionner. Un changement non cassant laisse chaque appel existant fonctionner avec le même sens, ce qui explique pourquoi les ajouts sont généralement sûrs et les suppressions, renommages et règles resserrées généralement non.</p> <p><strong>Ajouter un champ obligatoire compte-t-il ?</strong> Oui. Chaque appel existant l'omet, donc chaque appel existant échoue maintenant. Ajoutez-le comme optionnel avec une valeur par défaut sensée, ou versionnez l'endpoint.</p> <p><strong>Une correction de bug compte-t-elle ?</strong> Ça peut. Si des appelants dépendaient du comportement buggé, le corriger les casse, quoi que dise la documentation. Traitez toute correction qui change la sortie observable comme cassante, sauf si vous pouvez montrer que personne n'en dépendait.</p> <p><strong>Le versionnage sémantique s'applique-t-il à une API web ?</strong> La règle oui : les changements cassants reçoivent une nouvelle version majeure et l'ancienne continue de fonctionner pendant une période déclarée. Le numéro vit souvent dans l'URL ou un en-tête de date plutôt que dans une version de paquet.</p> <p><strong>Combien de préavis suffit ?</strong> Assez pour qu'un appelant trouve l'avis et fasse le travail. Quatre-vingt-dix jours est un plancher courant pour les API publiques ; plus long pour tout ce qui est utilisé dans du code livré aux utilisateurs finaux et qui ne peut pas être mis à jour à distance.</p> </article> <article> <h1>Fermer la boucle de feedback depuis le changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Une boucle de feedback client se ferme quand la personne qui a donné le feedback apprend ce qui en a été fait. Pas quand c'est classé. Pas quand c'est priorisé. Même pas quand c'est livré. Quand on le lui dit. La plupart des équipes réussissent bien les trois premières étapes et pas du tout la dernière, puis se demandent pourquoi les gens qui envoient du feedback arrêtent d'en envoyer.</p> <p>Cet article traite de cette dernière étape, et d'une affirmation concrète : le changelog est le bon endroit pour fermer la boucle, parce que c'est le seul artefact qui existe déjà exactement au moment où la boucle peut être fermée.</p> <h2>Qu'est-ce qu'une boucle de feedback client ?</h2> <p>Une boucle de feedback client est le chemin d'une utilisatrice qui vous dit quelque chose jusqu'à cette utilisatrice apprenant ce que vous en avez fait. Elle a quatre étapes : collecter le feedback, décider quoi en faire, livrer le résultat, et prévenir la personne qui a demandé. La boucle est ouverte jusqu'à ce que la quatrième étape arrive. Une équipe qui collecte du feedback et livre des corrections mais ne prévient jamais personne a une boîte de réception, pas une boucle.</p> <table> <thead> <tr> <th>Étape</th> <th>Ce qui se passe</th> <th>Où ça casse généralement</th> </tr> </thead> <tbody><tr> <td>Collecter</td> <td>Le feedback arrive : widget, support, ventes, entretiens</td> <td>Rien ; chaque équipe le fait</td> </tr> <tr> <td>Décider</td> <td>C'est trié, fusionné avec des doublons, accepté ou refusé</td> <td>Les refus ne sont jamais communiqués</td> </tr> <tr> <td>Livrer</td> <td>Quelqu'un le construit et ça part en prod</td> <td>Le lien vers la demande se perd au merge</td> </tr> <tr> <td>Prévenir</td> <td>La demandeuse apprend que c'est livré</td> <td>Sauté, ou fait seulement pour la personne la plus bruyante</td> </tr> </tbody></table> <p>La quatrième ligne est celle dont traite cet article. Elle casse pour une raison structurelle, pas culturelle : le temps qu'une fonctionnalité soit livrée, la demande qui l'a causée vit dans un système différent de la chose livrée, et ce n'est le travail de personne de les connecter. La boucle commence plus tôt, avec la façon dont la demande est formulée au départ ; <a href="https://changeloop.dev/blog/fr/how-to-ask-for-customer-feedback/">comment demander un feedback client</a> couvre les mots et le moment.</p> <h2>Pourquoi les boucles de feedback restent-elles ouvertes ?</h2> <p>Les boucles de feedback restent ouvertes parce que la demande et le changement livré vivent à des endroits différents et que le lien entre les deux est fait à la main, si tant est qu'il le soit. La demande est dans un outil de feedback, une boîte de support ou un tableur. Le changement est dans une pull request. L'annonce est dans un changelog ou un email. Trois systèmes, trois propriétaires, et le lien du troisième vers le premier est une personne qui se souvient, des mois plus tard, qui a demandé.</p> <p>Il y a une seconde raison. L'étape de prévenir est généralement cadrée comme une tâche marketing ("annoncer la fonctionnalité") plutôt qu'une tâche de support ("répondre à la personne"). Les annonces vont à tout le monde et n'atteignent personne en particulier. La personne qui a demandé la fonctionnalité en mars lit l'annonce en juin, si elle la lit, comme une actualité, pas comme une réponse. La boucle se ferme seulement si le message lui est adressé.</p> <h2>Pourquoi fermer la boucle depuis le changelog ?</h2> <p>Parce que l'entrée de changelog est le seul artefact qui existe exactement au bon moment, contient exactement les bons mots, et est écrite par exactement la bonne personne. Elle existe quand le changement est en prod et pas avant. Elle dit ce qui a changé dans les termes de la lectrice, ce qui est le message dont la demandeuse a besoin. Et elle est écrite par quelqu'un qui vient de lire la pull request, ce qui est le seul moment où le lien vers la demande originale est encore visible.</p> <p>Comparez les alternatives. Fermer la boucle depuis l'outil de feedback signifie que l'outil de feedback doit savoir quand la fonctionnalité a été livrée, ce qui signifie que quelqu'un met à jour un statut à la main. La fermer depuis la pull request signifie prévenir la cliente au merge, avant que le changement soit en prod, une promesse rompue avec horodatage dès que le déploiement se retarde. La fermer depuis l'annonce marketing signifie en attendre une, et la plupart des changements livrés n'en ont jamais.</p> <p>Le changelog se trouve au milieu : après le merge, au moment de la livraison, avec la formulation prête.</p> <h2>Comment se ferme la boucle, étape par étape</h2> <p>Voici le mécanisme qu'on exécute. Il est décrit ici comme une spécification plutôt qu'une visite de produit, parce que chaque étape peut se faire à la main ou avec d'autres outils ; ce qui compte, c'est l'ordre.</p> <ol> <li><strong>Le feedback devient une issue dans le repository qui va la corriger.</strong> Une soumission de widget est classée comme issue étiquetée sur GitHub (<code>feature-request</code> ou <code>bug</code>, une priorité, et <code>from-widget</code>), avec l'adresse email de la personne qui l'a envoyée tenue hors du corps de l'issue. L'issue vit à côté du code, pour que l'étape trois puisse la trouver. Une issue créée à la main, par exemple depuis une <a href="https://changeloop.dev/blog/fr/feature-request-template/">template de demande de fonctionnalité</a>, est hors de ce chemin : l'étape cinq ne la commente pas, alors fermez cette boucle vous-même.</li> <li><strong>La correction référence l'issue.</strong> La pull request dit <code>Fixes #142</code>, le propre mot-clé de fermeture de GitHub. Rien de nouveau à apprendre, et c'est la même phrase que les développeuses écrivent déjà.</li> <li><strong>L'entrée de changelog est rédigée à partir de la pull request mergée et porte le lien.</strong> Au merge, le brouillon est créé et <code>#142</code> est lu depuis le corps de la PR et attaché au brouillon. Le lien est créé pendant qu'il est encore bon marché, par une machine, à partir de données déjà là.</li> <li><strong>Une personne relit l'entrée.</strong> Formulation, audience, si ça devrait être publié du tout. Un brouillon jeté ne ferme rien, ce qui est correct : un refactor interne qui a par hasard référencé une issue n'est pas une actualité.</li> <li><strong>À l'approbation, la demandeuse est prévenue.</strong> Un commentaire est posté sur l'issue qu'est devenu son feedback, "Shipped —" suivi du titre de l'entrée et d'un lien vers l'entrée publiée, et le widget montre à la personne qui l'a envoyé la même entrée livrée. Une fois, jamais deux, et seulement après qu'une personne a publié l'entrée. La même entrée sort via <a href="https://changeloop.dev/docs">feed et widget</a> vers tous ceux qui n'ont pas demandé.</li> </ol> <p>L'ordre dans l'étape cinq est tout le design. Prévenir la demandeuse au merge serait plus tôt et plus facile, et serait faux à peu près aussi souvent que les déploiements se retardent. Un feature flag casse même cet ordre, parce qu'approuvé et publié peut se produire pendant que la fonctionnalité reste invisible pour le compte de la demandeuse ; <a href="https://changeloop.dev/blog/fr/feature-flags-feature-requests/">feature flags et demandes de fonctionnalités</a> couvre la vérification supplémentaire dont cette étape a besoin dès qu'un flag entre en jeu.</p> <h2>À quoi ressemble une boucle fermée pour la cliente ?</h2> <p>Ça ressemble à une réponse. La cliente a envoyé une demande via un widget, et un jour le widget l'affiche comme livrée, avec un lien vers une entrée qui la décrit dans ses termes ; sur GitHub, l'issue reçoit la même nouvelle sous forme de commentaire. Elle ne s'est pas abonnée à une newsletter, n'a pas vérifié une roadmap, n'a pas cherché dans le changelog. On le lui a dit.</p> <p>C'est l'expérience qui provoque le prochain morceau de feedback. Les gens envoient du feedback à des produits qui répondent. La page <a href="https://changeloop.dev/changelog-examples">exemples de changelog</a> inclut des entrées d'équipes dont les utilisateurs reviennent visiblement avec des demandes, et le fil commun n'est pas l'outil ; c'est que les entrées se lisent comme des réponses.</p> <h2>Comment mesure-t-on une boucle de feedback ?</h2> <p>Mesurez la fraction des changements livrés qui ont prévenu au moins une demandeuse, et le temps entre la livraison et l'avis. Deux chiffres, tous deux faciles une fois que le lien existe et impossibles avant.</p> <ul> <li><strong>Taux de fermeture</strong> : des entrées de changelog publiées ce mois-ci, combien liaient au moins une demande, et parmi celles-ci, combien ont prévenu la demandeuse. Si le second chiffre est bien plus bas que le premier, les notifications échouent ; si le premier est bas, les demandes ne sont pas référencées depuis les pull requests, et la correction est une phrase dans le template de PR.</li> <li><strong>Temps de livraison à avis</strong> : combien de temps entre l'entrée qui passe en prod et l'avis à la demandeuse. Avec le mécanisme ci-dessus, c'est des secondes. À la main, c'est typiquement des semaines, ou jamais, et "jamais" est le chiffre qui compte.</li> </ul> <p>Ne mesurez pas la boucle par le volume de feedback collecté. Collecter est l'étape facile, et une équipe qui la mesure va l'optimiser, ce qui produit plus de boucles ouvertes.</p> <h2>Où s'insère la roadmap ?</h2> <p>Une roadmap publique est une façon de fermer la boucle tôt : elle dit à la demandeuse que sa demande a été entendue, avant qu'elle soit livrée. C'est utile, et ça ne remplace pas la dernière étape. "Planifié" est une promesse sur l'avenir ; "Livré" est un fait sur le présent. Exécutez la <a href="https://changeloop.dev/blog/fr/public-roadmap/">roadmap publique</a> depuis les mêmes issues, avec un label par colonne, pour que la même demande passe de planifiée à livrée sans être ressaisie nulle part. Le passage à livrée est un changement de label (<code>roadmap:shipped</code>) que personne ne fait à votre place quand l'entrée est approuvée, alors faites-le dans la même relecture.</p> <h2>FAQ</h2> <p><strong>Quelles sont les quatre étapes d'une boucle de feedback client ?</strong> Collecter, décider, livrer, prévenir. La boucle est ouverte jusqu'à ce que la quatrième étape arrive. La plupart des cadres ajoutent des étapes d'analyse et de priorisation au milieu ; ce sont des raffinements de "décider", et aucune d'elles ne ferme rien.</p> <p><strong>Devrait-on prévenir les clients quand une demande est refusée ?</strong> Oui, et c'est le message le plus négligé de la boucle. Un clair "on ne va pas faire ça, et voici pourquoi" met fin à l'attente. Le silence laisse la boucle ouverte pour toujours et la cliente à vérifier.</p> <p><strong>En quoi fermer la boucle diffère-t-il d'annoncer une fonctionnalité ?</strong> Une annonce va à tout le monde. Fermer la boucle est une réponse aux gens qui ont demandé, sur le canal par lequel ils ont demandé. Faites les deux ; ce sont des messages différents pour des lectrices différentes.</p> <p><strong>Et si la demandeuse n'est pas sur GitHub ?</strong> La plupart n'y sont pas, et ce n'est pas grave. Le widget continue de leur montrer le statut de ce qu'elles ont envoyé, y compris l'entrée livrée et son lien, donc elles n'ont besoin de rien d'autre que la page depuis laquelle elles ont écrit. Le commentaire sur l'issue est pour les personnes qui peuvent voir le repository.</p> <p><strong>Est-ce que cette boucle fonctionne sur GitLab ou Bitbucket au lieu de GitHub ?</strong> Le widget et le changelog, oui ; le commentaire automatique de l'étape cinq, pas encore aujourd'hui. Une équipe sur GitLab ou Bitbucket reçoit quand même chaque soumission, la classe quand même comme une issue, et montre quand même à la demandeuse un statut dans le widget, mais refermer cette boucle précise jusque sur l'issue elle-même est une étape à faire à la main tant que cette intégration n'existe pas.</p> </article> <article> <h1>Template de demande de fonctionnalité qui devient changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Une template de demande de fonctionnalité est un formulaire avec quatre questions : ce que la personne essaie de faire, ce qui l'en empêche, ce qu'elle a essayé à la place, et comment elle veut être prévenue quand c'est fait. Tout le reste qui apparaît généralement sur une, sélecteurs de priorité, estimations d'effort, scores de valeur business, est pour l'équipe qui reçoit la demande, et c'est mal rempli par celle qui l'envoie.</p> <p>Les demandes bien rangées sont le mauvais test pour une template. Le bon : six mois plus tard, quand la fonctionnalité est livrée, quelqu'un peut-il trouver la demande, la comprendre, et prévenir la personne qui l'a écrite ? La plupart des templates sont conçues pour l'accueil. Celle-ci est conçue pour le jour où la boucle se ferme.</p> <h2>Que devrait inclure une template de demande de fonctionnalité ?</h2> <p>Elle devrait inclure l'objectif, le blocage, la solution de contournement, et un moyen de revenir vers la demandeuse. Quatre champs, dans cet ordre, chacun répond à une question que l'équipe posera plus tard.</p> <table> <thead> <tr> <th>Champ</th> <th>La question à laquelle il répond plus tard</th> <th>Pourquoi il est dans le formulaire</th> </tr> </thead> <tbody><tr> <td>Qu'essayez-vous de faire ?</td> <td>La fonctionnalité construite est-elle celle qu'il fallait ?</td> <td>L'objectif survit à toute proposition concrète</td> </tr> <tr> <td>Qu'est-ce qui vous en empêche aujourd'hui ?</td> <td>À quoi ressemble "terminé" ?</td> <td>Nomme le vide sans prescrire la correction</td> </tr> <tr> <td>Que faites-vous à la place ?</td> <td>À quel point est-ce vraiment urgent ?</td> <td>Une solution de contournement douloureuse est un signal plus fort qu'un sélecteur de priorité</td> </tr> <tr> <td>Comment devrions-nous vous prévenir ?</td> <td>Qui reçoit le message "livré" ?</td> <td>Le champ que la plupart des templates omettent</td> </tr> </tbody></table> <p>Ce qui manque délibérément : une solution proposée comme champ obligatoire (bienvenue en commentaire, fausse comme cadrage), un sélecteur de priorité (chaque soumetteur choisit haute), et toute estimation d'effort ou de valeur (travail de l'équipe, après le tri). Une template qui demande une solution reçoit des demandes de boutons ; une template qui demande un objectif reçoit des demandes de résultats, et c'est sur des résultats qu'on écrit une entrée de changelog.</p> <h2>La template</h2> <p>Voici la template d'issue GitHub qu'on utilise, sous forme de formulaire. Collez-la dans <code>.github/ISSUE_TEMPLATE/feature_request.yml</code> et elle se rend comme formulaire structuré sur la page de nouvelle issue. Les demandes classées via elle atterrissent comme des issues avec les mêmes champs que celles classées depuis un widget de feedback, ce qui compte pour la section suivante.</p> <pre><code class="language-yaml">name: Feature request description: What you are trying to do, and what stops you. labels: ["feature-request"] body: - type: textarea id: goal attributes: label: What are you trying to do? description: >- The outcome, not the button. "Export a month of invoices as one PDF" beats "add a PDF export". validations: required: true - type: textarea id: blocker attributes: label: What stops you today? description: >- Where the product runs out. An error, a missing option, a limit. validations: required: true - type: textarea id: workaround attributes: label: What do you do instead? description: >- The spreadsheet, the script, the manual step. "Nothing, I gave up" is a valid answer. - type: input id: contact attributes: label: How should we tell you when it ships? description: >- An email address, or leave blank to be notified only on this issue. </code></pre> <p>Deux détails font le travail. <code>labels: ["feature-request"]</code> signifie que la demande est classifiée à la création plutôt que d'attendre que quelqu'un la trie. Et le dernier champ existe parce que "on te préviendra" est une promesse, et une promesse a besoin d'une adresse.</p> <h2>Quels labels une demande de fonctionnalité devrait-elle porter ?</h2> <p>Une demande de fonctionnalité devrait porter un label pour ce qu'elle est, un pour son urgence, et un pour d'où elle vient. Trois labels, trois axes, et chacun est lu par une lectrice différente.</p> <table> <thead> <tr> <th>Label</th> <th>Valeurs</th> <th>Qui le lit</th> </tr> </thead> <tbody><tr> <td>Type</td> <td><code>feature-request</code>, <code>bug</code></td> <td>Qui décide dans quelle file elle entre</td> </tr> <tr> <td>Priorité</td> <td><code>priority:low</code>, <code>priority:medium</code>, <code>priority:high</code></td> <td>Qui planifie le prochain cycle</td> </tr> <tr> <td>Source</td> <td><code>from-widget</code>, <code>from-form</code>, <code>from-support</code></td> <td>Qui mesure d'où viennent les demandes</td> </tr> </tbody></table> <p>Le widget applique les deux premiers axes et <code>from-widget</code> quand il classe une soumission comme issue ; <code>from-form</code> et <code>from-support</code> sont des suggestions pour les demandes qui arrivent par d'autres voies. Les labels du widget sont un type (<code>bug</code> ou <code>feature-request</code>, décidé par un classificateur à partir du seul message), une priorité (un rapport de crash calme et précis est haut ; un doublon de quelque chose déjà demandé est bas ; tout ce qui suggère même vaguement un problème de sécurité est <code>bug</code> et haut, quelle que soit la formulation), et <code>from-widget</code>. Les mêmes trois axes fonctionnent pour les demandes qui arrivent à la main via la template ci-dessus, et c'est le point : une demande est une demande, peu importe par où elle est entrée.</p> <p>Une convention de plus : le widget retire l'adresse email de la personne qui soumet du corps de l'issue avant de la classer, parce que l'issue vit dans un repository qui peut être public, et la remplace par une référence de soumission. L'adresse reste hors de l'issue ; la personne qui soumet suit le résultat dans le widget lui-même. Faites de même avec le champ de contact si votre tracker est visible pour des gens hors de l'équipe.</p> <h2>Comment une demande de fonctionnalité devient-elle une entrée de changelog ?</h2> <p>Une demande de fonctionnalité devient une entrée de changelog quand une pull request ferme l'issue et que l'entrée rédigée à partir de cette pull request lie en retour. Le mécanisme, ce sont les propres mots-clés de fermeture de GitHub : une PR dont la description dit <code>Fixes #142</code> ferme l'issue 142 au merge. Si vos entrées de changelog sont rédigées à partir de pull requests mergées, le brouillon peut porter le numéro d'issue avec lui, et l'entrée sait qui a demandé.</p> <p>C'est la raison pour laquelle la template demande l'objectif plutôt que la solution. Quand l'entrée est écrite, l'objectif est la phrase dont a besoin qui écrit : "Vous pouvez maintenant exporter un mois de factures comme un seul PDF" est une entrée de changelog. "Ajout de l'export PDF" est un message de commit. Les <a href="https://changeloop.dev/changelog-tools">outils de changelog</a> qui rédigent à partir de pull requests peuvent faire la collecte et le lien ; la formulation a toujours besoin d'une personne, et la personne a besoin de l'objectif.</p> <h2>Que se passe-t-il quand c'est livré ?</h2> <p>La demandeuse est prévenue, avec un lien vers l'entrée. Dans notre configuration, c'est automatique pour les demandes arrivées via le widget : un commentaire disant "Shipped — <titre de l'entrée>" avec un lien vers l'entrée publiée, posté sur l'issue dès qu'une personne approuve l'entrée, pendant que le widget montre la même entrée à la personne qui l'a soumise. Une issue créée à la main depuis cette template ne reçoit aucun commentaire automatique ; fermez cette boucle vous-même, selon la même règle. Le commentaire est posté délibérément à l'approbation plutôt qu'au merge : un commentaire disant que quelque chose est en prod avant que ce le soit est une promesse rompue avec horodatage. Chaque demande est notifiée au plus une fois ; une seconde approbation de la même entrée ne produit pas un second commentaire.</p> <p>Si vous faites ça à la main, la même règle s'applique. Ne fermez pas la boucle depuis la pull request. Fermez-la depuis l'entrée publiée, et fermez-la une fois. <a href="https://changeloop.dev/docs">Feed et widget</a> portent la même entrée à tous ceux qui n'ont pas demandé, qui sont la plupart ; le commentaire est pour ceux qui ont demandé.</p> <h2>Pourquoi la plupart des templates de demande de fonctionnalité échouent</h2> <p>Elles sont conçues pour faciliter le tri et y réussissent, au prix du seul moment qui compte pour la demandeuse. Une template avec douze champs reçoit moins de demandes, et celles qu'elle reçoit viennent de gens avec la patience de remplir douze champs, ce qui n'est pas la même population que celle qui a besoin de la fonctionnalité. Une template avec quatre champs, dont un "comment vous contactons-nous", reçoit plus de demandes et peut toutes les honorer.</p> <h2>FAQ</h2> <p><strong>Une template de demande de fonctionnalité devrait-elle demander la priorité ?</strong> Non. Demandez plutôt la solution de contournement. "J'exporte vers un tableur et je le ressaisis chaque vendredi" en dit plus sur la priorité qu'un menu déroulant que la personne qui a soumis a mis sur haute.</p> <p><strong>Les demandeurs devraient-ils proposer une solution ?</strong> Ils peuvent, dans le texte libre. N'en faites pas le cadrage. Les demandes écrites comme des solutions sont plus difficiles à fusionner entre elles et plus difficiles à transformer en entrée de changelog.</p> <p><strong>Les demandes de fonctionnalité devraient-elles apparaître sur une roadmap publique ?</strong> Une fois planifiées, oui : un label sur la même issue la met dans la colonne planifiée, et la demandeuse peut voir comment elle avance. L'article <a href="https://changeloop.dev/blog/fr/public-roadmap/">roadmap publique</a> est le mécanisme.</p> <p><strong>Comment gérer les doublons ?</strong> Liez la nouvelle demande à l'issue existante et étiquetez-la priorité basse ; ne la fermez pas. Chaque doublon est une personne de plus à prévenir quand c'est livré. Avec le commentaire automatique de changeloop, cette personne n'est prévenue que si la pull request nomme aussi son issue (<code>Fixes #142, fixes #187</code>).</p> <p><strong>Où devrait vivre la template ?</strong> Dans le repository qui recevra la pull request, pour que le mot-clé de fermeture fonctionne. Une demande dans un tracker séparé doit être liée à la main au merge, et c'est cette étape qui est sautée.</p> </article> <article> <h1>Roadmap publique depuis votre issue tracker, trois colonnes</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Une roadmap publique est une liste de ce que vous prévoyez de construire, publiée là où les clients peuvent la voir. Le mot qui fait le travail est <em>prévoyez</em> : une roadmap est un ensemble de promesses sur l'avenir, et chaque élément dessus est un que vous tiendrez ou qu'on verra que vous n'avez pas tenu. C'est la raison d'en publier une, et c'est aussi la raison pour laquelle la plupart des roadmaps publiques deviennent obsolètes en un trimestre. La version qui survit est petite, dérivée de données que vous maintenez déjà, et connectée à l'autre bout au changelog, pour qu'une promesse devienne un fait sans que personne ne la ressaisisse.</p> <h2>À quoi sert une roadmap publique ?</h2> <p>Une roadmap publique dit à une cliente avec une demande que sa demande a été entendue, avant qu'elle soit livrée. C'est la moitié précoce de la fermeture de boucle : "planifié" répond à la question "quelqu'un a-t-il lu ça", et "en construction" répond à "est-ce vraiment en train d'arriver". Aucune des deux ne remplace la dernière étape, prévenir la demandeuse quand c'est livré, mais toutes deux réduisent le nombre de gens qui demandent entre-temps.</p> <p>Ça fait aussi une chose pour l'équipe : ça force un engagement public, ce qui est le remède le moins cher connu contre un backlog qui cache silencieusement quatre cents éléments que personne ne construira.</p> <table> <thead> <tr> <th>Colonne</th> <th>La promesse qu'elle fait</th> <th>Ce qui déplace un élément dedans</th> </tr> </thead> <tbody><tr> <td>Planifié</td> <td>On prévoit de construire ça</td> <td>Une décision, enregistrée comme label sur l'issue</td> </tr> <tr> <td>En construction</td> <td>Quelqu'un y travaille maintenant</td> <td>Un label <code>roadmap:building</code> sur l'issue</td> </tr> <tr> <td>Livré</td> <td>C'est en prod</td> <td>Un label <code>roadmap:shipped</code>, ou la fermeture de l'issue qui en porte un</td> </tr> </tbody></table> <p>Trois colonnes, dans un ordre fixe, suffisent. Une quatrième colonne ("en considération", "en révision", "backlog") est là où les bonnes intentions deviennent un musée, et c'est la première que les clients apprennent à ignorer.</p> <h2>Votre roadmap devrait-elle être publique ?</h2> <p>Rendez-la publique si vous pouvez la garder petite et honnête ; gardez-la privée si l'alternative est une longue liste de peut-être. Le coût d'une roadmap publique n'a rien à voir avec sa publication : chaque élément dessus est maintenant une question que quelqu'un posera, en support, dans les appels de vente et dans les conversations de renouvellement. Dix éléments que vous construirez sont un atout. Soixante éléments que vous pourriez construire sont soixante conversations futures sur pourquoi non.</p> <p>Deux raisons honnêtes de ne pas publier : vos plans changent plus vite qu'un trimestre, ou votre concurrence lit votre roadmap plus attentivement que vos clients. Les deux sont réelles, et les deux se résolvent en publiant moins plutôt que rien : seulement "en construction", avec "planifié" gardé en interne, dit quand même à une demandeuse que son issue bouge.</p> <h2>Comment construit-on une roadmap publique à partir d'issues GitHub ?</h2> <p>Mettez un label par colonne sur les issues que vous suivez déjà, et rendez les issues étiquetées comme la roadmap. Rien n'est ressaisi, la roadmap ne peut pas dériver du travail, et la même issue qui a commencé comme demande d'une cliente se déplace à travers les colonnes sans changer d'identité.</p> <p>Le mécanisme, tel qu'on l'exécute :</p> <ol> <li><strong>Un label par colonne, avec préfixe fixe</strong> : <code>roadmap:planned</code>, <code>roadmap:building</code>, <code>roadmap:shipped</code>. Toute issue dans un repository connecté qui en porte un apparaît dans cette colonne. Une issue sans aucun d'eux n'est pas sur la roadmap, ce qui est la plupart des issues, ce qui est correct.</li> <li><strong>Les colonnes sont un tableau ordonné, toujours dans le même ordre.</strong> Planifié, en construction, livré. Pas une map indexée par nom, pour qu'une lectrice (ou un widget) n'ait jamais à deviner la séquence.</li> <li><strong>Si une issue porte deux labels, le plus avancé gagne.</strong> Quelqu'un ajoutera <code>roadmap:shipped</code> avant de retirer <code>roadmap:planned</code> ; une machine à états guidée par "quel webhook est arrivé en dernier" mettrait l'élément dans des colonnes différentes selon l'ordre de livraison. Décider uniquement à partir de l'ensemble de labels rend la réponse la même quel que soit l'ordre d'arrivée des événements.</li> <li><strong>Livré est un état de label comme les autres.</strong> La carte se déplace quand l'issue reçoit <code>roadmap:shipped</code>, ou est fermée alors qu'elle le porte. La carte elle-même ne lie pas vers l'entrée de changelog ; l'entrée, rédigée à partir de la pull request qui a fermé l'issue, est l'endroit où vivent les détails.</li> <li><strong>Servez-la comme données.</strong> La roadmap est un document JSON avec ces trois colonnes, publié à côté du flux de changelog avec les mêmes en-têtes de cache, pour qu'un site docs, un widget ou une page de statut puissent la rendre sans seconde intégration. La <a href="https://changeloop.dev/docs">documentation du flux</a> a la forme exacte.</li> </ol> <p>Un label est peu demander à une mainteneuse, et c'est toute l'intégration. Aucun tableau à garder synchronisé, aucun outil séparé où se connecter, et la demande que la cliente a classée est l'élément sur la roadmap ; quand c'est livré, c'est le même élément.</p> <h2>Que ne devrait pas contenir une roadmap publique ?</h2> <p>Elle ne devrait pas contenir de dates, d'estimations, ni rien dont vous auriez honte qu'on vous demande dans neuf mois. Les dates sont l'erreur classique : un trimestre sur une roadmap devient un engagement dans un deck de vente devient un ticket appelé "vous avez dit Q3". Les colonnes disent assez. "En construction" signifie déjà "assez bientôt que quelqu'un y est".</p> <p>Elle ne devrait pas non plus contenir le backlog interne. Une roadmap avec trois cents éléments est un problème de recherche, pas une promesse, et la cliente qui trouve sa demande en position 212 a appris quelque chose que vous ne vouliez pas lui dire.</p> <h2>Comment la roadmap se connecte-t-elle au changelog ?</h2> <p>La roadmap et le changelog décrivent les mêmes issues de deux côtés, l'un pour l'avenir et l'autre pour le passé. Personne ne déplace une carte sur un tableau séparé. Une mainteneuse change le label sur l'issue sur laquelle elle travaillait déjà, l'entrée est rédigée à partir de la pull request, et quand une personne approuve cette entrée, une demandeuse dont le feedback via le widget est devenu cette issue y est prévenue. Déplacer la carte vers livré reste une étape à part, le label <code>roadmap:shipped</code>, alors intégrez-la à la même relecture ; approuver l'entrée ne le fait pas pour vous.</p> <p>C'est la même boucle que décrit l'<a href="https://changeloop.dev/blog/fr/customer-feedback-loop/">article sur la boucle de feedback</a> du côté du changelog ; la roadmap est ce que la cliente voit au milieu de ça. Le récap <a href="https://changeloop.dev/changelog-tools">outils de changelog</a> couvre quels produits offrent une vue roadmap et lesquels la traitent comme un tableau séparé, ce qui est la différence qui décide si elle reste exacte.</p> <h2>À quoi ressemble une bonne roadmap publique ?</h2> <p>Elle a l'air courte, et chaque élément dessus est une issue que n'importe qui peut ouvrir. Le test est de savoir si une cliente peut aller d'un élément à la discussion derrière lui, et d'un élément livré à l'entrée qui décrit ce qui a réellement changé. Une roadmap qui est une liste de noms de fonctionnalités sans entrée est une brochure.</p> <p>Un exemple travaillé, comme le JSON qu'un widget irait chercher :</p> <pre><code class="language-json">{ "columns": [ { "column": "planned", "hasMore": false, "items": [ { "id": "6b0c1f...", "column": "planned", "publicTitle": "Saved views on the inbox", "publicDescription": "Keep a filter you use often and come back to it.", "publishedAt": "2026-09-16T10:04:11.000Z" } ]}, { "column": "building", "hasMore": false, "items": [ { "id": "71a4e2...", "column": "building", "publicTitle": "Roadmap column in the widget", "publicDescription": "See what is coming without leaving the page.", "publishedAt": "2026-09-12T08:20:02.000Z" } ]}, { "column": "shipped", "hasMore": false, "items": [ { "id": "5c9d70...", "column": "shipped", "publicTitle": "Feedback filed as labelled issues", "publicDescription": "Widget submissions arrive as issues your triage already handles.", "publishedAt": "2026-09-02T15:41:37.000Z" } ]} ], "enabled": true, "language": "en" } </code></pre> <p>Trois éléments sur trois colonnes forment une roadmap publique parfaitement bonne. Elle dit ce qui arrive, ce qui se passe, et ce qui s'est passé, et chaque ligne est vérifiable. Cinq autres formats, de Now/Next/Later à la roadmap par résultats, sont présentés avec des exemples d'éléments dans <a href="https://changeloop.dev/blog/fr/product-roadmap-examples/">exemples de roadmap produit</a>.</p> <h2>FAQ</h2> <p><strong>Combien d'éléments une roadmap publique devrait-elle avoir ?</strong> Le moins possible que vous puissiez défendre. Moins de dix au total est normal pour un petit produit ; plus de trente en "planifié" est un backlog déguisé en roadmap.</p> <p><strong>Une roadmap publique devrait-elle avoir des dates ?</strong> Non. Les colonnes communiquent une séquence sans créer d'échéance. Si une cliente a besoin d'une date, c'est une conversation, pas un élément de roadmap.</p> <p><strong>Les clients devraient-ils voter sur les éléments de la roadmap ?</strong> Les votes mesurent qui s'est présenté, pas ce qui compte. Un commentaire sur l'issue expliquant la solution de contournement qu'ils utilisent aujourd'hui vaut plus que cinquante votes, et ça coûte quelque chose à qui vote, ce qui est le point.</p> <p><strong>Que se passe-t-il pour un élément de roadmap annulé ?</strong> Retirez le label et dites pourquoi sur l'issue. Un "on ne va pas faire ça" public fait partie de la boucle, et c'est le message que la plupart des équipes n'envoient jamais.</p> </article> <article> <h1>Automatisation du changelog, et ses limites</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>L'automatisation du changelog fonctionne quand elle automatise la collecte, la classification et la publication, et s'arrête à la sélection et à la formulation. Automatisez tout et vous livrez un git log formaté ; n'automatisez rien et le changelog est écrit par rafales, de mémoire, avant les versions. La question utile est quelles parties automatiser, pas combien.</p> <p>Les projets d'automatisation de changelog échouent dans une de deux directions, et les deux sont prévisibles dès la première réunion de design. Automatisez trop peu et le changelog est un document que quelqu'un est censé mettre à jour, ce qui signifie qu'il est mis à jour par rafales, par quiconque a tiré la courte paille. Automatisez trop et ça devient un git log formaté : complet, précis, et lu par personne.</p> <h2>Quelles parties d'un changelog devraient être automatisées ?</h2> <p>Trois des quatre étapes. Collecte et publication complètement ; classification comme première passe avec dérogation humaine ; sélection et formulation jamais.</p> <table> <thead> <tr> <th>Étape</th> <th>Automatiser ?</th> <th>Pourquoi</th> </tr> </thead> <tbody><tr> <td>Collecte : changements depuis commits, PR, tickets vers une liste</td> <td>Complètement</td> <td>Fastidieux, sauté sous délai, les machines le font parfaitement</td> </tr> <tr> <td>Classification : Added, Fixed, Changed, Deprecated, Removed, Security</td> <td>Première passe, dérogation humaine</td> <td>Environ 80% correct depuis les métadonnées seules ; les 20% faux sont les entrées qui comptent</td> </tr> <tr> <td>Sélection et formulation : quoi dire au lecteur, et comment</td> <td>Jamais</td> <td>C'est toute la valeur de l'artefact</td> </tr> <tr> <td>Publication : page, flux, email, widget, Slack</td> <td>Complètement, depuis une source</td> <td>Où va la majorité de l'effort manuel réel</td> </tr> </tbody></table> <p><strong>Collecte.</strong> Sortir les changements de l'endroit où ils se produisent (commits, PR, tickets) et les mettre dans une liste. Automatisez ça complètement. Les humains sont mauvais pour ça, c'est fastidieux, et c'est l'étape sautée sous délai. <a href="https://changeloop.dev/blog/fr/conventional-commits-changelog/">Conventional commits</a> ou les labels de PR sont la matière première habituelle.</p> <p><strong>Classification.</strong> Décider si quelque chose est Added, Fixed, Changed, Deprecated, Removed ou Security. Automatisez la première passe depuis le type de commit ou le label de PR, et laissez un humain déroger. La précision ici tourne autour de quatre-vingts pour cent depuis les métadonnées seules, et les vingt pour cent faux se concentrent exactement sur les entrées qui comptent, parce que l'ambiguïté corrèle avec l'importance.</p> <p><strong>Sélection et formulation.</strong> Décider ce qu'un lecteur devrait savoir et comment le dire. <strong>N'automatisez pas ça.</strong> C'est toute la valeur de l'artefact. Tout le reste est de la logistique.</p> <p><strong>Publication.</strong> Amener les entrées finies vers une page, un flux, un email, un widget in-app, un canal Slack. Automatisez complètement, et depuis une source. C'est là que va la majorité de l'effort manuel réel, et presque personne ne le compte. C'est aussi l'étape qui peut dire à la personne qui a demandé le changement qu'il a été livré, ce qui est tout le sujet de <a href="https://changeloop.dev/blog/fr/customer-feedback-loop/">fermer la boucle de feedback depuis le changelog</a>. La moitié email de cette étape a sa propre forme, dans <a href="https://changeloop.dev/blog/fr/product-update-email/">le modèle d'email de mise à jour produit</a>.</p> <p>Ce dernier point mérite qu'on s'y arrête. Les équipes tendent à voir le changelog comme un problème d'écriture, puis passent la majorité de leur temps sur la distribution : copier des entrées dans un outil email, reformater pour l'in-app, coller dans Slack, mettre à jour une page docs. L'écriture prend une heure. La copie prend une heure à chaque version, pour toujours, et c'est la partie qu'une machine devrait avoir.</p> <h2>Que se passe-t-il quand la ligne bouge ?</h2> <p><strong>Déplacez-la vers le haut et vous obtenez un dump de git.</strong> L'automatisation totale depuis les commits produit <code>bump deps</code>, <code>fix flaky test</code>, <code>wip</code> et <code>address review comments</code> devant les clients. Chaque équipe qui a fait ça a ensuite ajouté un filtre, et le filtre est une étape de sélection réintroduite sous un autre nom, avec une pire ergonomie.</p> <p><strong>Déplacez-la vers le bas et vous obtenez des rafales.</strong> La collecte totalement manuelle signifie que les entrées sont écrites de mémoire au moment de la version. C'est le mode contre lequel <a href="https://changeloop.dev/blog/fr/keep-a-changelog-implemented/">Keep a Changelog</a> avertit dès le début, et ça se dégrade silencieusement : le changelog paraît entretenu jusqu'à la semaine où personne n'a eu le temps.</p> <h2>À quoi ressemble un pipeline d'automatisation de changelog ?</h2> <p>Quatre étapes, avec exactement une porte humaine, placée là où un brouillon devient public.</p> <ol> <li>Au merge, dérivez une entrée brouillon de la PR : type depuis le label ou le préfixe de commit, titre comme premier brouillon, lien retour vers la PR, autrice enregistrée. Faites-la atterrir dans un bac non publié.</li> <li>N'importe qui peut éditer n'importe quel brouillon à n'importe quel moment, et éditer est bon marché. La plupart reçoivent une ligne réécrite.</li> <li>Tailler une version exige que chaque entrée du bac soit soit éditée soit explicitement marquée interne. Cette porte est tout le design. Sans elle, les brouillons sont livrés non édités la semaine chargée.</li> <li>Publier est un fan-out depuis l'ensemble publié : la page publique, le flux, l'email, le widget, le post Slack. Une source, plusieurs rendus, pas de copie.</li> </ol> <p>L'étape 3 est le seul endroit où une personne est requise, et elle prend environ dix minutes par version une fois que les brouillons sont corrects. Là où une demande de cliente est impliquée, le brouillon porte aussi l'issue qu'il ferme, ce qui est ce qui permet à l'étape 4 d'avertir la demandeuse ; la <a href="https://changeloop.dev/blog/fr/feature-request-template/">template de demande de fonctionnalité</a> est conçue pour que ce lien survive. La place de cette étape dans le flux de release plus large fait l'objet du <a href="https://changeloop.dev/blog/fr/release-management-process/">processus de release management</a>.</p> <h2>Que demande l'automatisation à vos données ?</h2> <p>Rien de tout ça ne fonctionne si le changelog est un fichier Markdown, parce qu'un fichier ne peut pas être rendu sur cinq surfaces sans être reparsé, et parser de la prose est comment on finit avec un widget qui affiche la moitié d'un titre.</p> <p>Les entrées doivent être structurées : un type, une date, une version ou identifiant de release, une audience, un corps et un lien. Alors le fichier, la page, le flux et l'email sont tous des vues. Ce point structurel est la seule chose qui vaut la peine d'être bien faite avant de choisir un outil, parce que c'est ce qu'on ne peut pas rajouter après bon marché. Rien de tout ça ne fonctionne si une entrée n'est pas vraiment créée pour chaque changement qui en a besoin ; <a href="https://changeloop.dev/blog/fr/changelog-ci-enforcement/">exiger une entrée de changelog en CI</a> couvre comment faire refuser un merge sans entrée par le pipeline, au lieu de laisser cette étape à la mémoire.</p> <p>On construit <a href="https://changeloop.dev/">changeloop</a>, où le changelog est d'abord un flux puis une page, donc lisez ça comme un intérêt plutôt qu'une recommandation impartiale ; le <a href="https://changeloop.dev/pricing">pricing</a> est un repository gratuit sans carte, suffisant pour voir la forme. <a href="https://changeloop.dev/changelog-tools">Outils de changelog</a> est notre récap de ce qui existe d'autre, y compris les produits avec lesquels on est en concurrence, et le <a href="https://changeloop.dev/changelog-generator">générateur de changelog</a> fait les étapes de collecte et classification dans le navigateur si vous voulez voir la dérivation avant de vous engager dans un pipeline.</p> <h2>Le test</h2> <p>Comptez les minutes entre un changement mergé et ce changement visible pour une cliente qui ne lit pas votre repo. Si la plupart de ces minutes, c'est quelqu'un qui copie du texte entre outils, l'automatisation dont vous avez besoin est dans la publication, pas dans l'écriture.</p> <h2>FAQ</h2> <p><strong>L'IA peut-elle écrire le changelog ?</strong> Elle peut en rédiger un brouillon. Un modèle à qui on donne la pull request mergée produit la plupart du temps un premier brouillon utilisable du titre et du corps, ce qui est la collecte et la classification mieux faites. La sélection, si dire quelque chose à un lecteur, et la formulation finale, ont toujours besoin de la personne qui connaît l'audience, et un pipeline qui publie des brouillons sans cette porte a automatisé la mauvaise étape.</p> <p><strong>Quelle est la différence entre un générateur de changelog et l'automatisation du changelog ?</strong> Un générateur transforme des commits en une liste formatée une fois, à la demande. L'automatisation tourne à chaque merge, maintient un bac non publié, conditionne la version à une revue humaine, et publie sur chaque surface depuis une source. Le générateur est la première étape du pipeline, exécutée à la main.</p> <p><strong>Le changelog devrait-il être automatisé depuis les commits ou les pull requests ?</strong> Depuis les pull requests, où l'unité de changement est la PR : le titre et la description sont écrits une fois, pour tout le changement, et la PR lie l'issue qu'elle ferme. La dérivation basée sur les commits fonctionne quand le commit est l'unité et suit une convention.</p> <p><strong>Comment empêche-t-on l'automatisation de publier des changements internes ?</strong> Classifiez <code>chore</code>, <code>ci</code>, <code>test</code>, <code>refactor</code> et les mises à jour de dépendances comme internes par défaut, et faites de la promotion vers public un acte délibéré. Le défaut inverse, public sauf si quelqu'un le cache, est comment <code>bump deps</code> atteint les clients.</p> </article> <article> <h1>Changelog vs release notes : quelle est la différence ?</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>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.</p> <p>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.</p> <h2>Changelog vs release notes, côte à côte</h2> <table> <thead> <tr> <th></th> <th>Changelog</th> <th>Release notes</th> </tr> </thead> <tbody><tr> <td>Lecteur</td> <td>Quelqu'un qui cherche quelque chose</td> <td>Quelqu'un qui décide si ça le concerne</td> </tr> <tr> <td>Portée</td> <td>Tout ce qui a changé</td> <td>Ce qui vaut la peine d'être dit sur cette version</td> </tr> <tr> <td>Cadence</td> <td>Continue, par merge ou par version</td> <td>Par version, et seulement celles qui méritent d'être annoncées</td> </tr> <tr> <td>Ton</td> <td>Concis, factuel, souvent impératif</td> <td>Explicatif, parfois persuasif</td> </tr> <tr> <td>Durée de vie</td> <td>Permanente, lue des années plus tard</td> <td>Lue la première semaine, puis archivée</td> </tr> <tr> <td>Vit dans</td> <td>Le repo, un site de docs, une page <code>/changelog</code></td> <td>Email, in-app, un article de blog, une page de version</td> </tr> <tr> <td>Échoue par</td> <td>Être incomplet</td> <td>Être ennuyeux, ou arriver après coup</td> </tr> </tbody></table> <h2>Qu'est-ce qu'un changelog ?</h2> <p>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 <a href="https://changeloop.dev/blog/fr/keep-a-changelog-implemented/">Keep a Changelog</a> consacre l'essentiel de son unique page à la structure et presque rien à la prose.</p> <h2>Que sont les release notes ?</h2> <p>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. <a href="https://changeloop.dev/blog/fr/how-to-write-release-notes/">Comment écrire des release notes</a> traite de la sélection et de la formulation.</p> <h2>Faut-il un changelog et des release notes ?</h2> <p>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 <code>/changelog</code> 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.</p> <p>La division vaut la peine quand ça commence à arriver :</p> <ul> <li>Vos entrées de changelog ont développé des paragraphes explicatifs que les développeurs scrollent sans lire.</li> <li>Ou l'inverse : vos annonces de version ont commencé à lister des mises à jour de dépendances.</li> <li>Le support copie des entrées dans des emails et les réécrit au passage.</li> <li>Quelqu'un demande "juste les changements cassants" et vous ne pouvez pas les filtrer.</li> </ul> <p>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.</p> <h2>Une source, deux vues</h2> <p>L'erreur est de les traiter comme deux documents. Ce sont deux vues sur le même ensemble de changements.</p> <p>É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.</p> <p>Ç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. <a href="https://changeloop.dev/blog/fr/changelog-automation/">Automatisation du changelog</a> 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.</p> <h2>Si vous n'avez le temps que pour un seul</h2> <p>É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.</p> <p>Gardez-le dans un format fixe pour que la dérivation reste possible. Notre page <a href="https://changeloop.dev/changelog-examples">exemples de changelog</a> rassemble des entrées d'équipes qui font ça bien, et la <a href="https://changeloop.dev/release-notes-template">release notes template</a> est la forme qu'on utilise en transformant un ensemble d'entrées en quelque chose qui vaut la peine d'être envoyé.</p> <h2>Une note sur les noms</h2> <p>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.</p> <p>Sur quelle surface le résultat atterrit est une décision à part, couverte dans <a href="https://changeloop.dev/blog/fr/changelog-page/">construire une page de changelog</a>.</p> <h2>FAQ</h2> <p><strong>Un changelog est-il la même chose que les release notes ?</strong> 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.</p> <p><strong>Peut-on générer des release notes à partir d'un changelog ?</strong> 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é.</p> <p><strong>Où devrait vivre un changelog ?</strong> Quelque part de permanent et liable auquel la lectrice peut accéder sans repository : une page <code>/changelog</code>, un site de docs, ou un flux qui se rend à plusieurs endroits. Un <code>CHANGELOG.md</code> seul atteint les contributeurs, pas les clients.</p> <p><strong>Un changelog devrait-il inclure les changements internes ?</strong> 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.</p> </article> <article> <h1>Des conventional commits à un changelog</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Les conventional commits offrent gratuitement trois choses à un changelog : le type de chaque changement, la partie du système touchée, et si ça casse quelque chose. Ils n'offrent rien d'autre. La formulation, le regroupement et la sélection, qui sont le changelog, restent entièrement ouverts, et un pipeline qui prétend le contraire livre un git log formaté.</p> <pre><code>feat(exports): add CSV column selection fix(auth): reject expired refresh tokens chore(deps): bump node-pg to 8.11 </code></pre> <p>Trois commits au format <a href="https://www.conventionalcommits.org/">Conventional Commits</a>. À partir de ceux-ci, une machine peut vous dire qu'un est une fonctionnalité, un est une correction, un est du ménage, et quelle partie du système chacun a touché. C'est vraiment utile, et c'est toute la promesse de la convention : un historique de commits lisible par autre chose qu'une personne. L'erreur est de penser que ça vous donne un changelog. Ça vous donne la matière première.</p> <h2>Que spécifie la convention ?</h2> <p>Un type, un scope optionnel, et une description : <code>type(scope): description</code>. Les types sont conventionnellement <code>feat</code>, <code>fix</code>, <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>perf</code>, <code>build</code>, <code>ci</code>. Deux choses marquent un changement cassant : un <code>!</code> avant les deux-points, ou un footer <code>BREAKING CHANGE:</code>. Les outils se basent sur <code>feat</code> et <code>fix</code> pour les bumps de version mineure et patch, et sur le marqueur breaking pour une majeure.</p> <table> <thead> <tr> <th>Le commit vous donne</th> <th>Le changelog a besoin de</th> <th>Qui comble l'écart</th> </tr> </thead> <tbody><tr> <td><code>feat</code> / <code>fix</code> / <code>chore</code></td> <td>Added / Fixed / interne</td> <td>Un mapping, automatique</td> </tr> <tr> <td><code>(scope)</code></td> <td>Un regroupement que le lecteur reconnaît</td> <td>Une personne, une fois par scope</td> </tr> <tr> <td><code>!</code> ou <code>BREAKING CHANGE:</code></td> <td>Qui casse, pour quand, et quoi faire</td> <td>Une personne, à chaque fois</td> </tr> <tr> <td>La description, écrite pour une revieweuse</td> <td>Le résultat, écrit pour une cliente</td> <td>Une personne, chaque entrée</td> </tr> <tr> <td>Un commit</td> <td>Un changement, qui peut être plusieurs commits</td> <td>Règles de squash, ou une personne</td> </tr> </tbody></table> <p>Le marqueur le dit à l'outil ; il ne le dit pas à l'appelant, ce qui est le sujet de <a href="https://changeloop.dev/blog/fr/api-deprecation/">comment déprécier une API</a> et <a href="https://changeloop.dev/blog/fr/breaking-changes/">qu'est-ce qu'un changement cassant</a>. C'est une petite spec et ça vaut la peine de la suivre même si vous n'en générez jamais rien, parce qu'elle force une décision par commit : est-ce un changement que les utilisateurs voient, ou non.</p> <h2>Où s'arrêtent les conventional commits ?</h2> <p>Ils s'arrêtent à la phrase. Tout ce que la convention capture, ce sont des métadonnées sur un changement ; le changement lui-même est toujours décrit dans le vocabulaire d'une revieweuse.</p> <p><strong>Les messages de commit sont écrits pour des revieweuses.</strong> <code>fix(auth): reject expired refresh tokens</code> est correct et ne dit rien à une cliente. La lectrice d'un changelog veut "vous serez déconnecté quand une session a vraiment expiré, au lieu de voir des 401 intermittents".</p> <p><strong>Les scopes sont internes.</strong> <code>exports</code>, <code>auth</code>, <code>ingest</code> sont des noms de modules. Ils sont stables, ce qui les rend bons pour regrouper, et sans signification pour quiconque en dehors de la codebase.</p> <p><strong>Un changement, c'est souvent plusieurs commits.</strong> Une fonctionnalité mergée sur onze commits produit onze entrées, dix desquelles du bruit, et les écraser pour cacher ça perd l'historique de revue.</p> <p><strong><code>chore</code> est un fourre-tout, pas une catégorie.</strong> Mises à jour de dépendances, changements CI et renommages atterrissent tous là, et certains comptent pour les utilisateurs alors que la plupart non.</p> <p>Donc : la convention vous donne gratuitement type, scope et statut breaking, et laisse la formulation, le regroupement et la sélection entièrement ouverts. Ces trois-là sont le changelog. <a href="https://changeloop.dev/blog/fr/changelog-entry-ownership/">À qui appartient vraiment une entrée de changelog</a> couvre qui devrait s'occuper de cette formulation, ce regroupement et cette sélection, puisque la convention elle-même n'a aucun avis là-dessus.</p> <h2>Comment génère-t-on un changelog à partir de conventional commits ?</h2> <p>En deux couches, et la seconde doit être obligatoire.</p> <p><strong>Couche un, automatique.</strong> Au merge, dérivez une entrée brouillon du commit : type mappé sur un type de changelog (<code>feat</code> sur Added, <code>fix</code> sur Fixed, un marqueur breaking sur Changed plus un flag), scope gardé comme métadonnée plutôt que comme texte, lien vers la PR. Faites-la atterrir dans la section Unreleased que demande <a href="https://changeloop.dev/blog/fr/keep-a-changelog-implemented/">Keep a Changelog</a>.</p> <p><strong>Couche deux, humaine, et requise.</strong> Avant qu'une version sorte, chaque entrée brouillon reçoit soit une réécriture d'une ligne dans le vocabulaire de l'utilisateur, soit est marquée interne et retirée de la vue publique. C'est l'étape que les gens essaient de sauter, et la sauter est ce qui produit des changelogs qui se lisent comme un diff.</p> <p>Le détail de design important est que la couche deux n'est pas optionnelle dans le pipeline. Si une version peut être taillée avec des brouillons non édités, elle le sera, la semaine où tout le monde est occupé. Quelles étapes appartiennent à la machine et lesquelles à la personne, c'est tout le sujet de l'<a href="https://changeloop.dev/blog/fr/changelog-automation/">automatisation du changelog</a>.</p> <p>Tailler la release est aussi le moment où un tag git, une release et cette entrée de changelog s'accordent ou commencent à diverger ; <a href="https://changeloop.dev/blog/fr/git-tags-releases-changelog/">tags git, releases et votre changelog</a> couvre comment garder les trois synchronisés.</p> <h2>Trois pièges</h2> <p><strong>Les squash merges mangent les footers.</strong> Si votre plateforme écrase avec le titre de la PR comme message, le footer <code>BREAKING CHANGE:</code> d'un commit à l'intérieur de cette branche disparaît, et votre outillage cesse silencieusement de voir le changement cassant. Vérifiez ce que votre template de squash garde vraiment.</p> <p><strong>Les commits de revert produisent des entrées fantômes.</strong> Un <code>fix</code> qui est reverté le lendemain génère une entrée pour quelque chose qui n'a jamais été livré, sauf si la dérivation réconcilie les reverts. La plupart des outils ne le font pas.</p> <p><strong>Le bump de version et le changelog se désynchronisent.</strong> Si la version est calculée à partir des commits et le changelog écrit à la main après, ils divergent en environ deux versions. Calculez les deux dans la même passe ou acceptez que l'un des deux soit faux.</p> <h2>Si vous voulez la partie mécanique sans pipeline</h2> <p>Notre <a href="https://changeloop.dev/changelog-generator">générateur de changelog</a> fait l'étape de dérivation dans le navigateur : collez des commits, obtenez des entrées regroupées et typées en sortie. C'est délibérément déterministe et entièrement côté client, donc les commits que vous collez ne quittent jamais votre machine, ce qui compte quand les messages viennent d'un repository privé. Ça fait honnêtement la moitié collecte et ne tente pas la couche deux, parce que la couche deux est un jugement et un outil qui la simule produit exactement le changelog contre lequel cet article argumente.</p> <p>Pour la version pipeline, <a href="https://changeloop.dev/changelog-tools">outils de changelog</a> couvre ce qui existe.</p> <h2>Le résumé</h2> <p>Les conventional commits répondent "quel type de changement est-ce" de manière fiable et bon marché. Ils ne répondent pas "que devrait-on dire aux gens", et aucune quantité d'outillage au-dessus du message de commit ne le fera, parce que l'information n'a jamais été dans le message de commit. Budgétez la réécriture.</p> <h2>FAQ</h2> <p><strong>Les conventional commits génèrent-ils automatiquement un changelog ?</strong> Ils génèrent automatiquement un brouillon : entrées typées, avec scope, liées. La formulation pour une cliente, le regroupement et la décision de ce qu'il faut laisser de côté ont toujours besoin d'une personne, et un pipeline qui saute cette étape publie des messages de commit.</p> <p><strong>Quels types de conventional commit apparaissent dans un changelog ?</strong> <code>feat</code> et <code>fix</code> toujours, comme Added et Fixed. <code>perf</code> généralement, comme Changed. <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>build</code> et <code>ci</code> sont internes par défaut et n'apparaissent que si une personne en promeut un.</p> <p><strong>Comment les conventional commits marquent-ils un changement cassant ?</strong> Un <code>!</code> après le type ou le scope (<code>feat(api)!: ...</code>), ou un footer <code>BREAKING CHANGE:</code> dans le corps du commit. Les deux se perdent si un squash merge ne garde que le titre de la PR.</p> <p><strong>A-t-on besoin de conventional commits pour automatiser un changelog ?</strong> Non. Les labels de PR, les templates de PR et les liens d'issues portent les mêmes métadonnées pour les équipes qui mergent par pull request. Les conventional commits sont l'option la moins chère quand l'unité de changement est le commit.</p> </article> <article> <h1>Comment écrire des release notes que les gens lisent</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Pour écrire des release notes que les gens lisent, répondez à une question par entrée : qu'est-ce que la lectrice peut faire maintenant qu'elle ne pouvait pas avant, et que doit-elle faire à ce sujet. Mettez en premier tout ce qui a une échéance, nommez qui est concerné, dites "aucune action requise" quand c'est vrai, et sautez les versions qui n'ont rien à dire. Tout le reste de cette page est cette règle appliquée.</p> <blockquote> <p>Corrections de bugs et améliorations de performance.</p> </blockquote> <p>Chaque produit a publié ça un jour. La cause est rarement la paresse : c'est ce qu'on obtient quand les release notes sont écrites de l'intérieur, par quelqu'un qui a passé deux semaines dans le diff et ne peut plus voir quelles parties intéresseraient un inconnu. Un meilleur ton ne réglera pas ça ; répondre à la question, oui.</p> <h2>Que devraient inclure des release notes ?</h2> <p>Les release notes devraient inclure, pour chaque changement qui mérite d'être mentionné : ce que la lectrice peut faire maintenant, qui est concerné, ce qu'elle doit faire (y compris "rien"), et quand entre en vigueur ce qui a une échéance. Elles ne devraient pas inclure de numéros de tickets internes, de noms de composants que seule l'équipe utilise, ou un numéro de version comme seul titre.</p> <table> <thead> <tr> <th>Inclure</th> <th>Laisser de côté</th> </tr> </thead> <tbody><tr> <td>Le résultat, dans les termes de la lectrice</td> <td>L'implémentation, dans les termes de l'équipe</td> </tr> <tr> <td>Qui est concerné, par plan, rôle ou version d'API</td> <td>"Certains utilisateurs"</td> </tr> <tr> <td>L'action requise, ou "aucune action requise"</td> <td>Le silence, que la lectrice remplit par le pire scénario</td> </tr> <tr> <td>Une date pour tout ce qui a une échéance</td> <td>Un numéro de version en guise de date</td> </tr> <tr> <td>Un lien vers la doc qui explique</td> <td>Un lien vers la pull request</td> </tr> <tr> <td>Les bugs signalés, et la limite qui a été relevée</td> <td>Des id de tickets internes</td> </tr> <tr> <td>La section ennuyeuse, une ligne chacune, en bas</td> <td>La section ennuyeuse mélangée aux nouveautés</td> </tr> </tbody></table> <p>La séparation entre une release note et une <a href="https://changeloop.dev/blog/fr/changelog-vs-release-notes/">entrée de changelog</a> est ce qui rend cette liste possible : le changelog garde tout, donc les notes peuvent laisser des choses de côté. Des exemples annotés de chaque type d'entrée sont rassemblés dans <a href="https://changeloop.dev/blog/fr/release-notes-examples/">exemples de release notes</a>.</p> <h2>La question à laquelle répond chaque entrée</h2> <p><strong>Qu'est-ce que la lectrice peut faire maintenant qu'elle ne pouvait pas avant, et que doit-elle faire à ce sujet ?</strong></p> <p>Si une entrée ne peut pas répondre à ça, elle appartient au changelog et non aux release notes. Les deux moitiés comptent. La première moitié, c'est la valeur. La deuxième moitié, c'est celle que les équipes oublient, et c'est celle qui génère des tickets de support quand elle manque.</p> <p>Deux exemples de la seconde moitié qui fait un vrai travail :</p> <ul> <li>"Les webhooks existants continuent de fonctionner jusqu'au 1er novembre. Après cette date, les payloads non signés seront rejetés."</li> <li>"Aucune action requise. Les exports existants sont automatiquement réencodés la prochaine fois que vous les ouvrez."</li> </ul> <p>Le second dit explicitement "aucune action requise". Cette phrase vaut la peine d'être écrite à chaque fois, parce qu'une lectrice qui ne la trouve pas suppose le pire.</p> <h2>Comment devrait-on ordonner des release notes ?</h2> <p>Ordonnez-les par conséquence pour la lectrice, jamais par la partie du système qui a changé. Regrouper par API, dashboard, mobile et infrastructure, c'est votre organigramme, pas le problème de la lectrice.</p> <ol> <li><strong>Les changements cassants et tout ce qui a une échéance.</strong> En premier, toujours, même si c'est petit. Si une lectrice arrête de lire après une ligne, c'est celle-là qu'elle devait avoir lue. Si l'échéance est un sunset, l'entrée devrait ressembler à un <a href="https://changeloop.dev/blog/fr/api-deprecation/">avis de dépréciation</a>.</li> <li><strong>Ce qui est nouveau et qu'elles voudront.</strong> Un par paragraphe, avec le résultat dans la première proposition.</li> <li><strong>Ce qui s'est amélioré.</strong> Les bugs signalés, les limites relevées, les choses qui étaient lentes.</li> <li><strong>Tout le reste, en liste.</strong> Mises à jour de dépendances, refactors internes, copy mineur. Une ligne chacune. Personne ne lit cette section, et elle devrait quand même être là, parce que la personne qui la cherche en a vraiment besoin.</li> </ol> <h2>La réécriture</h2> <p>Avant :</p> <blockquote> <p><strong>v4.2.0</strong> Correction d'un problème où l'endpoint <code>POST /exports</code> renvoyait de manière intermittente 500 sous charge. Refactorisation du worker d'export. Mise à jour de <code>node-pg</code> en 8.11. Amélioration de la gestion d'erreurs dans le sérialiseur CSV.</p> </blockquote> <p>Après :</p> <blockquote> <p><strong>Les exports ne plantent plus sur les gros comptes.</strong> Les comptes de plus de 50 000 lignes environ pouvaient recevoir un 500 au démarrage d'un export, plus souvent en fin de mois. C'est corrigé, et les exports de toute taille se relancent maintenant tout seuls plutôt que d'échouer. Aucune action requise, et tout export qui a échoué la semaine dernière peut simplement être relancé.</p> <p>Aussi dans la 4.2.0 : <code>node-pg</code> 8.11, erreurs plus claires dans le sérialiseur CSV.</p> </blockquote> <p>Même version. La seconde nomme le compte concerné, le moment où c'était le pire, ce qui a changé, et quoi faire. La mise à jour de dépendance n'a pas disparu, elle a juste cessé d'être le titre. L'article <a href="https://changeloop.dev/blog/fr/release-notes-best-practices/">bonnes pratiques des release notes</a> a le reste des règles que suit cette réécriture, chacune avec ce qu'il en coûte de la sauter.</p> <h2>Choses qui valent la peine d'être supprimées</h2> <ul> <li><strong>"Nous sommes ravis d'annoncer."</strong> La lectrice n'est pas encore ravie. Gagnez-la dans la phrase suivante.</li> <li><strong>Numéros de tickets internes.</strong> <code>PROJ-4471</code> ne signifie rien hors de votre tracker. Si l'entrée a besoin d'une référence, liez la page de doc.</li> <li><strong>Noms de composants que seule votre équipe utilise.</strong> Si vous avez renommé le "pipeline d'ingest", dites "imports".</li> <li><strong>Un numéro de version comme seul titre.</strong> <code>v4.2.0</code> est une étiquette d'archivage, pas un résumé.</li> <li><strong>Captures d'écran d'une page de réglages que personne n'a jamais visitée.</strong> Montrez ce qui a changé, en usage.</li> </ul> <h2>À quelle fréquence devrait-on publier des release notes ?</h2> <p>Publiez quand quelque chose s'est passé, pas selon un calendrier. Des notes qui arrivent à chaque version entraînent tout le monde à les ignorer. Des notes qui arrivent quand quelque chose s'est passé se font ouvrir. C'est correct, et généralement juste, de livrer une version sans aucune note et de faire rouler ses entrées dans le prochain lot qui a un titre qui vaut la peine d'être lu.</p> <p>Le changelog continue de tout enregistrer. C'est la répartition du travail : le changelog est complet, les notes sont sélectives. Si vous gardez le changelog structuré au fil de l'eau, écrire les notes devient de la sélection et de la réécriture plutôt que de l'archéologie.</p> <p>La <a href="https://changeloop.dev/release-notes-template">release notes template</a> est la forme qu'on utilise pour l'étape de sélection, et <a href="https://changeloop.dev/changelog-examples">exemples de changelog</a> rassemble des entrées d'équipes dont le changelog est assez bon pour en dériver des notes.</p> <p>Tout ça suppose une page qu'on contrôle entièrement, sans limite de longueur et avec des liens qui fonctionnent. <a href="https://changeloop.dev/blog/fr/mobile-app-release-notes/">Release notes mobiles</a> couvre ce qui change quand la surface est une fiche App Store ou Play Store. <a href="https://changeloop.dev/blog/fr/emergency-release-notes/">Release notes d'urgence</a> couvre l'autre exception : ce qui change quand il ne reste plus du tout de temps pour suivre le processus normal de rédaction.</p> <h2>Un test avant de publier</h2> <p>Lisez les notes comme quelqu'un qui a été en vacances deux semaines et a 40 secondes. Si dans ce temps, cette personne ne peut pas dire si quelque chose lui est demandé, les notes ne sont pas finies, aussi précises soient-elles.</p> <h2>FAQ</h2> <p><strong>Combien de temps devraient durer des release notes ?</strong> Autant que le nécessitent les changements à conséquences, et pas une ligne de plus. Une version avec un changement cassant et deux améliorations, c'est trois paragraphes. Gonfler une version tranquille pour la faire paraître substantielle, c'est comment les lecteurs apprennent à sauter les notes.</p> <p><strong>Qui devrait écrire les release notes ?</strong> La personne qui comprend le changement, éditée par quelqu'un qui ne le comprend pas. L'ingénieure sait ce qui a changé ; l'éditrice sait ce qu'un inconnu comprendra de travers. Écrire l'entrée au moment du merge, pendant que l'ingénieure s'en souvient encore, est la pratique qui rend tout ça bon marché.</p> <p><strong>Les release notes devraient-elles inclure des corrections de bugs ?</strong> Oui, celles que quelqu'un a signalées ou subies. Indiquez le symptôme vu par la lectrice, pas la cause. "Les exports de plus de 50 000 lignes échouaient" est une correction qu'une lectrice reconnaît ; "correction d'une race condition dans le worker d'export" est un message de commit.</p> <p><strong>Quelle est la différence entre des release notes et un changelog ?</strong> Le changelog est le registre complet et continu ; les release notes sont le message sélectionné sur une version, écrit pour des gens qui n'ont pas encore décidé si ça les intéresse. La réponse plus longue est dans <a href="https://changeloop.dev/blog/fr/changelog-vs-release-notes/">changelog vs release notes</a>.</p> </article> <article> <h1>Keep a Changelog, vraiment implémenté</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Keep a Changelog est une convention d'une page pour un <code>CHANGELOG.md</code> : version la plus récente en premier, une section par version avec un numéro et une date ISO, entrées regroupées sous six types (Added, Changed, Deprecated, Removed, Fixed, Security), et une section Unreleased en haut pour les entrées entre les versions. La plupart des équipes qui la citent en implémentent environ deux tiers, et le tiers qu'elles laissent tomber est celui qui protège leurs utilisateurs.</p> <p>Olivier Lacan a publié <a href="https://keepachangelog.com/">Keep a Changelog</a> en 2014 avec une phrase qui a mieux vieilli que la plupart de la prose logicielle : <em>don't let your friends dump git logs into changelogs</em>. Dix ans plus tard, c'est ce qui se rapproche le plus d'un standard dans ce coin du logiciel. Ça vaut la peine de lire la source plutôt qu'un résumé ; ceci traite des parties abandonnées.</p> <h2>Que demande Keep a Changelog ?</h2> <p>Un <code>CHANGELOG.md</code> à la racine du repo, le plus récent en premier, avec une section par version. Chaque version porte un numéro et une date ISO, et regroupe ses entrées sous six types :</p> <table> <thead> <tr> <th>Type</th> <th>Pour</th> <th>Ce que ça coûte de l'abandonner</th> </tr> </thead> <tbody><tr> <td>Added</td> <td>Nouvelles fonctionnalités</td> <td>Rien ; personne n'abandonne celui-là</td> </tr> <tr> <td>Changed</td> <td>Changements de comportement existant</td> <td>Les lecteurs découvrent un changement de comportement par une erreur</td> </tr> <tr> <td>Deprecated</td> <td>Fonctionnalités sur le point d'être supprimées</td> <td>Une suppression devient un incident plutôt qu'un événement planifié</td> </tr> <tr> <td>Removed</td> <td>Fonctionnalités supprimées dans cette version</td> <td>Personne ne distingue une suppression d'un bug</td> </tr> <tr> <td>Fixed</td> <td>Corrections de bugs</td> <td>Rien ; personne n'abandonne celui-là non plus</td> </tr> <tr> <td>Security</td> <td>Vulnérabilités</td> <td>La seule lectrice qui le cherchait ne le trouve pas</td> </tr> </tbody></table> <p>Plus une section <code>Unreleased</code> en haut, pour qu'il y ait un endroit où mettre une entrée dès qu'elle est mergée, et pour que n'importe qui puisse voir ce qui arrive.</p> <p>C'est à peu près tout. Le reste, c'est le raisonnement : les entrées sont pour des humains, une entrée par changement, et le fichier est un document plutôt qu'un log.</p> <h2>Quelles parties de Keep a Changelog sont abandonnées ?</h2> <p>La section Unreleased, puis quatre des six types, Security parmi eux, dans cet ordre.</p> <p><strong><code>Unreleased</code> disparaît en premier.</strong> C'est la section sans échéance, donc c'est celle dont l'entretien s'arrête en premier, et une fois partie les entrées sont écrites au moment de la version à partir de l'historique des commits. C'est précisément le dump de git log contre lequel la spec avertit dès le départ, atteint progressivement. <a href="https://changeloop.dev/blog/fr/changelog-automation/">Automatisation du changelog</a> consiste surtout à garder cette section vivante sans que personne ait à s'en souvenir.</p> <p><strong>Les six types s'effondrent en deux.</strong> La plupart des vrais changelogs finissent avec Added et Fixed, parce que Changed et Deprecated demandent un jugement sur ce que quelqu'un tenait pour acquis. Ce jugement est la partie précieuse. Deprecated en particulier est le seul type qui est une promesse sur l'avenir, et l'abandonner, c'est comment une suppression se transforme en incident ; la mécanique pour tenir cette promesse est dans <a href="https://changeloop.dev/blog/fr/api-deprecation/">comment déprécier une API</a>.</p> <p><strong>Security cesse d'être séparé.</strong> Une correction de sécurité classée sous Fixed est invisible pour la seule lectrice qui la cherchait. Gardez-la distincte même quand la correction est triviale, et surtout quand vous préféreriez ne pas y attirer l'attention.</p> <h2>Que ne répond pas la spec ?</h2> <p>C'est un format de fichier. Elle ne dit rien sur les questions qu'on rencontre immédiatement après l'avoir adoptée :</p> <ul> <li><strong>Comment quelqu'un l'apprend-il ?</strong> Un fichier dans un repo atteint les contributeurs. Il n'atteint pas une cliente qui n'a jamais ouvert GitHub.</li> <li><strong>Et les produits sans versions ?</strong> Un service déployé en continu n'a pas de v4.2.0 pour regrouper. La plupart des équipes substituent des dates, ce qui fonctionne, et la spec ne l'approuve ni ne l'interdit.</li> <li><strong>Qui écrit l'entrée ?</strong> La spec suppose qu'un humain le fait. Elle ne dit pas quand.</li> <li><strong>Et les audiences multiples ?</strong> Un fichier sert les développeurs. Il ne sert pas le même contenu à une administratrice non technique, et le reformater à la main pour elle est où commence la duplication. <a href="https://changeloop.dev/blog/fr/changelog-vs-release-notes/">Changelog vs release notes</a> est la division que la spec vous laisse faire vous-même.</li> </ul> <p><a href="https://common-changelog.org/">Common Changelog</a>, un fork plus strict de l'idée, resserre une partie de ça : il interdit certaines formulations d'entrées, exige un lien vers le changement, et a un avis tranché sur qui est le lecteur. Ça vaut la peine à lire si les parties floues de Keep a Changelog sont ce sur quoi votre équipe n'arrête pas de se disputer.</p> <h2>Peut-on automatiser Keep a Changelog sans dumper des git logs ?</h2> <p>Oui : dérivez le brouillon de commits structurés, mettez-le dans Unreleased avec son type pré-rempli, et exigez qu'un humain édite la formulation avant qu'une version soit taillée. L'avertissement de la spec concerne le résultat, pas l'outillage. Dériver un brouillon de commits, c'est correct. Publier ce brouillon non édité est ce à quoi elle s'oppose.</p> <p>La machine gère la collecte et le formatage, ce en quoi elle est bonne. L'humain gère la sélection et la formulation, ce en quoi elle ne l'est pas. <a href="https://changeloop.dev/blog/fr/conventional-commits-changelog/">Conventional commits</a> couvre la séparation en deux couches sur laquelle ça repose, et quels types de commit correspondent à quelles des six catégories ci-dessus. Notre récap <a href="https://changeloop.dev/changelog-tools">outils de changelog</a> couvre ce qui existe pour la moitié collecte.</p> <h2>Où Keep a Changelog cesse-t-il d'être suffisant ?</h2> <p>Ça s'arrête à la distribution. Keep a Changelog est une bonne réponse à "à quoi devrait ressembler ce fichier". Ce n'est pas une réponse à "comment nos utilisateurs apprennent-ils ce qui a changé", parce qu'un fichier Markdown dans un repo est une stratégie de distribution qui ne fonctionne que si vos utilisateurs sont des contributeurs.</p> <p>C'est l'obstacle que la plupart des équipes rencontrent en second : le fichier va bien, et personne en dehors de l'équipe ne le lit. Le résoudre signifie que les entrées doivent devenir des données qui peuvent être rendues ailleurs, ce qui est un problème différent de formater un fichier, et la raison pour laquelle <a href="https://changeloop.dev/changelog-examples">exemples de changelog</a> rassemble des pages publiques de changelog plutôt que des fichiers de repository. Comment transformer ces entrées en quelque chose auquel les gens reviennent est couvert dans <a href="https://changeloop.dev/blog/fr/changelog-page/">construire une page de changelog</a>.</p> <p>Adoptez quand même la spec. Ça coûte un après-midi, ça rend le second problème traitable, et c'est toujours la meilleure page jamais écrite sur ce sujet.</p> <h2>FAQ</h2> <p><strong>Keep a Changelog est-il un standard ?</strong> C'est une convention largement adoptée, pas la spécification d'un organisme de normalisation. Les outils (scripts de release, linters, parsers) supposent souvent sa forme, au point que la suivre achète de la compatibilité.</p> <p><strong>Que met-on dans la section Unreleased ?</strong> Chaque entrée pour un changement qui a été mergé mais pas encore livré dans une version numérotée. Quand une version est taillée, la section est renommée avec la version et la date, et une nouvelle section Unreleased vide se place au-dessus.</p> <p><strong>Un changelog devrait-il utiliser le versionnage sémantique ?</strong> Keep a Changelog le recommande et ne l'exige pas. Les bibliothèques et les API en bénéficient ; un service déployé en continu substitue généralement des dates, ce que le format accommode.</p> <p><strong>Les corrections de sécurité devraient-elles être dans le changelog avant d'être publiques ?</strong> Ajoutez l'entrée quand la correction est livrée, avec assez de détail pour qu'une opératrice puisse agir et pas plus. Retarder l'entrée jusqu'à une date de divulgation coordonnée est normal ; l'omettre ne l'est pas.</p> </article> <article> <h1>Bonnes pratiques des release notes qui comptent</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Les bonnes pratiques de release notes qui comptent sont celles avec une conséquence attachée : écrire l'entrée au moment du merge, nommer qui est concerné, indiquer l'action requise même quand c'est aucune, dater les changements cassants, garder une entrée permanente par changement, regrouper par résultat, et garder la section ennuyeuse. Chacune change ce que fait le lecteur. La plupart des autres conseils sur ce sujet changent l'apparence des notes.</p> <p>Cherchez des bonnes pratiques de release notes et vous obtenez des conseils de style : soyez clair, soyez concis, utilisez un langage simple, ajoutez des captures d'écran. Rien de tout cela n'est faux et rien de tout cela ne change quoi que ce soit, parce qu'aucune équipe ne s'est jamais assise avec l'intention d'être peu claire. Les pratiques ci-dessous sont accompagnées de ce qu'il en coûte de les sauter, parce qu'une pratique sans mode d'échec attaché n'est qu'une préférence.</p> <table> <thead> <tr> <th>Pratique</th> <th>Ce que ça coûte de la sauter</th> </tr> </thead> <tbody><tr> <td>Écrire l'entrée au merge, pas à la version</td> <td>Les entrées reconstruites après disent "diverses améliorations"</td> </tr> <tr> <td>Nommer qui est concerné</td> <td>Chaque lecteur décide que ça ne le concerne pas</td> </tr> <tr> <td>Indiquer l'action requise, y compris "aucune"</td> <td>Quarante tickets de support identiques, et des lecteurs qui présument le pire</td> </tr> <tr> <td>Dater les changements cassants, ne pas les versionner</td> <td>L'échéance se découvre après être passée</td> </tr> <tr> <td>Une entrée permanente et liable par changement</td> <td>Personne ne peut répondre "quand ça a changé"</td> </tr> <tr> <td>Regrouper par résultat, pas par système</td> <td>Les lecteurs ont besoin de votre architecture pour trouver leur section</td> </tr> <tr> <td>Garder la section ennuyeuse</td> <td>La sécurité, la conformité et qui débogue une version perdent leur source</td> </tr> </tbody></table> <h2>Quelles sont les bonnes pratiques pour les release notes ?</h2> <p><strong>Écrivez l'entrée quand vous mergez, pas quand vous livrez.</strong> Coût de sauter ça : la personne qui reconstruit la version depuis l'historique des commits n'est pas celle qui a fait le changement, et elle devinera l'intention. Les entrées écrites deux semaines plus tard sont celles qui disent "diverses améliorations".</p> <p><strong>Dites qui est concerné, par nom.</strong> "Équipes sur le plan Business", "quiconque utilise l'API d'export v1", "installations self-hosted sur Postgres 14". Coût de sauter ça : chaque lecteur doit deviner si ça le concerne, et la plupart décideront que non.</p> <p><strong>Indiquez l'action requise, y compris quand c'est aucune.</strong> Coût de sauter ça : le support répond quarante fois à la même question, et les lecteurs qui n'ont pas demandé présument que quelque chose est requis et le repoussent.</p> <p><strong>Datez les changements cassants, pas de numéro de version.</strong> "Supprimé en v5" ne signifie rien pour quelqu'un qui ne sait pas quand v5 arrive. "Cesse de fonctionner le 1er novembre" est une date qu'on peut noter au calendrier. Coût de sauter ça : l'échéance se découvre après être passée. Ce qui compte comme telle, et la checklist pour la livrer, sont dans <a href="https://changeloop.dev/blog/fr/breaking-changes/">qu'est-ce qu'un changement cassant</a>.</p> <p><strong>Gardez une entrée permanente et liable par changement.</strong> Un email n'est pas une archive et un message Slack n'est pas une référence. Coût de sauter ça : personne ne peut répondre "quand ça a changé" six mois plus tard, vous non plus. L'email a quand même un rôle, couvert dans <a href="https://changeloop.dev/blog/fr/product-update-email/">le modèle d'email de mise à jour produit</a> ; il pointe vers l'entrée plutôt que de la remplacer.</p> <p><strong>Regroupez par résultat, pas par système.</strong> Coût de sauter ça : le lecteur doit garder votre architecture en tête pour savoir quelle section le concerne. L'ordre qui en découle est dans <a href="https://changeloop.dev/blog/fr/how-to-write-release-notes/">comment écrire des release notes</a>.</p> <p><strong>Gardez la section ennuyeuse.</strong> Les mises à jour de dépendances et les changements internes restent, en bas, une ligne chacun. Coût de sauter ça : l'équipe sécurité, la personne qui vérifie la conformité et celle qui débogue un décalage de version perdent leur unique source. Les entrées où l'on se trompe le plus souvent sont les correctifs ; <a href="https://changeloop.dev/blog/fr/bug-fix-release-notes/">release notes de correctifs</a> montre comment les rédiger pour que le lecteur sache s'il doit agir.</p> <h2>Quelles sont les bonnes pratiques de changelog, et en quoi diffèrent-elles ?</h2> <p>Un changelog est une référence, donc ses pratiques concernent la complétude et la structure plutôt que la persuasion. Les quatre qui comptent :</p> <ul> <li><strong>Un type d'entrée fixe par ligne.</strong> Added, Changed, Deprecated, Removed, Fixed, Security. Ce n'est pas un style maison, c'est un filtre : c'est ce qui permet de demander "juste les changements cassants". La convention <a href="https://changeloop.dev/blog/fr/keep-a-changelog-implemented/">Keep a Changelog</a> en est la source habituelle.</li> <li><strong>Une section non publiée.</strong> Où vivent les entrées entre le merge et la version. Son absence est la raison pour laquelle les équipes écrivent des entrées tardivement.</li> <li><strong>Des dates ISO.</strong> <code>2026-08-28</code>, pas <code>28/08/26</code>, qui signifie deux jours différents selon le lecteur.</li> <li><strong>Une entrée par changement, pas par commit.</strong> Trois commits qui corrigent un bug sont une entrée.</li> </ul> <p>Les deux artefacts sont comparés en détail dans <a href="https://changeloop.dev/blog/fr/changelog-vs-release-notes/">changelog vs release notes</a> ; la version courte est que les pratiques du changelog protègent la complétude et celles des release notes protègent l'attention. <a href="https://changeloop.dev/blog/fr/private-release-notes-enterprise/">Release notes privées pour clientes enterprise</a> couvre une version de ceci qui n'apparaît que lorsque vos clientes ne sont plus toutes sur le même build : les mêmes objectifs de complétude et d'attention, mais calibrés par compte plutôt que diffusés à toutes en même temps.</p> <h2>Trois qui sont du pur folklore</h2> <p><strong>Les emoji comme types d'entrée.</strong> Une fusée et une clé à molette ne sont pas une taxonomie. Ça a l'air propre et ça ne peut être ni filtré, ni trié, ni lu utilement par un lecteur d'écran. Utilisez des mots, et si vous voulez l'emoji, mettez-le après le mot.</p> <p><strong>Les numéros de version sémantique comme titres pour un produit hébergé.</strong> Semver est une promesse sur la compatibilité d'API. Pour un produit SaaS où personne ne choisit sa version, un numéro de version en titre est de l'archivage interne déguisé en actualité. Gardez semver dans le changelog et hors de l'annonce.</p> <p><strong>Publier selon un calendrier indépendamment du contenu.</strong> Des notes mensuelles sans rien dedans apprennent aux gens que vos notes sont du bruit. Publiez quand il y a quelque chose à dire. Le changelog couvre le reste.</p> <h2>Celle qui est vraiment difficile</h2> <p>Garder le changelog et l'annonce synchronisés, sans tout écrire deux fois.</p> <p>La plupart des équipes commencent avec une seule page, la divisent quand les audiences divergent, puis laissent silencieusement l'une des deux pourrir, généralement le changelog, parce que c'est celui sans échéance attachée. La sortie est structurelle plutôt que disciplinaire : gardez les entrées comme des données avec un type, une date et une audience, et traitez les deux surfaces comme des rendus de ça. Notre récap <a href="https://changeloop.dev/changelog-tools">outils de changelog</a> couvre ce qui existe pour ça, y compris les outils avec lesquels on est en concurrence, et la page <a href="https://changeloop.dev/beamer-alternative">alternative à Beamer</a> est la comparaison honnête face au widget dont partent la plupart des équipes.</p> <p>La <a href="https://changeloop.dev/release-notes-template">release notes template</a> est où vit l'étape de sélection une fois que les entrées existent.</p> <h2>Si vous n'en adoptez qu'une</h2> <p>Écrivez l'entrée au moment du merge, dans un format fixe, avec un type. Toutes les autres pratiques de cette page deviennent plus faciles une fois que celle-là est en place, et aucune ne survit sans elle.</p> <h2>FAQ</h2> <p><strong>Les release notes devraient-elles avoir des captures d'écran ?</strong> Seulement de ce qui a changé, en usage. Une capture d'une page de réglages que personne n'a jamais visitée ajoute du scroll, pas de l'information. Un texte qui nomme le résultat et le lecteur concerné bat une image qui ne montre ni l'un ni l'autre.</p> <p><strong>Comment écrit-on des release notes pour un changement cassant ?</strong> D'abord la date, ensuite les appelants concernés, puis l'action requise, puis la migration. Ne commencez jamais par le numéro de version. La forme complète, avec une entrée d'exemple, est dans <a href="https://changeloop.dev/blog/fr/breaking-changes/">qu'est-ce qu'un changement cassant</a>.</p> <p><strong>Les release notes devraient-elles être écrites par l'ingénierie ou le marketing ?</strong> Rédigées par l'ingénieur qui a fait le changement, au moment du merge, et éditées par quelqu'un qui les lit comme un inconnu. Ni l'un ni l'autre seul ne produit des notes sur lesquelles un client peut agir.</p> <p><strong>Quel est le format idéal de release notes ?</strong> D'abord les éléments avec échéance, puis les nouvelles capacités, puis les améliorations, puis une liste d'une ligne chacune pour le reste. La <a href="https://changeloop.dev/release-notes-template">release notes template</a> est ce format sous forme de page à remplir.</p> </article> </main></body></html>