Semantic Versioning e Conventional Commits

Indice dei contenuti

• Che cos’è il versioning?
• Il Semantic Versioning 
• Varianti nel Semantic Versioning 
• La possibilità di avere una versione 0.0.0 
• Conventional Commits 
• Vantaggi per la sicurezza e lo sviluppo 
• Esistono alternative ai Conventional Commits? 
• Confronto con i Conventional Commits 

---

Questo articolo esplora due strumenti fondamentali per organizzare il lavoro dei team di sviluppo: il Semantic Versioning (SemVer), una metodologia per il versionamento semantico del codice, e i Conventional Commits, una convenzione per standardizzare i messaggi di commit.  

Entrambi migliorano la chiarezza, l’efficienza e la sicurezza dei processi di rilascio e manutenzione del software. 

Che cos’è il versioning? 

Il Versioning è il processo di assegnare un identificatore unico e progressivo a ogni nuova versione di un software. Questo aiuta a catalogare le modifiche, monitorare le correzioni di bug e rilasciare aggiornamenti strutturati.

Strumenti di controllo delle versioni come Git sono essenziali per il tracciamento delle modifiche e permettono agli sviluppatori di lavorare su più branch contemporaneamente. 

Tra i vantaggi del Versioning troviamo: 

• migliora la tracciabilità delle modifiche apportate; 

• facilita il tracciamento dei problemi segnalati dagli utenti, aiutando il mantainer del prodotto a identificare meglio il problema. 

• consente l’uso dello stesso prodotto con funzionalità diverse in base alle esigenze e alla disponibilità dell’utente finale (tester, sviluppatore o utente comune); 

• permette una comunicazione chiara delle nuove funzionalità: permette all’utente di identificare le funzionalità utilizzate nel prodotto leggendo la documentazione di rilascio associata. 

• supporto per ambienti open source, dove più sviluppatori collaborano sullo stesso progetto; 

• consente la parallelizzazione del lavoro, poiché è possibile lavorare con più versioni contemporaneamente per lo stesso prodotto, accelerando il processo di distribuzione. In sostanza garantisce la capacità di gestire parallelamente versioni patch, versioni minor e versioni major, ognuna adatta a specifiche esigenze. 

Il Semantic Versioning 

Cos’è il SemVer? Il versionamento semantico è uno standard che definisce una struttura chiara per i numeri di versione: MAJOR.MINOR.PATCH. Questo metodo consente a sviluppatori e utenti di comprendere facilmente le modifiche introdotte in ogni nuova versione. 

• MAJOR
  Incrementato quando vengono introdotti cambiamenti che rompono la retrocompatibilità. 

• MINOR
  Aggiornato per aggiungere nuove funzionalità senza compromettere la retrocompatibilità. 

• PATCH
  Incrementato per ogni bug fix o correzione di bug che non altera la retrocompatibilità. 

Ad esempio la versione 1.0.0: 

• si passa alla 1.0.1 non solo in caso di vulnerabilità ma anche in caso di correzione di bug;

• una minor release version che introduce funzionalità porta a 1.1.0;

• modifiche incompatibili con versioni precedenti generano la 2.0.0. 

Questa logica strutturata rende il Semantic Versioning uno standard riconosciuto e facilmente integrabile nei processi CI/CD. 

Altro esempio di semantics version

1.3.5 (1 = major, 3 = minor, 5 = patch)

Aggiornamenti gerarchici: 

• solo correzioni compatibili: da 1.3.5 a 1.3.6;

• nuove funzionalità compatibili: da 1.3.5 a 1.4.0;

• cambiamenti che interrompono la compatibilità: da 1.3.5 a 2.0.0. 

Varianti nel Semantic Versioning 

Oltre alla struttura base di semantics versioning, esistono estensioni utili per la fase di sviluppo e testing: 

• Identificatori di pre-release
  Come -alpha o -beta, segnalano versioni instabili. 

• Metadati di build
  Come +20240101, aggiungono informazioni sulla compilazione senza influire sul numero di versione. 

Esempio
1.0.0-alpha indica una fase sperimentale, mentre 1.0.0+build1234 può includere dettagli specifici. 

La possibilità di avere una versione 0.0.0 

Non è possibile avere una versione 0.0.0 secondo le linee guida del SemVer. Questo perché il valore 0 per il MAJOR rappresenta una fase in cui il prodotto è ancora in sviluppo e non è considerato pronto per un rilascio ufficiale. 

Nella pratica, la versione più bassa consentita è 0.1.0. Ecco come funziona: 

• Il valore 0 nel MAJOR
  Indica che il prodotto si trova in una fase iniziale, di pre-rilascio, durante la quale potrebbe subire modifiche sostanziali e frequenti, con la possibilità di introdurre cambiamenti che rompono la compatibilità senza particolari vincoli. 

