Changelog: cos'è, con un esempio di voce

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, 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.

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.

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.

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.

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.

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.

Correlati su changeloop: Esempi di changelog, Documentazione per sviluppatori