Il existe deux sortes de journaux des modifications.
Le premier est généré à partir des messages de commit. On y trouve des lignes comme fix: handle null in resolver et chore: bump deps. Techniquement, c’est un relevé complet de ce qui a changé, et aucun utilisateur ne l’a jamais lu deux fois.
Le second est écrit pour la personne qui utilise votre produit. Il dit ce qu’on peut faire aujourd’hui et qu’on ne pouvait pas faire la semaine dernière. Il est court. Les gens s’y abonnent.
La différence ne vient pas des outils. Elle vient d’une décision : quelqu’un a considéré que le journal des modifications faisait partie du produit.
Donnez un type à chaque entrée
Le changement qui rapporte le plus, c’est de donner un type à chaque entrée. Kookee en utilise sept :
feature · fix · improvement · breaking · security · deprecated · other
Ce n’est pas de la décoration. Avec un type, le journal se filtre, et un journal filtrable sert plus d’un public :
// Nouveautés — pour les utilisateurs
const features = await kookee.changelog.list({
filter: { changelogType: 'feature' },
limit: 10,
});
// Ce qui va casser — pour les intégrateurs
const breaking = await kookee.changelog.list({ filter: { changelogType: 'breaking' } });Un ingénieur qui intègre votre API s’intéresse à breaking et à deprecated, et à rien d’autre. Un utilisateur s’intéresse à feature. Une équipe sécurité veut security sur une page à part. Une liste typée sert les trois ; une liste à plat n’en sert bien aucun.
Le type est un champ structuré, pas une colonne de l’entrée, et cela compte au moment de l’affichage. entry.type vaut la chaîne 'changelog' ; le type de changement se lit dans le tableau des champs :
import { fieldOptionKey, fieldStringValue } from '@kookee/sdk';
const releaseType = fieldOptionKey(entry.fields, 'changelogType'); // 'feature'
const version = fieldStringValue(entry.fields, 'version'); // '1.6.0'Donnez une version à chaque entrée
Le type répond à la question « quel genre de changement est-ce ? ». La version répond à « est-ce que je l’ai déjà ? », et c’est la vraie question d’un utilisateur qui arrive depuis un fil de support.
La version est un texte libre, elle accepte donc le schéma que vous utilisez : 1.6.0, 2024.11, v3-beta. Deux habitudes lui donnent de la valeur : en mettre une sur chaque entrée, et garder le même schéma partout. Un journal dont la moitié des entrées a une version donne l’impression d’un oubli, et c’en est un.
Filtrez sur une version exacte quand quelqu’un demande ce qui est sorti dans une version précise :
const release = await kookee.changelog.list({ filter: { version: '1.6.0' } });Les entrées arrivent de la plus récente à la plus ancienne. Si vous voulez plutôt un ordre strict par version — et c’est sans doute le cas pour une page de versions, puisque les dates trompent sur les correctifs rétroportés et les versions qui prennent du retard —, triez-les vous-même, car un tri de chaînes place 1.10.0 avant 1.9.0 :
const { data } = await kookee.changelog.list({ limit: 100 });
const byVersion = [...data].sort((a, b) =>
(fieldStringValue(b.fields, 'version') ?? '').localeCompare(
fieldStringValue(a.fields, 'version') ?? '',
undefined,
{ numeric: true },
),
);C’est numeric: true qui place 1.10.0 après 1.9.0.
Laissez les gens réagir
Chaque entrée du journal accepte des réactions emoji :
await kookee.changelog.react(entryId, { reactionType: 'fire', action: 'add' });On dirait une petite fonction sociale. En réalité, c’est la boucle de retours produit la moins chère que vous construirez jamais. Livrer dix choses par mois et voir les deux qui ont récolté toutes les réactions vous dit à quoi consacrer le mois suivant, et l’utilisateur n’y passe qu’un clic au lieu d’un questionnaire.
Écrivez l’entrée en même temps que la version
En pratique, l’échec ne vient pas d’entrées mal écrites, mais d’entrées écrites une semaine trop tard, de mémoire, toutes d’un coup. À ce moment-là, plus personne ne se souvient pourquoi le changement comptait, et on retombe par défaut sur le journal fait de messages de commit.
Dans Kookee, on rédige l’entrée pendant que la pull request est encore ouverte, et on la publie quand la version sort : pas de déploiement, pas de rebuild, pas de générateur de site statique à attendre. Rédigez-la dans le tableau de bord, ou depuis un assistant de code connecté via MCP : il lit les dernières entrées et écrit la suivante sur le même ton, avec son type et sa version, pour que vous la relisiez.
Ensuite, un seul appel suffit pour l’afficher où vous voulez :
const { data } = await kookee.changelog.list({ limit: 5 });Votre site marketing, le panneau « Nouveautés » de votre application, l’e-mail qui annonce la version. Une seule source, écrite une fois, par la personne qui a fait le changement.