Modello di release notes

Il modello

Tutto ciò che è tra parentesi quadre è un segnaposto. Tutto il resto vale la pena conservarlo, incluso l'ordine: chi legge cerca ciò che lo riguarda, quindi i cambiamenti importanti vengono prima e il lavoro interno non compare affatto.

## [Prodotto] [versione] - [data]

[Una frase su a cosa serve questo rilascio. Ometterla nei rilasci di routine.]

### Cambiamenti importanti
- [Cosa smette di funzionare, cosa fare al suo posto ed entro quando.
  Collega i passaggi di migrazione.]

### Novità
- [Funzionalità, descritta come risultato. "Fissa un filtro e riutilizzalo",
  non "aggiunto il modello SavedView".]

### Migliorie
- [Cosa è più veloce, più chiaro o più affidabile, e di quanto circa.]

### Correzioni
- [Il sintomo visto dall'utente, non la causa nel codice.]

Se una sezione è vuota, elimina l'intestazione. Una sezione Correzioni vuota fa pensare che nulla sia stato corretto, e un'intestazione senza contenuto fa pensare che la pagina non si sia caricata bene.

Lo stesso modello, compilato

Ecco come appare con contenuti reali. Nota che nessuna voce nomina un file, un branch, un numero di ticket o una persona, e il cambiamento importante inizia con l'azione che chi legge deve compiere.

## Acme API 4.2 - 20 agosto 2026

L'impaginazione ora usa un cursore su tutti gli endpoint di elenco.

### Cambiamenti importanti
- `?page=` viene rimosso su tutti gli endpoint di elenco. Usa il valore
  `nextCursor` della risposta precedente. `?page=` restituirà 400
  dopo il 1° ottobre 2026. Passaggi di migrazione:
  acme.example/docs/pagination

### Novità
- Viste salvate nella casella. Fissa un filtro una volta e riutilizzalo
  dalla barra laterale.
- I webhook possono ora essere limitati a un singolo progetto.

### Migliorie
- Gli endpoint di elenco rispondono circa quattro volte più velocemente
  sugli account di grandi dimensioni.
- Il job di esportazione segnala l'avanzamento invece di sembrare bloccato.

### Correzioni
- I membri invitati non vedono più una dashboard vuota prima del
  primo accesso.
- I timestamp nelle esportazioni ora rispettano il fuso orario
  dell'account.

Cosa va in ogni sezione

Cambiamenti importanti

L'unica sezione con una scadenza. Di' cosa smette di funzionare, cosa fare al suo posto e da quale data. Se non hai ancora deciso la data, non pubblicare ancora la sezione: un cambiamento importante senza data si legge come urgente, e una serie di falsi allarmi è ciò che insegna alle persone a ignorare le tue release notes.

Novità

Descrivi il risultato, non ciò che hai costruito. Il test è se la riga ha ancora senso per chi non ha mai visto il tuo codice. «Viste salvate nella casella» lo supera. «Aggiunti il modello SavedView e la sua migrazione» no.

Migliorie

Quantifica dove puoi farlo onestamente. «Più veloce» vale quasi nulla e viene scontato; «circa quattro volte più veloce sugli account grandi» vale la pena leggerlo e stabilisce un'aspettativa di cui puoi essere chiamato a rispondere. Se non puoi misurarlo, di' cosa è migliore in modo verificabile.

Correzioni

Scrivi il sintomo, non la causa. Le persone cercano in queste note ciò che è successo a loro, quindi «i membri invitati vedevano una dashboard vuota» è trovabile e «corretta una race condition nella cache di appartenenza» no.

Varianti

Le quattro sezioni vanno bene per la maggior parte dei rilasci. Tre casi richiedono un adattamento:

• Rilasci di app mobile. Gli app store mostrano un campo breve di novità, quindi inizia con una frase leggibile nella scheda dello store, poi rimanda alle note complete. La revisione dello store può anche ritardare un rilascio di giorni, quindi data le note per data di rilascio, non di unione.
• Rilasci API. Versiona le note come versioni l'API, e metti la finestra di deprecazione nelle note stesse, non solo nella documentazione. Chi consuma un'API legge le note proprio per sapere quanto tempo ha ancora.
• Strumenti interni o di amministrazione. Elimina la sezione Migliorie e uniscila a Correzioni. Agli utenti interni interessa se il loro flusso di lavoro è cambiato, e una lunga sezione Migliorie lo seppellisce.

Quattro regole che le mantengono leggibili

1. Scrivi per chi non conosce il tuo codice. Niente nomi di file, niente nomi di branch, niente id di ticket, niente nomi di servizi, niente nomi in codice interni.
2. Ometti tutto ciò che non ha effetto visibile per l'utente. Aggiornamenti di dipendenze, refactor, cambiamenti di CI e correzioni di refusi vanno nella cronologia dei commit, non nelle release notes. Il modo più comune in cui muoiono le release notes è riempiendosi di lavoro che nessuno fuori dal team può vedere.
3. Una voce, un cambiamento. Se una riga ha bisogno della parola «e» due volte, probabilmente sono due voci.
4. Pubblica con un ritmo su cui le persone possano contare, anche se il ritmo è «ogni volta che rilasciamo». Note che compaiono quattro volte in una settimana e poi non compaiono per due mesi vengono trattate come rumore.

Formato delle release notes: le parti, in ordine

Il formato conta meno dell'ordine. Qualunque stile di intestazioni usi, chi scorre delle release notes cerca le stesse quattro cose nella stessa sequenza, e ogni formato diffuso ne è una variazione.

1. Un titolo che dica cosa è cambiato per chi legge, non il numero di versione. La versione va in una riga più piccola sotto, con la data in formato ISO (2026-08-29) così si legge allo stesso modo in ogni lingua.
2. Cambiamenti importanti e tutto ciò che ha una scadenza, per primi, anche se piccoli. Se qualcuno smette di leggere dopo un paragrafo, è questo quello che gli serviva.
3. Le novità, un punto per paragrafo, con il risultato nella prima frase e l'azione richiesta, incluso «nessuna azione necessaria», sempre indicata.
4. Correzioni e migliorie, poi tutto il resto come elenco di una riga in fondo. Gli aggiornamenti di dipendenze e i cambiamenti interni restano, perché l'unica persona che li cerca ne ha davvero bisogno.

In Markdown è un titolo H2, una riga attenuata con versione e data, poi sezioni H3 per Cambiamenti importanti, Novità, Migliorie e Correzioni. In un'email è lo stesso ordine con il titolo come oggetto. In un widget di changelog sono il titolo e il primo paragrafo, con il resto dietro un link. Il modello sopra è proprio questa forma, scritta per esteso.

Per la scrittura in sé, più che per la forma, vedi Come scrivere release notes che la gente legge davvero e Buone pratiche per le release notes che meritano sul blog.

Domande frequenti

Quanto dovrebbero essere lunghe le release notes?

Quanto bastano ai cambiamenti che riguardano gli utenti, e non una riga di più. Un rilascio con una correzione di bug si merita due righe. Riempire un piccolo rilascio per farlo sembrare corposo abitua le persone a saltare quelli grandi.

Qual è la differenza tra release notes e changelog?

In pratica i termini si usano in modo intercambiabile. Dove i team li distinguono, le release notes descrivono un singolo rilascio e sono scritte per gli utenti, mentre un changelog è l'elenco continuo di tutti i rilasci nel tempo. Questo modello copre un rilascio; un changelog è ciò che ottieni impilandoli, dal più nuovo.

Le release notes dovrebbero avere un numero di versione?

Solo se i tuoi utenti possono vederlo. I numeri di versione sono utili per API, librerie e software installato, dove chi legge deve sapere a che versione è. Per una web app a rilascio continuo, la data è più utile, perché è ciò che l'utente può confrontare con la propria esperienza.

Chi dovrebbe scriverle?

Chi sa cosa è cambiato, che di solito è la persona che l'ha unito, rivisto da chi cura il tono. Il modo in cui questo va storto, affidandole del tutto a chi è estraneo al lavoro, sono note che descrivono il ticket invece del cambiamento.