Que fait notes-de-version ?
Transforme un historique Git brut en notes de version qu'un humain aurait vraiment envie de lire.
Ce qu'elle fait
- Compare les commits entre deux références (tags, branches ou
HEAD) - Regroupe les modifications par type : fonctionnalités, corrections, changements cassants, tâches diverses
- Détecte les changements cassants à partir des marqueurs
!des commits conventionnels et des pieds de pageBREAKING CHANGE: - Rédige une section « Points forts » (les 3 à 5 changements qui intéressent vraiment les utilisateurs)
- Génère du Markdown prêt pour GitHub Release
Utilisation
# Notes pour la version à venir (dernier tag -> HEAD)
git log $(git describe --tags --abbrev=0)..HEAD --oneline
# Entre deux tags
git log v1.2.0..v1.3.0 --pretty=format:'%h %s %b'
Demandez ensuite à l'agent : « rédige les notes de version pour v1.3.0 à partir de ces commits. »
Ou avec la CLI GitHub, directement dans un brouillon de release :
# Créez le tag, puis rédigez les notes de version à partir de la différence
git tag v1.3.0 && git push origin v1.3.0
gh release create v1.3.0 --generate-notes --draft
# puis affinez les notes générées avec cette compétence
Processus
1. Collecter les commits
git log <prev-tag>..<new-tag> --pretty=format:'%h|%s|%b|%an' --no-merges
Incluez séparément les commits de fusion si le dépôt utilise un flux basé sur les fusions — le titre de la fusion résume généralement mieux la PR que les commits individuels.
2. Classer chaque commit
| Préfixe / signal | Section |
|---|---|
feat, feat! | Fonctionnalités |
fix | Corrections de bugs |
! ou BREAKING CHANGE: | ⚠️ Changements cassants (également listés dans leur propre section) |
perf | Performances |
docs, chore, ci, refactor, test | Regroupés sous « Autres » ou omis |
Commits sans préfixes conventionnels : classer selon le contenu du message. En cas de doute, placer dans « Autres modifications » plutôt que de les supprimer silencieusement.
3. Rédiger les points forts
Sélectionnez les 3 à 5 changements les plus importants pour les utilisateurs du logiciel :
- Nouvelles capacités qu'ils remarqueront
- Changements cassants auxquels ils doivent s'adapter
- Corrections de problèmes largement signalés
Rédigez chaque point en une phrase simple. Pas d'adjectifs marketing.
4. Écrire les notes
## v1.3.0
**Points forts**
- ...
- ...
### ⚠️ Changements cassants
- ...
### Fonctionnalités
- ...
### Corrections de bugs
- ...
### Autres modifications
- ...
**Journal complet :** <prev-tag>...<new-tag>
5. Vérifications avant publication
- Chaque changement cassant apparaît dans la section ⚠️ avec un conseil de migration
- Aucune tâche interne présentée comme une fonctionnalité destinée aux utilisateurs
- Les noms des contributeurs sont crédités si la convention du dépôt le prévoit
- Le numéro de version correspond au tag
Conventions
- Suivre le style de notes de version existant du dépôt s'il en a un — la cohérence prime sur tout modèle.
- Si le dépôt utilise
gh release --generate-notes, utiliser sa sortie comme brouillon de départ et l'affiner : il obtient la liste correcte mais les points forts sont erronés. - N'inventez jamais de changements qui ne figurent pas dans la plage de commits. Lorsque la plage est ambiguë, demandez quelles références comparer plutôt que de deviner.