Release notes software: cosa sono e cosa includere

Le release notes software sono il documento che accompagna una versione di un software e dice al lettore cosa è cambiato, a chi riguarda il cambiamento e cosa, se qualcosa, deve fare. Si scrivono una volta per rilascio e le leggono persone che decidono se aggiornare, persone che controllano se un problema in cui sono incappate è stato risolto e persone che fanno supporto sul prodotto. Quelle buone sono brevi, specifiche per la versione e oneste su tutto ciò che rompe qualcosa.

Cosa sono le release notes software?

Sono un riepilogo datato e versionato di un singolo rilascio. Una release note risponde a tre domande per un lettore che non era presente: cosa è diverso, mi riguarda, devo fare qualcosa. La storia completa del progetto è il changelog, e il log dei commit serve a chi ha scritto il codice.

Gli stessi fatti possono comparire in una voce di changelog e nelle release notes. La differenza sta nella selezione e nel pubblico: il changelog elenca ogni modifica rilevante, mentre le release notes aprono con quelle che il lettore noterà e le spiegano. Changelog vs release notes traccia il confine nel dettaglio.

Cosa devono includere le release notes software?

Includi versione e data, un riepilogo di un paragrafo, poi le modifiche raggruppate per ciò che il lettore può farne. Per ogni modifica, di’ cosa è diverso nei termini del lettore, chi è interessato e se serve un’azione.

Un insieme completo ha queste parti:

1. Numero di versione e data di rilascio. Usa il formato dei tuoi tag, così un lettore può collegare le note a una build.
2. Un riepilogo. Due o tre frasi: a cosa serve questo rilascio e se aggiornare richiede qualcosa al lettore.
3. Nuove funzionalità e miglioramenti. Cosa può fare ora il lettore, non cosa contiene ora il codice.
4. Correzioni. Il sintomo sparito e la versione in cui era iniziato.
5. Breaking change e deprecazioni. Cosa smette di funzionare, quando e cosa usare al suo posto. Mettile per prime, se ce ne sono.
6. Problemi noti. Tutto ciò che hai rilasciato sapendo che non è a posto, con una soluzione alternativa se esiste.
7. Requisiti e passaggi di aggiornamento. Piattaforme supportate, versioni minime, comandi di migrazione.

Lascia fuori refactoring, aggiornamenti di dipendenze senza effetti visibili e ticket interni. Se un lettore non può accorgersi della modifica, il suo posto è la cronologia di git. Come scrivere release notes copre formulazione e ordine.

Che aspetto ha una release note di un software?

Eccone una breve per uno strumento da riga di comando inventato. La forma conta più del contenuto.

## 2.4.0 (2026-10-08)

Export più veloci e una breaking change al file di configurazione.
Aggiornare richiede la modifica di una riga in `tool.yml`.

### Breaking change
- `output:` in `tool.yml` ora è `export.path:`. Le vecchie
  configurazioni falliscono con "unknown key". Rinomina la chiave;
  il resto non cambia.

### Novità
- Gli export vanno su disco in streaming, quindi i file oltre
  100 MB non vanno più in timeout.

### Corretto
- La ricerca funziona di nuovo per le query con un trattino.
  Rotta dalla 2.3.0.

### Problemi noti
- I percorsi Windows oltre 260 caratteri falliscono ancora. Per
  ora usa una cartella di output con un percorso più corto.

La breaking change sta per prima, con il testo esatto dell’errore che il lettore vedrà, perché le persone cercano i messaggi di errore. La correzione indica la versione in cui si era rotto, così il lettore può collegarla al momento in cui è iniziato il suo problema. Il problema noto ha una soluzione alternativa, che è meglio del silenzio. Gli esempi di release notes hanno altre formulazioni per ogni tipo di voce.

Come cambiano le release notes software per ogni pubblico?

Tieni un’unica fonte di verità e scrivi una versione per pubblico. I fatti non cambiano, ma il livello di dettaglio sì. I clienti vogliono il beneficio in una riga, gli amministratori vogliono requisiti e problemi noti, gli sviluppatori vogliono nomi e versioni esatti, e il supporto vuole sapere cosa rispondere quando arriva un ticket.

Per i prodotti API, la versione per sviluppatori richiede più cura, perché una modifica che per te è una piccola correzione può essere un’interruzione per chi chiama. Changelog API e breaking changes trattano questo pubblico. Per la versione interna, le release note interne descrivono cosa servono a supporto e vendite che ai clienti non serve.

Dove vanno pubblicate le release notes software?

Pubblicale dove il lettore si trova già quando si pone la domanda. Per un’app mobile è la scheda dello store, dove la piattaforma offre un campo per le release notes di ogni versione; Apple documenta come fornire le release notes per le build. Per un prodotto web è una pagina changelog collegata dall’app. Per una libreria è la pagina della release e un file nel repository, come descritto in release notes di GitHub.

Tieni ogni versione a un URL stabile, così il supporto può linkarla, e conserva le versioni vecchie. Chi è alla 2.2 ha bisogno anche delle note della 2.3 e della 2.4. Se vuoi una struttura di partenza, il template di release notes ti dà le intestazioni da copiare.

Quanto devono essere lunghe le release notes?

Quanto serve alla modifica, non di più. Un rilascio di patch può essere di tre righe. Un rilascio maggiore con una migrazione richiede una pagina, e probabilmente una guida di migrazione a parte, linkata dalle note. Il test è se un lettore che scorre la prima schermata capisce se il rilascio lo riguarda. Se non lo capisce, porta su il riepilogo e taglia il resto. Buone pratiche per le release notes elenca cosa regge e cosa è solo abitudine.

FAQ

Cosa sono le release notes software? Sono un riepilogo versionato di cosa è cambiato in un rilascio di un software, scritto per chi lo usa o lo supporta. Coprono nuove funzionalità, correzioni, breaking change e tutto ciò che il lettore deve fare.

Qual è la differenza tra release notes e changelog? Il changelog è il registro completo e continuo delle modifiche rilevanti. Le release notes sono un messaggio su un singolo rilascio, scelto e riscritto per i lettori che decidono se aggiornare. Molti team pubblicano la voce di changelog di una versione come sue release notes.

Chi scrive le release notes software? Di solito il product manager, un technical writer o l’ingegnere che ha rilasciato la modifica, con qualcuno che rivede il tono. Il risultato migliore arriva quando chi è più vicino alla modifica scrive la bozza e una seconda persona la edita pensando al lettore.

I rilasci minori hanno bisogno di release notes? Sì, brevi. Anche un rilascio di patch dovrebbe dire cosa è stato corretto e se il lettore deve fare qualcosa. Una nota di una riga è meglio di niente, perché “correzioni di bug e miglioramenti” non dice nulla al lettore.

Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.

Correlati su changeloop: Modello di release notes, Esempi di changelog