• I valori MINOR e PATCH
  Vengono utilizzati per identificare aggiornamenti progressivi durante questa fase di sviluppo. 

• MINOR
  Viene incrementato per aggiungere nuove funzionalità che non rompono la compatibilità interna del codice. 

• PATCH
  Viene incrementato per correggere bug o apportare modifiche di minore entità. 

Quando passare a 1.0.0 

Una volta che il prodotto raggiunge una stabilità sufficiente per essere distribuito al pubblico o utilizzato in ambienti di produzione, il MAJOR viene incrementato a 1, e si passa alla versione 1.0.0.

Questo cambio di versione segnala che il prodotto è pronto per un uso più ampio e che eventuali modifiche che interrompono la compatibilità saranno trattate con maggior cautela, seguendo le regole del SemVer. 

Esempio pratico 

Supponiamo di avere un progetto in fase iniziale: 

• prima versione di sviluppo: 0.1.0;

• aggiunta di una nuova funzionalità durante lo sviluppo: 0.2.0;

• correzione di un bug: 0.2.1. 

Una volta completato lo sviluppo e raggiunta una certa stabilità, si passerà alla versione 1.0.0 per indicare il primo rilascio ufficiale. 

In sintesi, la numerazione 0.0.0 non è contemplata perché non avrebbe senso pratico: lo 0 nel MAJOR già rappresenta una fase preliminare, mentre i valori MINOR e PATCH servono per definire progressi specifici in quella fase. 

Conventional Commits 

Se il SemVer semplifica la gestione delle versioni, i Conventional Commits garantiscono coerenza nella documentazione delle modifiche al codice. Questo standardizza i messaggi di commit nel formato: 

<type>([optional scope]): <description> 

[optional body] 

[optional footer(s)]

Ogni commit include: 

• Tipo
  Specifica la Macro-attività, natura del cambiamento (feat, fix, chore, ecc.). 

• Scope (facoltativo)
  Indica la sezione del codice interessata. 

• Description
  Breve spiegazione della modifica. 

• Body (facoltativo)
  Dettagli aggiuntivi. 

• Footer (facoltativo)
  Metadati come riferimenti a ticket o reviewer. 

Esempio 

fix(command): modificata richiesta di sovrascrittura 

Ora la sovrascrittura elimina l'ultimo file invece di crearne uno nuovo 

Reviewed by: PB 

Refs: a00078c

I Conventional Commits possono essere collegati al SemVer: 

• un commit fix incrementa la versione patch  (es. 1.3.5 → 1.3.6);

• un commit feat incrementa la minor version  (es. 1.3.5 → 1.4.0);

• un commit con BREAKING CHANGE aumenta la major version  (es. 1.3.5 → 2.0.0). 

Vantaggi per la sicurezza e lo sviluppo 

L’adozione di SemVer e Conventional Commits offre vantaggi concreti, soprattutto nei progetti open source: 

• migliora la leggibilità della cronologia delle modifiche;

• automatizza la generazione di changelog;

• supporta pipeline CI/CD per un rilascio più sicuro;

• consente agli utenti di scegliere le versioni in base alle loro necessità. 

Esistono alternative ai Conventional Commits? 

Sì, esistono diverse alternative ai Conventional Commits, che possono essere altrettanto valide a seconda delle esigenze del progetto e degli strumenti utilizzati. Sebbene i Conventional Commits siano una proposta solida e largamente adottata, altre convenzioni o strumenti possono offrire funzionalità simili o complementari. 

Ecco alcune alternative e approcci utili: 

Gitmoji 

Il formato Gitmoji è un’alternativa informale e visivamente accattivante, che utilizza emoji per identificare il tipo di modifica apportata. Ad esempio: 

• Fix
  Correzione di un bug. 

• Feat
  Aggiunta di una nuova funzionalità. 

• Docs
  Modifiche alla documentazione. 

• Perf
  Miglioramento delle prestazioni. 

Questa convenzione rende la cronologia dei commit più immediata e facile da leggere, soprattutto per team che preferiscono un approccio più leggero e meno formale. 

Gitflow Workflow 

Il Gitflow Workflow è un modello di gestione dei rami (branches) che stabilisce una struttura gerarchica per lo sviluppo del codice. Pur non essendo una convenzione sui messaggi di commit, Gitflow consente di organizzare meglio il ciclo di sviluppo e il rilascio delle versioni. 

I rami principali sono: 

• Main/master
  Contiene il codice pronto per la produzione. 

• Develop
  Contiene il codice in fase di sviluppo. 

• Feature/
  Rami dedicati a nuove funzionalità. 

• Hotfix/
  Rami per correggere bug urgenti. 

• Release/
  Rami per finalizzare una nuova versione. 

Sebbene Gitflow non definisca come scrivere i commit, la struttura dei rami può essere integrata con altre convenzioni, come i Conventional Commits, per migliorare la coerenza. 

Custom Commit message guidelines 

