Notes de version
Génération de CHANGELOG.md et changelog.json depuis les messages de commit, et ce que lrvo-update en tire.
Chaque package de l'écosystème livre ses notes de version dans son tarball npm. Les dépôts sont privés : sans ces fichiers, un client n'a aucun moyen de savoir ce qui change entre deux versions.
Ces pages s'adressent à qui publie un package @lrvo/*.
Les trois sorties
| Fichier | Destinataire | Emplacement chez le client |
|---|---|---|
CHANGELOG.md | Un humain. | node_modules/<package>/CHANGELOG.md |
changelog.json | lrvo-update, après installation. | node_modules/<package>/changelog.json |
Champ lrvo du package.json | lrvo-update, avant installation. | Le packument du registre. |
Le troisième mérite une explication. changelog.json vit dans le tarball, donc hors de portée sans téléchargement. Les champs de premier niveau d'un package.json, eux, atterrissent dans le packument : npm view @lrvo/[email protected] lrvo --json récupère le résumé en un appel, sans rien installer. C'est ce qui permet à lrvo-update de dire ce qui change avant de le faire.
Génération
npm run build:changelogLe script régénère l'intégralité de l'historique à chaque exécution. Il est idempotent, et une correction de convention se propage à toutes les versions d'un coup.
Il est appelé depuis release, pas depuis build : au moment du prepublishOnly, le commit de publication n'existe pas encore, et il faut l'historique git complet qu'un checkout d'intégration continue n'a pas toujours.
Bornes de version
Par ordre de préférence, les étiquettes v* puis les commits chore: bump version to X.Y.Z que produit npm run release. La seconde forme couvre tout l'historique antérieur à l'adoption des étiquettes.
L'ordre retenu est celui de l'historique git, jamais l'ordre numérique des versions. Le dépôt du core en est la démonstration : il a porté un autre nom avant LRVO, sa numérotation est montée jusqu'à 1.4.x puis a été réinitialisée à 1.0.0. Pour la même raison, le changelog s'arrête à l'ère de numérotation courante : une version dont le numéro est inférieur à celui de la borne précédente signale une réinitialisation, et tout ce qui la précède appartient à un autre cycle de vie du package.
Ce que le script déduit seul
| Champ | Source |
|---|---|
entries | Analyse des messages de commit selon la convention. |
breaking | ! après le type, ou pied BREAKING CHANGE:. |
envAdded / envRemoved | Comparaison des clés déclarées à chaque borne : src/core/doctor/env.js pour le core, manifest.envVars de src/index.js pour un module. |
templateChanged | Diff de templates/. @lrvo/start uniquement. |
action | Un db.server.js ou un fichier de migration touché donne npx lrvo-db migrate. Un changement de templates/, ou l'apparition d'une variable, donne npx lrvo-doctor --fix. |
La déduction depuis les fichiers touchés est la source principale, pas les pieds de commit. Un squash de pull request sous Gitea écrase les corps de commit et perdrait le pied.
Pieds de commit, en surcharge
Quand la déduction ne suffit pas, quatre pieds la complètent. Ils s'ajoutent, ils ne remplacent pas.
feat(database): ajoute le journal de migrations
Lrvo-Action: npx lrvo-db migrate
Lrvo-Env-Added: LRVO_UPDATE_CHECK
Lrvo-Env-Removed: LRVO_LEGACY_FLAG
Lrvo-Template: instrumentation.jsLes valeurs sont séparées par des virgules. Voir Commits pour la convention générale.
Commits hors convention
Le script n'abandonne jamais un commit et ne fait jamais échouer une publication. Un sujet qui ne suit pas la convention est classé en other et apparaît dans la section « Autres ». L'historique réel en contient déjà, par exemple des messages de fusion de pull request.
Un dépôt sans historique git produit un changelog vide et sort en 0.
Ce qui n'est pas rendu
Les commits chore, style et test restent dans entries du JSON mais n'apparaissent pas dans le CHANGELOG.md. Une version qui n'en contient que se résume à une ligne, « Maintenance interne, aucun changement de comportement ».
Pas d'agrégation à la construction
Le core ne rassemble pas les changelogs des modules. Il ne peut pas : leurs dépôts sont séparés, privés, et parfois pas clonés. Tout instantané copié dans dist/ serait périmé dès la première publication d'un module.
L'agrégation se fait à l'exécution, dans lrvo-update, qui lit les changelog.json des paquets réellement installés.
Livraison
CHANGELOG.md et changelog.json sont déclarés dans package.json#files. npm n'inclut pas CHANGELOG.md automatiquement, contrairement au README.md.