Notes de version et CHANGELOG

Chaque change archivé dit déjà pourquoi il a été fait et ce qui a changé. codev en tire les notes de version : chaque proposal porte une courte section ## Release note destinée aux utilisateurs, et codev changelog rassemble les notes des changes archivés depuis la dernière version. Le choix du numéro de version, le tag et la publication restent entre vos mains et celles de vos outils de release.

Rédiger la note de version avec la proposal

/codev-propose rédige la section avec le reste de la proposal, après ## Impact :

## Release note

- Added: `--format json` pour `codev export`.
- Changed: **BREAKING** `codev export` écrit sur stdout par défaut ; passez
  `--output <PATH>` pour écrire un fichier.

Chaque élément s’écrit - <Category>: <texte>, avec l’une des six catégories de Keep a Changelog : Added, Changed, Deprecated, Removed, Fixed, Security. Les catégories restent en anglais ; le texte suit la langue des artefacts. Écrivez pour les personnes qui utilisent le produit, pas pour celles qui le construisent. Un élément incompatible commence par **BREAKING**. Un change que personne ne remarquera — un refactoring, un test, un réglage de CI — écrit la seule ligne None.

codev validate contrôle la section sur les changes actifs : une section absente donne un avertissement (release_note_missing), une catégorie inconnue, un élément sans texte ou une section vide une erreur (release_note_invalid). Le format complet figure dans Formats de fichiers.

Générer les notes

codev changelog

## [Unreleased]

### Added

- `--format json` pour `codev export`.

### Changed

- **BREAKING** `codev export` écrit sur stdout par défaut ; passez `--output <PATH>` pour écrire un fichier.

C’est git qui décide de l’intervalle : les changes dont le dossier se trouve dans _codev/changes/archive/ aujourd’hui et ne s’y trouvait pas au dernier tag v*. Utilisez --since <ref> et --until <ref> pour un autre intervalle — par exemple les notes d’une version passée :

codev changelog --until v1.4.0 --format markdown

--until v1.4.0 commence après le tag de version juste en dessous, v1.3.x. --format markdown retire le titre de version, ce qui convient au texte d’une release ; --format json fournit les éléments aux scripts (voir Sortie JSON).

Les changes archivés avant l’existence des notes de version n’ont pas de ## Release note : les puces de leur section What Changes sont listées sous Changed, et un avertissement release_note_missing nomme chacun d’eux pour que vous puissiez en relire la formulation. Un change dont les specs suppriment des exigences sans élément Removed ni BREAKING reçoit un avertissement release_note_inconsistent.

Tenir CHANGELOG.md à jour

codev changelog --write

--write place le bloc [Unreleased] dans CHANGELOG.md, entre les marqueurs de codev, juste après l’en-tête du fichier — le fichier est créé avec un en-tête standard s’il n’existe pas :

# Changelog

All notable changes to this project are documented in this file.

<!-- codev:begin — generated by `codev changelog --write` from the archived changes; edit outside this block -->
## [Unreleased]

### Added

- `--format json` pour `codev export`.
<!-- codev:end -->

## [1.3.0] - 2026-09-30
…

Les versions publiées, le texte écrit à la main et les liens en bas du fichier restent tels quels. Relancer la commande sans rien de nouveau laisse le fichier inchangé. codev doctor signale un avertissement changelog lorsque la section est en retard sur l’archive, ou lorsque CHANGELOG.md n’existe pas.

Remarque Si CHANGELOG.md a déjà un titre ## [Unreleased] écrit à la main, le premier --write le reprend : la section gérée remplace ce titre, et les entrées que vous avez écrites en dessous restent à leur place, dans la même section.

Publier une version

Juste avant de poser le tag :

codev changelog --release 1.4.0 --write

Le bloc généré devient ## [1.4.0] - <aujourd'hui> (ou --date YYYY-MM-DD), hors des marqueurs, et une nouvelle section ## [Unreleased] vide prend sa place dans la section gérée. Commitez, puis posez aussitôt le tag v1.4.0 : tant que le tag n’existe pas, codev changelog compte encore ces changes comme non publiés.

Sur GitHub, le workflow de release peut reprendre les mêmes notes pour le texte de la release, produites par le codev du commit tagué :

codev changelog --until "$GITHUB_REF_NAME" --format markdown > release-notes.md

L’adopter dans un projet existant

Si votre CHANGELOG.md décrit déjà des changes archivés sans note de version, listez-les sous changelog.exclude dans _codev/config.yaml, pour qu’ils ne soient pas listés une seconde fois :

changelog:
  exclude:
    - 2026-09-30-legacy-import

Une fois la version suivante taguée, ils sortent de l’intervalle et la liste peut être vidée. Voir Configuration.

Raccourcis clavier