Alcuni team preferiscono creare linee guida personalizzate per i messaggi di commit. Queste regole sono spesso adattate al contesto specifico del progetto e possono includere: 

• riferimenti a numeri di ticket (es. Jira, Trello);

• livelli di priorità per il tipo di modifica;

• regole stilistiche particolari per rendere i commit leggibili e comprensibili. 

Esempio
Un commit potrebbe essere scritto come segue: 

[TASK-123] Added support for multi-language feature.

Changelog-first approach

Questa metodologia pone il changelog al centro della gestione del codice. Invece di concentrarsi sui messaggi di commit, gli sviluppatori scrivono prima un aggiornamento chiaro del changelog e poi lo associano ai commit.

Strumenti come Keep a Changelog o plugin per CI/CD possono automatizzare l’associazione tra changelog e messaggi di commit. 

Strumenti e integrazioni con Issue Tracker 

Molti strumenti di gestione dei progetti, come Jira, Wrike o ClickUp, offrono integrazioni con i sistemi di controllo versione (VCS) per mantenere ordine nel codice.

Esempio
Un commit potrebbe includere direttamente un riferimento a un task specifico. E le convenzioni di commit possono essere basate sul formato richiesto dallo strumento (es. TASK-101: Update database schema). 

Questi strumenti possono anche automatizzare il collegamento tra codice e task manager, semplificando il tracciamento delle modifiche. 

Squash Commits 

In alcuni progetti, invece di definire una convenzione per ogni commit, si preferisce utilizzare il squash commits, cioè consolidare più commit in uno solo al momento del merge.

Questo approccio è particolarmente utile per mantenere una cronologia dei commit pulita, soprattutto in repository pubblici con molti collaboratori. 

Esempio
Una serie di commit con messaggi descrittivi ma non standard viene compressa in un unico commit strutturato al momento del merge nel ramo principale. 

Confronto con i Conventional Commits 

Ogni alternativa ha vantaggi e svantaggi rispetto ai Conventional Commits. Ecco alcuni aspetti da considerare: 

• Formalità
  Conventional Commits sono più rigorosi rispetto a Gitmoji o linee guida personalizzate. 

• Automazione
  Molte alternative non supportano la generazione automatica di changelog o l’attivazione di pipeline CI/CD come fanno i Conventional Commits. 

• Adattabilità
  Soluzioni personalizzate o basate su strumenti come Jira possono essere più flessibili ma meno standardizzate. 

• Accessibilità
  Approcci visivi come Gitmoji sono intuitivi per team meno tecnici, mentre Conventional Commits sono orientati a progetti con esigenze più complesse. 

Conclusioni 

In un panorama tecnologico sempre più complesso, strumenti come il Sìemantic Versioning e i Conventional Commits sono fondamentali per organizzare il lavoro in modo chiaro e sicuro.

Con una gestione strutturata dei numeri di versione e dei messaggi di commit, si ottengono vantaggi non solo tecnici, ma anche comunicativi e organizzativi, sia per gli sviluppatori che per gli utenti finali. 

---

Domande e risposte 

1. Cos’è il Semantic Versioning?
   È un sistema di versionamento semantico che assegna numeri di versione in base a modifiche MAJOR, MINOR e PATCH. 

2. Qual è la struttura base di un numero di versione?
   MAJOR.MINOR.PATCH, dove ogni segmento è separato da punti e rappresenta una categoria di cambiamenti. 

3. Cosa indica una minor release?
   Una minor release introduce nuove funzionalità senza rompere la retrocompatibilità. 

4. Qual è il significato della versione 1.0.0?
   La versione 1.0.0 rappresenta il primo rilascio stabile di un prodotto. 

5. Quando si incrementa la versione patch?
   Per ogni correzione di bug compatibile con le versioni precedenti. 

6. Che differenza c’è tra major e minor version?
   Una versione major introduce cambiamenti incompatibili; una minor version aggiunge nuove funzionalità compatibili. 

7. Come funzionano gli identificatori di pre-release?
   Identificano versioni instabili, come -alpha o -beta, usate durante lo sviluppo. 

8. Perché usare Conventional Commits?
   Standardizzano i messaggi di commit, migliorando leggibilità e automazione dei processi CI/CD. 

9. È possibile usare Semantic Versioning in progetti open source?
   Sì, è ideale per organizzare le nuove versioni in progetti collaborativi. 

10. Come automatizzare il versionamento con Semantic Versioning?
    Tramite integrazione con strumenti CI/CD, che generano automaticamente numeri di versione e changelog. 

11. Come assicurarsi che tutti i contributori usino Conventional Commits?
    È sufficiente richiedere una pull request per revisionare e consolidare i commit. 

12. Che fare se trovo un problema dopo il rilascio?
    Se il problema emerge in testing, si può aggiungere un pre-release; altrimenti, incrementare il PATCH.