guides

Il versionamento semantico, quasi sempre abbreviato in SemVer, e un semplice insieme di regole per numerare le release del software in modo che il numero di versione stesso ti dica cosa e cambiato. Invece di un contatore privo di significato, una versione SemVer e composta da tre numeri, MAJOR.MINOR.PATCH, come 2.4.1, e ogni posizione ha un significato preciso. Una volta che conosci le regole, puoi guardare un incremento di versione e capire immediatamente se un aggiornamento e sicuro, aggiunge funzionalita o potrebbe rompere il tuo codice.

Le tre parti rispondono ciascuna a una domanda diversa. MAJOR (il primo numero) aumenta quando apporti modifiche incompatibili che rompono la compatibilita nell'API pubblica, e l'aggiornamento potrebbe richiederti di modificare il tuo codice. MINOR (il secondo) aumenta quando aggiungi nuove funzionalita in modo retrocompatibile, nuove funzioni che puoi adottare o ignorare. PATCH (il terzo) aumenta per le correzioni di bug retrocompatibili, correzioni sicure che non cambiano il modo in cui si usa il software.

Ci sono due regole meccaniche che mettono in difficolta le persone. Quando aumenti MAJOR, azzeri MINOR e PATCH: dopo 1.4.2, una modifica che rompe la compatibilita diventa 2.0.0, non 2.4.2. Quando aumenti MINOR, azzeri PATCH: dopo 1.4.2, una nuova funzionalita diventa 1.5.0. Quindi i numeri a destra ripartono sempre da zero quando un numero alla loro sinistra aumenta.

SemVer ha anche una regola speciale per le fasi iniziali dello sviluppo. Qualsiasi versione che inizia con 0, come 0.3.1, e considerata instabile, e le normali garanzie non si applicano del tutto. Durante la fase 0.x, l'API puo cambiare in qualsiasi momento, quindi tratta quelle release con cautela. Il passaggio a 1.0.0 e un segnale deliberato: significa che l'autore si impegna a mantenere un'API pubblica stabile e a seguire le regole di SemVer da quel momento in poi.

Oltre ai tre numeri principali, SemVer supporta le etichette di pre-release e di build. Una versione di pre-release aggiunge un trattino e un identificatore, come 1.0.0-alpha, 1.0.0-beta.2 o 1.0.0-rc.1, e ha una precedenza inferiore rispetto alla release finale, quindi 1.0.0-rc.1 viene prima di 1.0.0. I metadati di build possono essere aggiunti dopo un segno piu, come 1.0.0+20260715, ma vengono ignorati quando si confrontano le versioni. Questo permette ai team di distribuire build di test senza far credere che siano release finite.

Il motivo per cui tutto questo e importante e la gestione delle dipendenze. Quando il tuo progetto dipende da una libreria, raramente fissi per sempre una versione esatta; consenti un intervallo. I gestori di pacchetti usano SemVer per rendere sicuri quegli intervalli. In npm, per esempio, un intervallo con il caret come ^1.2.3 indica qualsiasi versione da 1.2.3 fino a, ma non incluso, 2.0.0, tutti gli aggiornamenti retrocompatibili e nessuno di quelli che rompono la compatibilita. Un intervallo con la tilde come ~1.2.3 e piu restrittivo e consente gli aggiornamenti patch fino a, ma non incluso, 1.3.0.

Quegli intervalli funzionano solo perche tutti concordano su cosa significhi un incremento di versione. Se una libreria distribuisce una modifica che rompe la compatibilita ma incrementa solo PATCH, puo rompere silenziosamente ogni progetto che si e fidato dell'intervallo. Questo e il contratto sociale al cuore di SemVer: il numero e una promessa sulla compatibilita, e rispettarlo e cio che impedisce all'intero ecosistema degli aggiornamenti automatici di andare in pezzi.

SemVer e definito da una specifica breve e leggibile su semver.org, ed e lo schema usato da npm, Cargo e innumerevoli altri registri e strumenti per i pacchetti. Non e l'unico modo di versionare il software, alcuni progetti usano il versionamento basato sul calendario (come 2026.07) o uno schema proprio, ma SemVer e il piu ampiamente compreso, e conoscerlo rende molto piu facile leggere i changelog e gli intervalli di dipendenza.

In pratica, la conclusione e questa: leggi una versione come una frase. Un salto nel primo numero dice di fermarti e verificare le modifiche che rompono la compatibilita prima di aggiornare. Un salto nel secondo dice che ci sono nuove funzionalita ma il tuo codice esistente e al sicuro. Un salto nel terzo dice che si tratta di una correzione di bug sicura. Quella singola abitudine, leggere la posizione che e cambiata, trasforma un numero opaco in un messaggio chiaro sul rischio.