Changelog: cos’è e come si struttura

Changelog in breve

• Cosa risolve: offre tracciabilità delle differenze tra una versione e la successiva di un progetto.
• Quando si applica: a ogni rilascio di software, API, prodotto digitale o aggiornamento documentale rilevante.
• Condizioni e limiti: non sostituisce la cronologia tecnica di Git né la documentazione completa del progetto.
• Come verificare: ogni voce dovrebbe riportare versione, data in formato ISO 8601 e categoria della modifica.
• Cosa fare: adottare una convenzione stabile, come quella di Keep a Changelog, e mantenerla ad ogni rilascio.
• Tempo richiesto: l’aggiornamento occupa pochi minuti per release se integrato nel flusso di sviluppo.

Cos’è un changelog e perché si usa

Il termine nasce dall’unione delle parole inglesi change e log e indica, in italiano, un registro delle modifiche: un documento che riporta, versione dopo versione, cosa è stato aggiunto, cambiato o corretto in un progetto software. A differenza di un semplice elenco automatico, il documento è scritto per essere letto da persone, non generato meccanicamente.

La funzione principale è la tracciabilità: permette a chi utilizza un software, o contribuisce al suo sviluppo, di capire con precisione cosa è cambiato tra un rilascio e l’altro senza dover analizzare il codice sorgente. A questa si affianca la trasparenza verso utenti e collaboratori, soprattutto quando una modifica introduce un breaking change, ovvero un’alterazione che interrompe la compatibilità con versioni precedenti.

Differenza tra changelog e cronologia di Git

Il git log è l’elenco automatico e tecnico di tutti i commit registrati dal sistema di controllo versione: include ogni intervento, anche minimo, senza selezione né contesto leggibile. Il changelog, al contrario, è un documento curato manualmente (o semi-automaticamente) che riporta solo le modifiche degne di nota, raggruppate per versione e scritte in un linguaggio comprensibile anche a chi non ha accesso al codice.

Ogni voce, per essere completa, dovrebbe indicare almeno la release di riferimento, l’autore dell’intervento, la data e una descrizione sintetica della modifica: questi elementi rendono il documento utile sia a scopo di debugging interno sia come riferimento pubblico per gli utenti finali.

Changelog e note di rilascio: le differenze

Il changelog è il registro tecnico e completo delle modifiche, mentre le release notes (note di rilascio) sono un testo più discorsivo e orientato al pubblico, pensato per comunicare i benefici di un aggiornamento piuttosto che elencarne ogni dettaglio. Entrambi i documenti nascono dagli stessi dati, ma rispondono a scopi diversi.

Come si struttura un changelog

La convenzione più diffusa, ispirata a Keep a Changelog, organizza le modifiche di ogni versione in sei categorie fisse. Questa suddivisione, più dello snippet generico di un elenco modifiche, permette di capire immediatamente se un aggiornamento introduce rischi, novità o semplici correzioni.

Added

Nuove funzionalità introdotte nella versione.

Changed

Modifiche a funzionalità già esistenti.

Deprecated

Funzioni ancora attive ma destinate alla rimozione in una release futura.

Removed

Funzionalità eliminate definitivamente dal progetto.

Fixed

Correzioni di bug o comportamenti anomali.

Security

Interventi legati a vulnerabilità o aggiornamenti di sicurezza, segnalati per invitare all’aggiornamento.

Le sezioni prive di voci in una determinata release vanno omesse: inserirle vuote aggiunge rumore al documento senza fornire informazione, un principio che distingue un changelog curato da un semplice dump di commit.

Cosa deve contenere un changelog efficace

Ogni versione documentata deve riportare almeno il numero di release (ad esempio v1.2.0) e la data di pubblicazione, espressa nel formato ISO 8601 (AAAA-MM-GG): questo formato elimina l’ambiguità dei formati regionali, dove il giorno e il mese possono essere invertiti.

