Tag git, release e il tuo changelog

Un tag git, una release e una voce di changelog sono tre registrazioni diverse dello stesso evento, e confonderli fa deragliare silenziosamente un changelog da ciò che è stato davvero rilasciato. Un tag marca un commit. Una release impacchetta quel tag con artefatti e una descrizione. Una voce di changelog spiega, in termini che una lettrice fuori dal repository può usare, cosa è cambiato. Di solito accadono vicini nel tempo, ed è proprio per questo che è facile trattarli come un unico passaggio invece di tre, ed è proprio per questo che il divario diventa visibile solo mesi dopo, quando qualcuno chiede “cosa è stato rilasciato nella v2.4” e la risposta onesta richiede una vera ricerca.

Qual è la differenza reale tra i tre?

Un tag è il più meccanico dei tre: git tag v2.4.0 e basta, senza alcun requisito che qualcosa spieghi cosa contiene. Una release aggiunge una descrizione e, di solito, artefatti scaricabili, e il suo pubblico rimane sviluppatrici che sanno cos’è una pagina di release. Una voce di changelog è l’unica delle tre scritta per una lettrice che potrebbe non aprire mai il repository, motivo per cui è quella che richiede più attenzione editoriale e quella più facilmente saltata sotto pressione di scadenze.

Ogni tag git ha bisogno di una voce di changelog?

No, e trattarli come uno a uno è un errore comune. Un tag può segnare una milestone interna, una release candidate, o un hotfix che non raggiunge mai la maggior parte delle utenti; nessuno di questi ha necessariamente bisogno di una voce pubblica. Il test è lo stesso che decide se qualcosa appartiene affatto a un changelog: se un’utente o chi chiama lo noterebbe o gliene importerebbe. La maggior parte dei tag passa questo test. Alcuni, come un tag creato solo per innescare una pipeline CI, mai.

Ogni voce di changelog ha bisogno del proprio tag?

Non sempre, ed è qui che i team che fanno deploy continuo divergono dai team che rilasciano pacchetti versionati. Un prodotto SaaS che fa più deploy al giorno può raggruppare più deploy sotto una voce di changelog datata senza un tag 1:1 per ogni deploy; una libreria pubblicata in un registro di pacchetti ha di solito bisogno di un tag per versione pubblicata. I moduli Go e Swift Package Manager risolvono le versioni direttamente dai tag; su npm o PyPI è il registro a conservare la versione pubblicata, e il tag è il modo in cui chiunque riconduce quella versione al suo sorgente. Un repository con più pacchetti versionati in modo indipendente deve deciderlo per pacchetto, non una volta sola per tutto il repo; changelog nei monorepo copre come i prefissi dei tag e l’ambito del changelog dovrebbero seguire i confini dei pacchetti, non delle cartelle. Semantic versioning e il tuo changelog copre come il numero di versione stesso dovrebbe mappare sulle categorie del changelog; i tag sono il meccanismo che rende un numero di versione verificabile contro il codice reale.

Come dovrebbe relazionarsi una descrizione di release con la voce di changelog?

Possono essere lo stesso testo, ma solo se il pubblico di entrambi è davvero lo stesso, il che è più raro di quanto sembri. Una pagina di release su un host di codice viene letta quasi esclusivamente da sviluppatrici; se un prodotto ha anche utenti non tecnici che leggono il changelog, duplicare la descrizione della release parola per parola manda termini interni e una formulazione orientata al codice a una lettrice che aveva bisogno della versione in linguaggio semplice. Lo schema più pulito: scrivere la voce di changelog come l’artefatto principale orientato alla lettrice, e lasciare che la descrizione della release la colleghi oppure mantenga un riassunto più breve e tecnico per il pubblico già a suo agio lì.

# Release v2.4.0 (GitHub, per sviluppatrici)
Aggiorna la pipeline dei report al nuovo motore di aggregazione. Vedi
il changelog per il riassunto orientato al cliente:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, orientato al cliente)
### Added
- I report ora si caricano in meno di un secondo, anche per account
  con più di un milione di righe.

Stessa release, due documenti, ognuno con la propria formulazione per la propria lettrice.

Da dove viene davvero la voce di changelog?

Da due punti di partenza, e la maggior parte delle pipeline reali è un misto di entrambi. Può essere generata dai messaggi di commit al momento del tag, il che è veloce e non perde mai una pull request unita; dai conventional commit al changelog copre quella pipeline per intero. Oppure può essere scritta a mano, separata dal tag, sincronizzata con il momento in cui una funzionalità è considerata pronta invece che con il momento in cui il codice viene unito. Le voci generate sono coerenti ma ereditano ogni messaggio di commit vago; le voci scritte a mano sono più chiare ma richiedono qualcuno che le scriva davvero. La maggior parte dei team che automatizza mantiene comunque un leggero passaggio di editing sul testo generato prima che diventi la voce pubblica, la stessa disciplina che raccomanda Keep a Changelog, in pratica, indipendentemente da dove sia originariamente venuto il testo grezzo.

Cosa si rompe quando i tre si desincronizzano?

La fiducia in quello che la lettrice ha controllato per prima. Un tag che esiste senza una voce di changelog corrispondente sembra, dal lato di chi legge il changelog, che quella settimana non sia successo nulla. Una voce di changelog senza tag o release corrispondente rende impossibile per chi sta facendo debug di un problema in produzione fare checkout del codice esatto che era live quando è stata pubblicata una voce. La soluzione non è l’automazione perfetta, è un’unica fonte di verità per la corrispondenza: un posto, anche solo la checklist stessa del processo di release, che dica che un cambiamento rilasciabile riceve tutti e tre, nello stesso commit o pull request che lo introduce.

FAQ

Le voci di changelog dovrebbero essere generate automaticamente dai tag git? Possono essere un punto di partenza, ma un tag da solo non porta nessuna descrizione orientata alla lettrice, solo un intervallo di commit. La generazione automatizzata deve leggere i messaggi di commit dentro quell’intervallo, non solo l’esistenza del tag, per produrre qualcosa di utilizzabile.

E se non taggiamo ogni release? Allora la voce di changelog diventa la registrazione principale, e dovrebbe comunque portare una data e, se il prodotto ne ha una, un numero di versione, così la voce resta qualcosa a cui una lettrice può fare riferimento più tardi anche senza un tag corrispondente.

I tag pre-release (come v2.4.0-rc.1) dovrebbero avere voci di changelog? In generale no. Una release candidate è per test interni o beta, e una voce di changelog per essa insegna alle lettrici ad aspettarsi voci per versioni che potrebbero non essere mai rilasciate così come descritte. Riserva le voci ai tag che raggiungono la disponibilità generale.

Una singola voce di changelog può coprire più tag git? Sì, e spesso dovrebbe per i team che taggano frequentemente. Raggruppa tag correlati sotto una voce datata che descriva il cambiamento netto, invece di pubblicare una voce sottile per tag che frammenta una funzionalità su più letture.

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: Generatore di changelog, Documentazione per sviluppatori