Cos'è un changelog? Definizione ed esempio di voce
6 min di lettura aggiornato il
Un changelog è il registro datato di ciò che è cambiato in un prodotto, scritto per le persone coinvolte dal cambiamento, non per il team che lo ha rilasciato. Ogni voce nomina un cambiamento, dice quando è entrato in vigore e dice cosa deve fare chi legge, che nella maggior parte dei casi è niente. Proprio questo separa un changelog da un log dei commit: un log dei commit è un registro per chi ha scritto il codice, un changelog è un registro per chi lo usa.
Cos’è un changelog, esattamente?
Un elenco di voci datate, dalla più recente, ognuna descrive un singolo cambiamento in termini che chi legge può verificare. Non cosa ha costruito il team, ma cosa è diverso ora. “Refactoring del servizio di fatturazione” è un messaggio di commit. “Le fatture ora mostrano l’imposta come riga separata” è una voce di changelog, perché dice a chi legge qualcosa che può controllare sul proprio account.
Il formato è antico e volutamente semplice: un titolo per release o per giorno, un elenco breve sotto, a volte un’etichetta di categoria. Keep a Changelog è la specifica più citata per questa forma (come funziona in un repository reale), ed esiste perché la maggior parte dei progetti che salta una specifica finisce per riversare la cronologia dei commit al suo posto, che risponde a una domanda diversa da quella con cui è arrivato chi legge.
| Documento | Scritto per | Risponde a |
|---|---|---|
| Changelog | Chiunque usi il prodotto | Cosa è cambiato, e quando? |
| Log dei commit | Il team che ha scritto il codice | Cosa è stato fatto, in che ordine? |
| Note di rilascio | Utenti che decidono se aggiornare | Cosa posso fare ora che non potevo? |
| Note di patch | Giocatori o utenti di un fix specifico | Cosa ha risolto proprio questa release? |
| Roadmap | Chiunque si chieda cosa arriva dopo | Cosa è pianificato, e a che punto è? |
I cinque si sovrappongono nella pratica, ma non sono lo stesso documento, e la differenza sta in chi lo tiene in mano quando lo legge. Un changelog è quello costruito per essere cercato e collegato in seguito, per cui le sue voci hanno più bisogno di date e URL stabili degli altri. La roadmap è l’unica delle cinque rivolta al futuro; esempi di roadmap di prodotto mostra sei formati che può assumere.
Cosa contiene davvero una voce di changelog?
Quattro cose, in quest’ordine: cosa è cambiato, espresso nei termini in cui l’utente o il chiamante lo noterebbe; quando è entrato in vigore; a quale categoria appartiene (added, fixed, changed, removed sono le quattro comuni); e, quando conta, cosa deve fare chi legge al riguardo. Un link per approfondire è benvenuto. Un paragrafo di giustificazione interna no, perché chi legge non ha chiesto perché, ha chiesto cosa.
## 2026-09-07
### Added
- Le fatture ora mostrano l'imposta come riga separata, nella valuta
dell'account del cliente.
### Fixed
- Esportare un report come CSV non elimina più l'ultima riga quando il
report supera le 10.000 righe.
Questa forma scala da un aggiornamento di due righe a cento voci in una release senza cambiare struttura, ed è il vero test se un formato funziona: si legge allo stesso modo in una settimana intensa e in una tranquilla.
Esiste un modello di changelog da copiare?
Sì. È la stessa forma con le quattro categorie comuni, pronta da incollare in un CHANGELOG.md o in
una pagina. Eliminate ogni intestazione che in una certa release non ha nulla sotto.
# Changelog
## 2026-10-18
### Added
- [Cosa può fare ora l'utente che prima non poteva.]
### Changed
- [Cosa funziona in modo diverso, e cosa dovrebbe fare chi legge.]
### Fixed
- [Il sintomo che l'utente vedeva, ora sparito.]
### Removed
- [Cosa non c'è più, e cosa usare al suo posto.]
Per un documento più lungo per ogni release, il modello di release notes
aggiunge una riga di sintesi e una sezione per i cambiamenti che rompono qualcosa. Per cinque voci
finite con note sul perché ognuna funziona, vedi esempi di changelog.
Se il changelog vive in un repository, CHANGELOG.md spiega come tenere
aggiornato il file, dalla sezione Unreleased in cima a ciò che è meglio lasciare fuori.
Chi scrive un changelog, e quando?
Chi ha fatto il cambiamento, nel momento in cui viene rilasciato, non una redattrice tecnica che lo ricostruisce dai ticket una settimana dopo. Chi ha toccato il codice sa cosa è cambiato davvero per l’utente; un riassunto scritto in seguito tende a descrivere il ticket invece di ciò che è stato effettivamente rilasciato, ed è di solito più ampio o più stretto dell’effettivo. Alcuni team aggiungono un passaggio di revisione prima che una voce diventi pubblica, soprattutto per intercettare linguaggio interno che si è infilato, e quella revisione dovrebbe essere abbastanza rapida da far uscire la voce lo stesso giorno.
Dove dovrebbe vivere un changelog?
Sulla propria pagina, con un URL stabile, distribuito come feed. Sepolto in un menu delle impostazioni o in un tag di release su un host di codice, raggiunge solo chi già sapeva dove guardare. Una pagina pubblica si può collegare da un ticket di supporto, citare in una recensione o sottoscrivere. Il feed conta quanto la pagina: chi controlla il changelog di un prodotto una volta al mese è raro, chi lo sottoscrive no, e solo il feed serve il secondo tipo. Come costruire una pagina di changelog pubblica copre la pagina in sé, dall’URL alle opzioni di iscrizione.
In cosa differisce dalle note di rilascio?
Vengono confusi costantemente, e sono abbastanza diversi che unirli produce un documento che non serve bene nessuna delle due lettrici. Changelog vs note di rilascio percorre la distinzione per intero; in breve, un changelog è il registro completo e cronologico, e le note di rilascio sono un sottoinsieme curato, scritto perché un aggiornamento suoni degno di essere avuto. Un prodotto di solito ha bisogno di entrambi, rivolti a momenti diversi della giornata di chi legge.
Cosa rende un changelog degno di essere letto?
Specificità e onestà sulla propria portata. “Vari bugfix” è la frase che insegna a chi legge a smettere di aprire la pagina, perché non promette nulla che possa verificare. Una voce che nomina il comportamento esatto cambiato, anche per un fix piccolo, è quella che tiene viva un’iscrizione. Questa disciplina vale anche per le omissioni: un changelog che annuncia solo successi e mai un fix per qualcosa che era rotto si legge come marketing travestito da changelog, e chi legge se ne accorge.
Conta anche la disciplina di versionamento. Semantic versioning e il tuo changelog spiega come numero di versione e voce dovrebbero corrispondere, così chi scorre la cronologia delle versioni riceve lo stesso segnale due volte invece di due segnali diversi.
Come vengono generati i changelog?
In due modi, e la maggior parte delle configurazioni reali è un mix. La generazione automatizzata legge i messaggi di commit, di solito in formato Conventional Commits, e li trasforma in voci senza che nessuno tocchi l’output; dai conventional commits al changelog copre quella pipeline. La generazione curata significa che qualcuno scrive o modifica ogni voce a mano. L’output automatizzato è più veloce e non perde mai una pull request unita, ma eredita ogni messaggio di commit vago parola per parola, per cui la maggior parte dei team che automatizza mantiene comunque un passaggio di revisione leggero prima di pubblicare invece di mostrare l’output grezzo.
Su GitHub la prima bozza può arrivare dalla piattaforma stessa, che sa generare le release notes
dalle pull request unite dopo il tag precedente. Release notes su
GitHub spiega il file release.yml che le raggruppa e il passaggio
di revisione che le rende leggibili.
FAQ
Ogni prodotto ha bisogno di un changelog? Qualsiasi prodotto con utenti coinvolti dal cambiamento ne ha bisogno, che sia un’app SaaS, uno strumento interno o un’API pubblica. La forma si adatta (un changelog di API si legge diverso da quello di un’app consumer), il bisogno no.
Cos’è un changelog in termini di software? La stessa definizione di sopra: un elenco datato e cronologico di ciò che è cambiato nel software, scritto per chi lo usa, non per chi lo ha costruito.
Un changelog può essere generato automaticamente dai commit? Sì, e molti team fanno esattamente questo, di solito da messaggi in formato Conventional Commits. Il compromesso è che una voce generata è chiara solo quanto il messaggio di commit da cui proviene, per cui un passaggio di revisione prima della pubblicazione intercetta quelle da riformulare.
Un changelog è lo stesso di una cronologia delle versioni? Abbastanza simile da usare i termini in modo intercambiabile. Una cronologia delle versioni a volte è solo un elenco di numeri e date senza descrizione; un changelog include sempre cosa è cambiato.
Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.