• Numero di versione: spesso allineato allo schema Semantic Versioning (SemVer), basato su major.minor.patch.
• Data di rilascio: sempre in formato AAAA-MM-GG, per restare leggibile a livello internazionale.
• Ordine cronologico inverso: la release più recente compare in cima al documento.
• Sezione “Unreleased”: raccoglie le modifiche già integrate ma non ancora pubblicate in una versione numerata.
• Categorizzazione delle modifiche: secondo le sei etichette standard descritte in precedenza.

La sezione “Unreleased” assolve una doppia funzione: consente di anticipare agli utenti cosa aspettarsi dal prossimo rilascio e, al momento della pubblicazione, basta rinominarla con il numero di versione e crearne una nuova vuota in cima al file.

Come scrivere un changelog: procedura in pratica

Impostare un changelog da zero richiede pochi passaggi ripetibili ad ogni rilascio, indipendentemente dal linguaggio o dal framework utilizzato dal progetto.

1. Crea un file dedicato, solitamente chiamato CHANGELOG.md, nella directory principale del progetto.
2. Aggiungi in cima una sezione “Unreleased” per raccogliere le modifiche non ancora pubblicate.
3. Per ogni rilascio, inserisci un’intestazione con numero di versione e data in formato ISO 8601.
4. Raggruppa le modifiche nelle categorie Added, Changed, Deprecated, Removed, Fixed, Security, mantenendo solo quelle con voci effettive.
5. Scrivi ogni voce in una riga sintetica, comprensibile anche a chi non consulta il codice sorgente.
6. Collega, dove utile, ogni voce al numero della issue o della pull request corrispondente per favorirne la verifica.
7. Prima della pubblicazione, rimuovi le sezioni rimaste vuote per non appesantire la lettura.

Se il progetto è open source o un prodotto commerciale: come cambia l’approccio

Se il progetto è open source: il changelog si rivolge principalmente a contributori e maintainer, va versionato insieme al codice e reso accessibile pubblicamente nel repository. Se invece si tratta di un prodotto SaaS o di un’app distribuita a clienti finali: il documento può affiancare una versione semplificata, mostrata direttamente nell’interfaccia, per comunicare le novità senza richiedere competenze tecniche.

Dove si trova e come si gestisce un changelog

Il file può assumere diversi nomi convenzionali: ChangeLog, CHANGES, CHANGELOG o, con estensione esplicita, CHANGELOG.md se scritto in Markdown, linguaggio di markup che permette di formattare titoli, elenchi e link senza strumenti complessi; approfondisci su cos’è il Markdown e come si usa per comprenderne la sintassi completa.

Molti sistemi wiki includono un registro delle modifiche come funzione integrata, spesso chiamato “cronologia”: è il caso delle pagine di Wikipedia, dove il link “Visualizza cronologia” porta all’elenco di tutte le revisioni di un contenuto. Un principio analogo si applica ai registri di modifica dei servizi geografici (WMS/WFS), dove il changelog riporta i nomi tecnici dei layer aggiornati, permettendo agli utenti di adeguare i propri applicativi GIS senza perdere funzionalità.

Oltre al file nel repository, molti prodotti digitali espongono un changelog in-app, pensato per aggiornare i clienti su nuove funzionalità e correzioni senza che debbano consultare la documentazione tecnica. Nei contesti basati su API, il changelog segnala in particolare le modifiche che alterano la compatibilità con le integrazioni esistenti, un’informazione critica per chi consuma il servizio in modo automatizzato.

Il file è spesso versionato nello stesso repository Git del progetto, piattaforma che ospita sia il codice sia, frequentemente, il changelog stesso: in questo contesto il registro delle modifiche resta distinto dalla cronologia dei commit, perché seleziona solo le informazioni rilevanti per chi utilizza il software, non ogni singola operazione tecnica.

Errori frequenti e casi limite nella gestione del changelog

