Release notes su GitHub: generarle, poi renderle leggibili
7 min di lettura
Le release notes su GitHub sono la descrizione allegata a una release nella pagina Releases del repository, e GitHub può scriverne una prima bozza al posto tuo a partire dalle pull request integrate dopo il tag precedente. La bozza è un elenco di titoli di pull request raggruppati per etichetta, con una riga dei contributori e un link di confronto. È accurata, completa e scritta per le persone che hanno integrato quelle pull request. Trasformarla in qualcosa che un utente del progetto possa leggere richiede un file .github/release.yml e una breve revisione, e qui sotto trovi entrambi.
| Modo di produrre le note | Dove gira | Cosa ottieni |
|---|---|---|
| Pulsante “Generate release notes” | Form della release nell’interfaccia web | Titoli delle PR dall’ultimo tag, raggruppati per categorie di release.yml |
gh release create v1.4.0 --generate-notes | GitHub CLI, in locale o in CI | La stessa bozza, creata insieme alla release in un solo comando |
POST /repos/{owner}/{repo}/releases/generate-notes | REST API | La bozza come testo, senza creare una release, per la tua pipeline |
| release-please, semantic-release, conventional-changelog | GitHub Actions o un job di release | Note dai messaggi di commit invece che dai titoli delle PR, più salto di versione e un CHANGELOG.md |
| Scritte a mano | Il form della release | Quello che digiti, senza alcun link alle pull request |
Come si generano automaticamente le release notes su GitHub?
Apri il form della release, scegli o crea il tag e clicca “Generate release notes”. GitHub trova il tag della release precedente, elenca ogni pull request integrata nel branch di destinazione tra i due e scrive una riga per pull request con titolo, autore e numero. Da riga di comando, gh release create <tag> --generate-notes fa la stessa cosa e pubblica la release in un unico passaggio; --notes-start-tag sovrascrive il tag da cui parte l’intervallo.
La funzione lavora sulle pull request, quindi un repository che integra direttamente su main senza pull request ottiene una bozza vuota. Gli squash merge vanno bene, perché la pull request esiste comunque. I merge commit da un branch longevo verso main producono una riga per la pull request che integra, senza nessuna delle pull request integrate prima in quel branch. Se l’intervallo sembra sbagliato, la causa più comune è un tag precedente mancante o fuori ordine; il generatore usa l’ultima release sul branch di destinazione, e un tag senza release collegata viene ignorato.
La pagina della documentazione GitHub sulle release notes generate automaticamente copre il pulsante, e il manuale di gh release create copre le opzioni della CLI.
Cosa cambia release.yml?
.github/release.yml dice al generatore quali pull request lasciare fuori e come raggruppare le altre. Senza, ogni pull request finisce in un unico elenco, Dependabot compreso. Con il file, le pull request vengono smistate in categorie per etichetta, e il rumore etichettato o prodotto da bot sparisce.
# .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:
- "*"Tre regole da conoscere. Le categorie vengono confrontate in ordine, quindi una pull request con sia breaking-change sia bug finisce sotto il primo titolo che corrisponde. Il jolly "*" è obbligatorio se vuoi che le pull request senza etichetta compaiano; senza, vengono scartate in silenzio. E il file influisce solo su ciò che il generatore scrive, quindi modificarlo non tocca le note già esistenti. I team che già etichettano le pull request per un controllo del changelog in CI possono riusare qui le stesse etichette.
Perché le release notes generate da GitHub si leggono male?
Perché il titolo di una pull request è scritto per chi la revisiona, prima che la modifica sia finita, e descrive il codice. “Refactor export worker to use streaming” è un buon titolo di pull request e una release note inutile, perché chi legge la release vuole sapere che gli export sopra i 100 MB non vanno più in timeout.
La seconda ragione è che ogni pull request integrata ha lo stesso peso. Una correzione di refuso da una riga sta accanto a un nuovo flusso di autenticazione, nell’ordine in cui sono state integrate. Il lettore deve scorrere l’intero elenco per trovare le tre righe che lo riguardano.
La terza è che la bozza non ha un’apertura. Un elenco di quaranta righe senza una frase sopra non dice a nessuno se questa release si può prendere senza rischi, se serve una migrazione o se esiste solo per bloccare una dipendenza.
Cosa dovrebbe cambiare la revisione?
Tieni l’elenco generato e aggiungici, invece di riscrivere da zero. L’elenco è la traccia di audit; i numeri delle pull request sono il modo in cui qualcuno risale da una riga al diff. La revisione aggiunge le parti che il generatore non può sapere.
- Scrivi due o tre frasi in cima. A cosa serve questa release, se aggiornare richiede qualche azione e cosa leggere per primo. Se c’è una breaking change, dillo nella prima riga.
- Riscrivi le righe che interessano davvero dal lato del lettore: il sintomo che è sparito, la cosa che ora si può fare, l’impostazione che si è spostata. Lascia il numero della pull request in fondo alla riga. Come scrivere release notes ha la forma completa; release notes per le correzioni di bug copre nello specifico le righe delle correzioni.
- Sposta tutto ciò che il lettore deve fare in una sezione propria, con il comando o l’impostazione esatti. Una breaking change sepolta nell’elenco “Other changes” è un ticket di supporto tra una settimana.
- Non cancellare nulla dall’elenco generato. Comprimilo sotto un titolo “Elenco completo delle modifiche” se è lungo, ma tienilo, perché i contributori del progetto lo usano.
Fatte così, le release notes su GitHub richiedono circa dieci minuti di revisione per una release tipica, e servono entrambi i pubblici: il riassunto in cima per gli utenti, l’elenco sotto per i contributori.
La release su GitHub dovrebbe essere il tuo changelog?
Solo se tutti quelli che devono sapere di una modifica leggono già la pagina Releases. Per una libreria che gli sviluppatori consumano tramite un package manager spesso è vero, e la pagina Releases più un CHANGELOG.md nel repository bastano. Per un prodotto con utenti che non aprono mai GitHub, no: la pagina della release è scritta al livello sbagliato, vive dietro un URL pensato per sviluppatori e non può essere seguita da chi non ha un account GitHub.
Lo schema che regge è trattare la release su GitHub come il registro per gli sviluppatori e il changelog di prodotto come quello per i lettori, con la release che linka la voce del changelog. Tag git, release e changelog spiega come i tre registri si allineano. Se il changelog di prodotto viene generato dagli stessi commit, un generatore di changelog dà una bozza anche per quel lato, e la divisione changelog vs release notes spiega quale dettaglio va dove.
Come si versionano le release notes stesse?
Una release pubblicata su GitHub può essere modificata in qualsiasi momento, e la modifica non lascia nessuna cronologia visibile nella pagina. Per la maggior parte dei progetti va bene. Per i progetti in cui le note sono un registro su cui contano la compliance o i clienti, aiutano due abitudini: tenere il testo canonico nel repository (il CHANGELOG.md, o una cartella docs/releases/) e far puntare lì il corpo della release, e abilitare le immutable releases sul repository se il tuo piano lo offre, che bloccano tag e asset una volta pubblicati. La documentazione GitHub sulla gestione delle release descrive bozze, pre-release e l’etichetta “latest”, assegnata in ordine di versione semantica a meno che non la imposti a mano.
FAQ
Le release notes su GitHub si possono generare automaticamente?
Sì. Il pulsante “Generate release notes” nel form della release, l’opzione --generate-notes di gh release create e l’endpoint REST generate-notes producono tutti una bozza dalle pull request integrate dopo il tag della release precedente. Un file .github/release.yml controlla raggruppamenti ed esclusioni.
Perché le mie release notes generate sono vuote? Il generatore elenca pull request, quindi i commit diretti sul branch non compaiono, e l’intervallo parte dall’ultima release sul branch di destinazione, non dall’ultimo tag. Controlla che la release precedente esista e che le modifiche siano arrivate tramite pull request.
release.yml si applica alle release già esistenti? No. Dà forma solo alle note generate dopo che il file è in posizione. I corpi delle release esistenti restano come sono finché qualcuno non li modifica.
Devo usare le release notes di GitHub o un CHANGELOG.md? Entrambi, se il progetto ha contributori e utenti. La pagina della release è dove guardano gli sviluppatori e dove stanno gli asset; il file nel repository sopravvive a un trasloco fuori da GitHub e si legge offline. Genera le release notes, tieni aggiornato il file e linka l’uno all’altro.
Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.