Release notes GitHub : les générer, puis les rendre lisibles
7 min de lecture
Les release notes GitHub sont la description attachée à une release sur la page Releases du dépôt, et GitHub peut en écrire un premier brouillon pour vous à partir des pull requests fusionnées depuis le tag précédent. Le brouillon est une liste de titres de pull requests regroupés par label, avec une ligne de contributeurs et un lien de comparaison. Il est exact, complet et écrit pour les personnes qui ont fusionné les pull requests. Le transformer en quelque chose qu’un utilisateur du projet peut lire demande un fichier .github/release.yml et une courte passe de relecture, et les deux sont décrits ci-dessous.
| Façon de produire les notes | Où ça s’exécute | Ce que vous obtenez |
|---|---|---|
| Bouton “Generate release notes” | Formulaire de release dans l’interface web | Les titres de PR depuis le dernier tag, groupés selon les catégories de release.yml |
gh release create v1.4.0 --generate-notes | GitHub CLI, en local ou en CI | Le même brouillon, créé avec la release en une seule commande |
POST /repos/{owner}/{repo}/releases/generate-notes | API REST | Le brouillon en texte, sans créer de release, pour votre propre pipeline |
| release-please, semantic-release, conventional-changelog | GitHub Actions ou un job de release | Des notes tirées des messages de commit plutôt que des titres de PR, plus les montées de version et un CHANGELOG.md |
| Rédaction à la main | Le formulaire de release | Ce que vous tapez, sans lien vers les pull requests |
Comment générer automatiquement des release notes sur GitHub ?
Ouvrez le formulaire de release, choisissez ou créez le tag, puis cliquez sur “Generate release notes”. GitHub retrouve le tag de la release précédente, liste chaque pull request fusionnée dans la branche cible entre les deux, et écrit une ligne par pull request avec son titre, son auteur et son numéro. En ligne de commande, gh release create <tag> --generate-notes fait la même chose et publie la release en une étape ; --notes-start-tag remplace le tag de départ de la plage.
La fonctionnalité travaille à partir des pull requests, donc un dépôt qui fusionne directement sur main sans pull request obtient un brouillon vide. Les squash merges passent bien, car la pull request existe toujours. Un merge commit d’une branche de longue durée vers main produit une seule ligne pour la pull request qui fusionne, sans aucune des pull requests fusionnées plus tôt dans cette branche. Si la plage a l’air fausse, la cause habituelle est un tag précédent absent ou mal ordonné ; le générateur part de la dernière release sur la branche cible, et un tag sans release attachée est ignoré.
La page GitHub Docs sur les release notes générées automatiquement couvre le bouton, et le manuel de gh release create couvre les options de la CLI.
Que change release.yml ?
.github/release.yml indique au générateur quelles pull requests laisser de côté et comment regrouper le reste. Sans lui, chaque pull request atterrit dans une seule liste, Dependabot compris. Avec lui, les pull requests sont triées en catégories par label, et le bruit étiqueté ou produit par des bots disparaît.
# .github/release.yml
changelog:
exclude:
labels:
- skip-changelog
authors:
- dependabot
- renovate
categories:
- title: Breaking changes
labels:
- breaking-change
- title: New
labels:
- enhancement
- title: Fixed
labels:
- bug
- title: Other changes
labels:
- "*"Trois règles à connaître. Les catégories sont évaluées dans l’ordre, donc une pull request portant à la fois breaking-change et bug va sous le premier titre qui correspond. Le fourre-tout "*" est obligatoire si vous voulez que les pull requests sans label apparaissent ; sans lui, elles sont silencieusement écartées. Et le fichier n’agit que sur ce que le générateur écrit, donc le modifier ne touche pas aux notes déjà existantes. Les équipes qui étiquettent déjà leurs pull requests pour un contrôle de changelog en CI peuvent réutiliser les mêmes labels ici.
Pourquoi les release notes GitHub générées se lisent-elles mal ?
Parce qu’un titre de pull request est écrit pour le relecteur, avant que le changement soit terminé, et qu’il décrit le code. “Refactor export worker to use streaming” est un bon titre de pull request et une release note inutile, parce que la personne qui lit la release veut savoir que les exports de plus de 100 Mo n’expirent plus.
La deuxième raison est que chaque pull request fusionnée a le même poids. Une correction de coquille d’une ligne côtoie un nouveau flux d’authentification, dans l’ordre où ils ont été fusionnés. Le lecteur doit parcourir toute la liste pour trouver les trois lignes qui le concernent.
La troisième est que le brouillon n’a pas d’introduction. Une liste de quarante lignes sans phrase au-dessus ne dit à personne si cette release peut être prise sans risque, demande une migration, ou n’existe que pour figer une dépendance.
Que doit changer la passe de relecture ?
Gardez la liste générée et complétez-la, plutôt que de réécrire de zéro. La liste est la piste d’audit ; les numéros de pull request sont ce qui permet de remonter d’une ligne au diff. La relecture ajoute ce que le générateur ne peut pas savoir.
- Écrivez deux ou trois phrases en haut. À quoi sert cette release, si la mise à jour demande une action, et quoi lire en premier. S’il y a un changement cassant, dites-le dès la première ligne.
- Réécrivez les lignes qui comptent pour les gens du point de vue du lecteur : le symptôme qui a disparu, ce qu’il peut faire maintenant, le réglage qui a bougé. Laissez le numéro de pull request en fin de ligne. Comment écrire des release notes donne la forme complète ; release notes de correctifs traite spécifiquement des lignes de correction.
- Déplacez tout ce qu’un lecteur doit faire dans sa propre section, avec la commande ou le réglage exact. Un changement cassant enfoui dans la liste “Other changes” est un ticket de support dans une semaine.
- Ne supprimez rien de la liste générée. Repliez-la sous un titre “Liste complète des changements” si elle est longue, mais gardez-la, parce que les contributeurs du projet s’en servent.
Faites ainsi, les release notes GitHub prennent une dizaine de minutes de relecture pour une release typique, et les notes servent les deux publics : le résumé en haut pour les utilisateurs, la liste en dessous pour les contributeurs.
La release GitHub doit-elle être votre changelog ?
Seulement si toutes les personnes qui doivent connaître un changement lisent déjà la page Releases. Pour une bibliothèque consommée par des développeurs via un gestionnaire de paquets, c’est souvent vrai, et la page Releases plus un CHANGELOG.md dans le dépôt suffisent. Pour un produit dont les utilisateurs n’ouvrent jamais GitHub, non : la page de release est écrite au mauvais niveau, vit derrière une URL destinée aux développeurs, et ne peut pas être suivie par quelqu’un sans compte GitHub.
Le schéma qui tient est de traiter la release GitHub comme le registre côté développeurs et le changelog produit comme celui côté lecteurs, la release renvoyant vers l’entrée du changelog. Tags git, releases et changelog explique comment les trois registres s’alignent. Si le changelog produit est généré à partir des mêmes commits, un générateur de changelog fournit aussi un brouillon pour ce côté-là, et la distinction changelog vs release notes précise quel détail va où.
Comment versionner les release notes elles-mêmes ?
Une release publiée sur GitHub peut être modifiée à tout moment, et la modification ne laisse aucun historique visible sur la page. Pour la plupart des projets, c’est acceptable. Pour les projets où les notes sont un registre sur lequel la conformité ou des clients s’appuient, deux habitudes aident : garder le texte canonique dans le dépôt (le CHANGELOG.md, ou un dossier docs/releases/) et faire pointer le corps de la release vers lui, et activer les releases immuables sur le dépôt si votre offre le permet, ce qui verrouille le tag et les assets une fois publiés. La documentation GitHub sur la gestion des releases décrit les brouillons, les pré-releases et le label “latest”, attribué par ordre de version sémantique sauf si vous le fixez à la main.
FAQ
Les release notes GitHub peuvent-elles être générées automatiquement ?
Oui. Le bouton “Generate release notes” du formulaire de release, l’option --generate-notes de gh release create et le endpoint REST generate-notes produisent tous un brouillon à partir des pull requests fusionnées depuis le tag de la release précédente. Un fichier .github/release.yml contrôle le regroupement et les exclusions.
Pourquoi mes release notes générées sont-elles vides ? Le générateur liste des pull requests, donc les commits directs sur la branche n’apparaissent pas, et la plage commence à la dernière release sur la branche cible plutôt qu’au dernier tag. Vérifiez que la release précédente existe et que les changements sont arrivés par des pull requests.
release.yml s’applique-t-il aux releases déjà existantes ? Non. Il ne façonne que les notes générées après la mise en place du fichier. Les corps des releases existantes restent tels quels jusqu’à ce que quelqu’un les modifie.
Faut-il utiliser les release notes GitHub ou un CHANGELOG.md ? Les deux, si le projet a des contributeurs et des utilisateurs. La page de release est là où les développeurs regardent et où vivent les assets ; le fichier dans le dépôt survit à un départ de GitHub et se lit hors ligne. Générez les release notes, gardez le fichier à jour, et liez l’un à l’autre.
Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.