Alcuni errori ricorrono con frequenza in progetti che adottano il changelog senza una convenzione chiara, compromettendone l’utilità per chi lo consulta.

• Copiare il git log così com’è: un dump di commit non filtrato non aiuta nessuno, perché mescola dettagli tecnici irrilevanti a modifiche realmente significative.
• Lasciare sezioni vuote: categorie senza voci occupano spazio e creano rumore informativo; vanno omesse finché non contengono almeno una modifica.
• Usare formati data regionali: un formato come MM-GG-AAAA genera ambiguità internazionale; il formato ISO 8601 (AAAA-MM-GG) elimina il problema.
• Confondere approccio storico e approccio curato: alcuni progetti registrano ogni singola modifica, altri solo quelle rilevanti per l’utente finale; la scelta va dichiarata esplicitamente nel file.
• Non distinguere pubblico tecnico e pubblico finale: un changelog pensato per sviluppatori, se mostrato tal quale a un utente non tecnico, rischia di risultare incomprensibile.

Va infine chiarito il confine con la patch: la patch è l’intervento tecnico che corregge un bug o chiude una vulnerabilità, mentre il changelog è il documento che registra e descrive quell’intervento dopo il rilascio. I due concetti sono collegati ma non coincidenti: la prima agisce sul codice, il secondo sulla comunicazione del cambiamento.

Domande frequenti

Cosa si intende per changelog?

Un changelog è un elenco curato e ordinato cronologicamente delle modifiche rilevanti apportate a un progetto software, suddiviso per versione. Non coincide con la cronologia automatica dei commit, ma seleziona solo le informazioni utili a chi utilizza o sviluppa il progetto.

Come si traduce “changelog” in italiano?

In italiano si traduce comunemente come “registro delle modifiche” o “giornale dei cambiamenti”. Nell’uso tecnico il termine inglese resta però la forma più diffusa, utilizzata anche nella documentazione in lingua italiana di progetti software e API.

Che differenza c’è tra changelog e note di rilascio?

Il changelog è il registro tecnico e completo delle modifiche per versione, rivolto principalmente a sviluppatori. Le note di rilascio sono invece un testo narrativo, pensato per l’utente finale, che racconta i benefici di un aggiornamento senza elencarne ogni dettaglio tecnico.

Cosa si intende per patch?

Una patch è una serie di comandi o modifiche al codice progettati per correggere un bug, aggiornare una funzionalità o risolvere una vulnerabilità di sicurezza. A differenza del changelog, che documenta l’intervento, la patch è l’intervento tecnico stesso.

Cosa si intende per markdown nel contesto del changelog?

Il Markdown è il linguaggio di markup più usato per scrivere i file changelog, perché permette di formattare titoli, elenchi e link in modo semplice e leggibile anche come testo semplice. Per i dettagli sulla sintassi, consulta la guida su Markdown: cos’è e come si usa.

Qual è la differenza tra changelog e log di Git?

Il git log è l’elenco automatico e completo di ogni commit registrato dal sistema di controllo versione, senza selezione editoriale. Il changelog, al contrario, riporta solo le modifiche rilevanti, scritte in un linguaggio comprensibile a chi non legge il codice sorgente.

Dove si trova di solito il changelog di un progetto software?

Il changelog si trova tipicamente come file nella directory principale del repository di codice, spesso con nome CHANGELOG.md. Molti prodotti digitali lo affiancano anche a una versione semplificata mostrata direttamente nell’interfaccia utente, per comunicare gli aggiornamenti senza competenze tecniche.

Che ruolo ha una piattaforma come GitHub nella gestione di un changelog?

GitHub è una delle piattaforme più diffuse per ospitare repository di codice e, al loro interno, il file del changelog: la piattaforma ne mostra il contenuto direttamente nella pagina del progetto, facilitandone la consultazione da parte di sviluppatori e collaboratori esterni.