guides

Un changelog è un file che elenca le modifiche notevoli apportate a un progetto, organizzate per versione. Il suo compito è rispondere a una domanda semplice per chiunque usi il tuo software o ne dipenda: cosa è cambiato tra la versione che avevo e quella verso cui sto passando. Poiché è scritto per le persone e non per le macchine, un buon changelog mette in evidenza ciò che conta davvero per gli utenti e lascia fuori il rumore.

È utile chiarire cosa un changelog non è. Non è l'output grezzo della tua cronologia di controllo di versione. Un git log elenca ogni commit, compresi piccoli refactoring, correzioni di refusi e commit di merge, nell'ordine in cui sono stati fatti e con la formulazione scelta dall'autore. Un changelog è un riassunto curato, scritto da una persona, che raggruppa il lavoro correlato, scarta i dettagli banali e descrive ogni modifica in base al suo effetto su chi legge.

La convenzione più seguita per scriverne uno si chiama Keep a Changelog. Definisce un formato semplice basato su Markdown, di solito in un file chiamato CHANGELOG.md nella radice del repository. L'idea è che una struttura coerente e prevedibile renda il file facile da scorrere, che il lettore sia una persona che naviga su un host di codice o uno strumento che analizza le voci.

Il formato Keep a Changelog

Secondo quella convenzione, ogni versione rilasciata ha una propria sezione, intitolata con il numero di versione e la data di rilascio. All'interno di una versione, le modifiche sono raggruppate sotto un piccolo insieme di intestazioni standard, così che i lettori trovino in fretta ciò che li interessa. I gruppi consigliati sono Added per le nuove funzionalità, Changed per le modifiche al comportamento esistente, Deprecated per le funzionalità in via di dismissione, Removed per quelle ormai rimosse, Fixed per le correzioni di bug e Security per tutto ciò che riguarda le vulnerabilità.

Le versioni stesse seguono di solito il versionamento semantico, così che una versione si legge MAJOR.MINOR.PATCH, come 2.4.1. Questo lega il changelog al numero di versione in modo utile: un lettore può guardare il salto da una versione alla successiva e farsi un'idea. Una modifica del numero maggiore segnala che qualcosa potrebbe rompersi, mentre un incremento di patch suggerisce solo correzioni. Il changelog spiega poi, a parole, cosa si nasconde esattamente dietro quel numero.

Ordine, date e la sezione Unreleased

Un changelog viene normalmente tenuto in ordine cronologico inverso, con la versione più recente in cima, così che l'informazione più rilevante sia la prima che il lettore vede. Ogni voce è datata, il che permette di collocare un rilascio nel tempo e capire quanto è recente una correzione o una funzionalità. Mantenere coerenti l'ordine e le date fa parte di ciò che rende il file affidabile a colpo d'occhio.

• Un changelog è un file che elenca le modifiche notevoli di ogni versione, scritto per le persone, non il git log grezzo.
• Keep a Changelog è la convenzione comune, di solito un CHANGELOG.md in Markdown nella radice del repository.
• Gruppi di modifiche standard: Added, Changed, Deprecated, Removed, Fixed e Security.
• Le versioni seguono di solito il versionamento semantico (MAJOR.MINOR.PATCH), ognuna con la sua data di rilascio.
• Le voci vanno in ordine cronologico inverso, spesso con una sezione Unreleased in cima.
• Puoi generare le voci dai commit (per esempio Conventional Commits), ma un changelog scritto a mano è spesso più chiaro.

Un'aggiunta comune e pratica è una sezione Unreleased proprio in cima. È lì che registri le modifiche mentre le fai, prima che siano legate a un numero di versione. Quando sei pronto a pubblicare un rilascio, rinomini quella sezione con il nuovo numero, le dai una data e avvii un nuovo blocco Unreleased. Questa abitudine fa sì che il changelog venga scritto mentre il lavoro è fresco, invece di essere ricostruito a memoria all'ultimo minuto.

Scrivere buone voci e generarle

Scrivere buone voci significa soprattutto tenere a mente il lettore. Ogni modifica notevole dovrebbe avere una propria voce, formulata in modo che anche chi non conosce gli interni ne capisca comunque l'effetto. Conviene descrivere il risultato per l'utente invece della meccanica del codice, evitare il gergo interno e raggruppare le modifiche correlate in un'unica riga chiara anziché una voce per commit. Le modifiche banali o puramente interne possono essere omesse del tutto.

È possibile generare un changelog automaticamente dalla tua cronologia dei commit, e molti team lo fanno. Approcci come Conventional Commits chiedono di scrivere i messaggi di commit in modo strutturato, per esempio anteponendo feat o fix, così che uno strumento possa ordinarli nei gruppi giusti e assemblare una bozza. Questo può far risparmiare tempo e imporre coerenza, ma il risultato tende a leggersi come un elenco di commit. Un changelog scritto o almeno rivisto a mano è spesso più chiaro, perché una persona può decidere cosa vale la pena menzionare e formularlo per il pubblico.

In sintesi

In breve, un changelog è una registrazione leggibile di ciò che è cambiato in ogni versione di un progetto, tenuta per le persone che lo usano. La convenzione Keep a Changelog gli dà una forma prevedibile, il versionamento semantico dà significato ai suoi numeri di versione, e un po' di disciplina, come una sezione Unreleased e una voce per modifica notevole, lo mantiene accurato. Che sia scritto a mano o generato dai commit, il suo valore nasce dall'essere chiaro, aggiornato e concentrato su ciò che il lettore ha davvero bisogno di sapere.