Quando si aggiorna un programma, un modello di documento o una procedura interna, chi la usa ha bisogno di sapere tre cose: che cosa è cambiato, se deve fare qualcosa, e se qualcosa che prima funzionava ora si comporta in modo diverso. Il changelog e le note di rilascio servono a rispondere a queste domande. Senza, ogni aggiornamento diventa una piccola scommessa.
Changelog e note di rilascio non sono la stessa cosa
| Changelog | Note di rilascio | |
|---|---|---|
| Destinatari | Chi usa o mantiene il progetto, spesso tecnico | Utenti finali, clienti, colleghi non tecnici |
| Contenuto | Elenco completo e ordinato delle modifiche per versione | Le novità rilevanti, spiegate con il loro impatto |
| Forma | File unico che cresce nel tempo, di solito CHANGELOG.md |
Un testo per ogni rilascio |
| Tono | Sintetico e preciso | Discorsivo, orientato ai benefici e alle azioni richieste |
Molti progetti hanno entrambi: il changelog come registro completo, le note di rilascio come comunicazione.
Non è la cronologia dei commit
L'errore più comune è generare il changelog copiando i messaggi dei commit. Il risultato è un elenco di voci come «fix», «aggiornamento», «refactoring del modulo export», utili a chi sviluppa ma incomprensibili per chi usa il programma. Il changelog descrive le modifiche dal punto di vista di chi lo usa, non il lavoro svolto.
Una struttura diffusa
Una convenzione molto usata, nota come «Keep a Changelog», organizza ogni versione per categorie:
- Aggiunto (Added): nuove funzioni.
- Modificato (Changed): cambiamenti a funzioni esistenti.
- Deprecato (Deprecated): funzioni che verranno rimosse in futuro.
- Rimosso (Removed): funzioni eliminate.
- Corretto (Fixed): errori risolti.
- Sicurezza (Security): correzioni di vulnerabilità.
Le versioni compaiono dalla più recente alla più vecchia, ognuna con la data in formato AAAA-MM-GG, che non si presta a interpretazioni diverse tra paesi. In cima si tiene una sezione «Non rilasciato» in cui accumulare le modifiche in arrivo.
# Registro delle modifiche
## [Non rilasciato]
### Aggiunto
- Esportazione del report in formato CSV.
## [2.3.0] - 2026-09-30
### Aggiunto
- Filtro per data nella schermata di ricerca.
### Modificato
- Il backup notturno ora parte alle 2:00 invece che alle 23:00.
### Corretto
- Le lettere accentate nei nomi dei file non vengono più sostituite da «?».
## [2.2.1] - 2026-08-12
### Sicurezza
- Aggiornata la libreria di lettura PDF a una versione che corregge una vulnerabilità nota.
I numeri di versione
Il versionamento semantico usa tre numeri, MAGGIORE.MINORE.CORREZIONE:
- CORREZIONE (2.3.0 → 2.3.1): solo correzioni di errori, nessun cambiamento di comportamento previsto.
- MINORE (2.3.1 → 2.4.0): nuove funzioni compatibili con l'uso precedente.
- MAGGIORE (2.4.0 → 3.0.0): cambiamenti incompatibili, che possono richiedere interventi da parte di chi aggiorna.
Il valore di questa convenzione è che il numero stesso comunica il rischio. Chi vede passare un componente da 2.x a 3.0 sa che deve leggere con attenzione prima di aggiornare. Lo stesso principio si può applicare anche a modelli di documento e procedure interne.
Come scrivere una buona voce
Una voce utile risponde a «che cosa cambia per me?». Alcuni confronti:
| Da evitare | Meglio |
|---|---|
| Fix bug export | Corretto: l'esportazione in PDF non si blocca più con documenti oltre 200 pagine. |
| Aggiornate dipendenze | Sicurezza: aggiornata la libreria di cifratura per correggere una vulnerabilità nota. |
| Refactoring impostazioni | Modificato: le impostazioni sono ora raggruppate in tre schede; nessun valore è stato perso. |
| Rimosso vecchio formato | Rimosso: l'importazione dal formato .xls. Convertite i file in .xlsx prima di aggiornare. |
Regole pratiche:
- iniziate con il comportamento osservabile, non con il dettaglio tecnico;
- indicate sempre le azioni richieste a chi aggiorna, soprattutto nelle versioni maggiori;
- annunciate le rimozioni con almeno una versione di anticipo, nella categoria «Deprecato»;
- una modifica per voce, una frase per modifica.
Note di rilascio per non tecnici
Le note di rilascio partono dal changelog ma scelgono e spiegano. Una struttura efficace:
- Le novità principali in due o tre punti, ognuno con il beneficio concreto.
- Cosa dovete fare, se c'è qualcosa da fare.
- Altre migliorie, in breve.
- Problemi noti, se ce ne sono, con una soluzione temporanea.
Nel mio lavoro scrivo la voce del changelog nello stesso momento in cui faccio la modifica: ricostruirla a fine mese è lento e si dimentica sempre qualcosa.
In sintesi
- Il changelog è il registro completo delle modifiche; le note di rilascio comunicano l'essenziale agli utenti.
- Non si copia la cronologia dei commit: si descrive l'effetto per chi usa il prodotto.
- Le categorie Aggiunto, Modificato, Deprecato, Rimosso, Corretto e Sicurezza rendono il registro leggibile.
- Il versionamento semantico comunica il rischio di un aggiornamento con il numero stesso.
- Ogni voce dice che cosa cambia e quali azioni sono richieste.
