Tag e Semantic Versioning

Un tag Git dà un nome stabile a un commit. Una release usa quel nome per dire: questa è la versione pubblicata.

Semantic Versioning aggiunge significato al nome: MAJOR.MINOR.PATCH comunica compatibilità e impatto del cambiamento.

Perché questa lezione conta

Senza tag, una release è “quel commit di ieri”. Senza policy di versioning, v2.3.4 è solo un numero decorativo.

Tag e SemVer aiutano utenti, team, CI e strumenti di deploy a sapere cosa è stato rilasciato, quando e con quale compatibilità.

Obiettivo operativo

Alla fine della lezione devi saper creare tag annotati, pusharli, leggerli, cancellarli se necessario e decidere quando aumentare major, minor o patch.

Tag leggeri e annotati

Tag leggero:

git tag v1.2.3

È solo un riferimento.

Tag annotato:

git tag -a v1.2.3 -m "Release 1.2.3"

Contiene autore, data e messaggio. Per release, preferisci tag annotati.

Push:

git push origin v1.2.3

Evita git push --tags se non vuoi pubblicare tutti i tag locali.

Vedere tag

git tag
git tag --list "v1.*"
git show v1.2.3
git log --oneline --decorate

Per capire commit tra due tag:

git log v1.2.2..v1.2.3 --oneline

SemVer

Formato:

MAJOR.MINOR.PATCH

Incrementa:

PATCH per bugfix compatibili.

MINOR per nuove funzionalità compatibili.

MAJOR per breaking change.

Esempi:

1.4.2 -> 1.4.3 fix compatibile
1.4.2 -> 1.5.0 nuova feature compatibile
1.4.2 -> 2.0.0 breaking change

Compatibilità reale

SemVer funziona solo se il progetto definisce cosa considera API pubblica. In una libreria può essere il contratto esportato. In una API HTTP può essere formato delle risposte, codici errore e parametri accettati. In un sito può essere meno utile, salvo pacchetti, plugin o integrazioni esterne.

Prima di cambiare major chiediti: quale consumatore si rompe? Prima di cambiare minor chiediti: la feature è compatibile? Prima di cambiare patch chiediti: sto davvero correggendo senza cambiare contratto?

Prerelease:

2.0.0-alpha.1
2.0.0-beta.1
2.0.0-rc.1

Release note

Una release utile contiene:

1. tag;
2. data;
3. changelog;
4. breaking change;
5. migrazioni;
6. asset se necessari;
7. checksum o firme se richieste.

Su GitHub/GitLab, la release è spesso un oggetto sopra il tag: aggiunge descrizione e asset.

Tag e CI/CD

Molte pipeline rilasciano quando vedono un tag:

on:
  push:
    tags:
      - "v*"

Questo rende il tag un comando operativo, non solo una nota storica. Prima di taggare devi sapere se partiranno build, deploy, pubblicazione pacchetti o notifiche.

Regola consigliata:

merge su main
CI verde
creazione tag annotato
push del tag specifico
pipeline release
verifica artefatti

Se la pipeline usa tag, evita prove locali con nomi che sembrano release vere. Usa prerelease chiare o repository sandbox.

Correggere un tag

Se un tag è sbagliato ma non pubblicato:

git tag -d v1.2.3
git tag -a v1.2.3 -m "Release 1.2.3" <sha-corretto>

Se è già pubblicato, fermati. Cambiare tag pubblici rompe fiducia e automazioni. Spesso è meglio creare v1.2.4 o documentare l’errore.

Laboratorio guidato

In un repo demo:

1. crea tre commit;
2. crea tag annotato v0.1.0;
3. aggiungi un fix e tagga v0.1.1;
4. aggiungi feature e tagga v0.2.0;
5. scrivi changelog tra tag;
6. simula breaking change e scegli versione.

Output atteso

Una policy:

Tag annotati per release.
Formato vMAJOR.MINOR.PATCH.
Patch per fix.
Minor per feature compatibili.
Major per breaking.
Tag pubblici non si riscrivono.

Errori comuni

Tag leggeri per release importanti. Mancano metadati utili.

Pushare tutti i tag per errore. Pubblica tag locali non pronti.

Cambiare tag pubblici. Può rompere deploy e dipendenze.

Versionare a sentimento. Senza regole, SemVer non comunica nulla.

Checklist di verifica

• so creare tag annotati;
• so pushare un tag specifico;
• so vedere changelog tra tag;
• so decidere patch/minor/major;
• la policy dice cosa fare con tag sbagliati.

Collegamenti

• Modulo: Workflow di team — lezione 30 del corso.
• Il capstone usa tag e policy di workflow come parte della consegna finale.