Esplora il versionamento semantico

  • 4 minuti

Uno dei modi predominanti per il controllo delle versioni è l'uso del controllo delle versioni semantiche (SemVer).

Il controllo delle versioni semantiche non è uno standard, ma offre un modo coerente per esprimere la finalità e la semantica di una determinata versione.

Descrive una versione in base alla compatibilità con le versioni precedenti.

Formato di versionamento semantico

Il controllo delle versioni semantiche usa un numero di versione in tre parti e un'etichetta facoltativa.

Formato Major.Minor.Patch

La versione ha la forma di Major.Minor.Patch che corrisponde ai tre tipi di modifiche descritte nella sezione precedente.

Struttura della versione:

  • Principale: primo numero, indica modifiche che causano interruzioni.
  • Minore: Secondo numero, indica le nuove funzionalità (compatibili con le versioni precedenti).
  • Patch: Terzo numero, indica le correzioni di bug (retrocompatibili).

Esempi di versioni che usano lo schema di controllo delle versioni semantico:

  • 1.0.0 - Versione stabile iniziale
  • 3.7.129 - Versione 3 con molti aggiornamenti secondari e patch
  • 2.0.0 - Versione principale 2 con modifiche che causano interruzioni

Queste versioni non hanno etichette.

Regole di incremento della versione

Quando incrementare ogni numero:

Incremento della versione principale (X.0.0)

  • Modifiche radicali: Apportare modifiche incompatibili all'API.
  • Rimuovere la funzionalità: Eliminare le funzionalità deprecate.
  • Modifiche dell'architettura: Riprogettazione fondamentale.

Esempio:

  • 1.5.3 → 2.0.0 quando vengono introdotte modifiche che causano interruzioni

Incremento della versione secondaria (x.Y.0)

  • Nuove funzionalità: Aggiungere funzionalità in modo compatibile con le versioni precedenti.
  • Funzionalità deprecate: Contrassegnare le funzionalità come deprecate (ma ancora funzionanti).
  • Miglioramenti: Miglioramenti sostanziali alle funzionalità esistenti.

Esempio:

  • 1.5.3 1.6.0→ quando si aggiungono nuove funzionalità

Incremento della patch (x.y.Z)

  • Correzioni: Apportare correzioni di bug compatibili con le versioni precedenti.
  • Patch di sicurezza: Correggere le vulnerabilità di sicurezza.
  • Miglioramenti delle prestazioni: Ottimizzazioni delle prestazioni minori.

Esempio:

  • 1.5.3 1.5.4→ per le correzioni di bug

Versioni preliminari

Per le versioni non definitive, è consuetudine usare un'etichetta dopo il numero di versione normale.

Formato dell'etichetta

Un'etichetta è un suffisso testuale separato da un trattino dal resto del numero di versione.

L'etichetta stessa può essere qualsiasi testo che descrive la natura della versione preliminare.

Struttura delle etichette:

Major.Minor.Patch-label

Etichette comuni di prerilascio

Esempi di questi sono rc1, beta27e alpha, che formano numeri di versione come:

  • 1.0.0-alpha - Versione di sviluppo iniziale, instabile.
  • 1.0.0-beta - Funzionalità completa, ma potenzialmente con bug.
  • 1.0.0-beta.2 - Seconda versione beta.
  • 1.0.0-rc1 - Versione candidata, potenzialmente pronta per il rilascio.
  • 1.0.0-preview - Versione di anteprima per il feedback anticipato.

Esempio di progressione della versione:

1.0.0-alpha.1
1.0.0-alpha.2
1.0.0-beta.1
1.0.0-beta.2
1.0.0-rc1
1.0.0-rc2
1.0.0

Convenzioni per le etichette pre-release

Prefissi di etichetta comuni:

  • alfa: Versione molto preliminare, aspettatevi bug e cambiamenti importanti.
  • Beta: Funzionalità completa, sottoposta a test.
  • rc (Release Candidate): Versione potenzialmente finale, ultima fase di test.
  • Anteprima: Anteprima anticipata per commenti e suggerimenti.
  • Dev: Snapshot di sviluppo.

Suffissi numerici:

Le etichette includono spesso numeri per versioni preliminari sequenziali:

  • 1.0.0-beta.1 1.0.0-beta.2 → →1.0.0-beta.3

Uso delle versioni prerelease

Le versioni non definitive sono un modo comune per prepararsi per il rilascio della versione senza etichetta del pacchetto.

Vantaggi delle versioni non definitive

Feedback iniziale:

Gli early adopter possono assumere una dipendenza da una versione non definitiva per la compilazione usando il nuovo pacchetto.

  • Integrazione dei test: Convalidare il funzionamento del pacchetto con i sistemi esistenti.
  • Segnalare i problemi: Individuare i bug prima del rilascio ufficiale.
  • Inviare commenti e suggerimenti: Suggerire miglioramenti o modifiche.

Implementazione graduale:

  • Rilascio a fasi: Rilasciare prima a un piccolo gruppo di utenti.
  • Mitigazione dei rischi: Rilevare i problemi prima del rilascio a livello generale.
  • Costruire fiducia: Costruire fiducia nella stabilità.

Avvertenze sulle versioni preliminari

In genere, l'uso di una versione preliminare dei pacchetti e dei relativi componenti per il software rilasciato non è una buona idea.

Rischi per l'uso di versioni preliminari nell'ambiente di produzione:

  • Instabilità: Le versioni non definitive potrebbero avere bug non individuati.
  • Modifiche di rilievo: Le versioni preliminari future potrebbero introdurre modifiche di rilievo.
  • Nessuna garanzia: Nessuna garanzia di compatibilità con le versioni precedenti.
  • Limitazioni del supporto: Supporto limitato o non disponibile per le versioni non definitive.

Test delle versioni non definitive

È consigliabile prevedere l'impatto dei nuovi componenti creando un ramo separato nella codebase e usando la versione non definitiva del pacchetto.

Procedure consigliate per il test delle versioni non definitive:

  • Ramo separato: Creare un ramo di funzionalità per il test.
  • Ambiente isolato: Testare in un ambiente non di produzione.
  • Monitorare il comportamento: Controllare il comportamento imprevisto o i problemi di prestazioni.
  • Problemi relativi ai documenti: Tenere traccia di eventuali problemi rilevati.

È probabile che ci saranno modifiche incompatibili da una versione preliminare alla versione finale.

Metadati e informazioni di compilazione

SemVer 2.0 supporta anche i metadati di compilazione aggiunti con un segno più:

1.0.0-beta.1+20231015.abc123

Metadati di compilazione:

  • Non considerato nella precedenza della versione: Due versioni diverse solo nei metadati di compilazione sono considerate uguali.
  • Scopo delle informazioni: Utile per tenere traccia dei numeri di compilazione, hash di commit.
  • Esempio:1.0.0+build.123 o 1.0.0-beta+exp.sha.5114f85

Precedenza della versione

SemVer definisce regole chiare per la precedenza della versione:

Regole di confronto

  1. Confronto delle versioni principali, secondarie e patch: in ordine numerico.
  2. Versioni non definitive: Avere sempre una precedenza inferiore rispetto alla versione normale associata.
  3. Confronto tra etichette: Segmenti alfanumerici confrontati lessicalmente, segmenti numerici confrontati numericamente.

Esempi in ordine (dal più basso al più alto):

1.0.0-alpha
1.0.0-alpha.1
1.0.0-alpha.beta
1.0.0-beta
1.0.0-beta.2
1.0.0-beta.11
1.0.0-rc.1
1.0.0
1.0.1
1.1.0
2.0.0

Vantaggi del controllo delle versioni semantici

Comunicazione chiara:

  • Intento: Il numero di versione comunica chiaramente la natura delle modifiche.
  • Compatibilità: Facile determinare se l'aggiornamento è sicuro.
  • Prevedibilità: Controllo delle versioni coerente tra i pacchetti.

Gestione automatica delle dipendenze:

  • Vincoli di versione: Gli strumenti di gestione pacchetti possono risolvere automaticamente le versioni.
  • Aggiornamenti sicuri: Gli strumenti possono essere aggiornati in modo sicuro alle versioni compatibili.
  • Risoluzione dei conflitti: È più facile risolvere i conflitti di dipendenza.

Adozione dell'ecosistema:

  • Standard del settore: Ampiamente adottato in molti ecosistemi.
  • Supporto degli strumenti: Gli strumenti di gestione pacchetti comprendono SemVer.
  • Aspettative della community: Gli sviluppatori si aspettano la conformità SemVer.

Controllo delle versioni semantiche in Azure Artifacts

Azure Artifacts supporta il controllo delle versioni semantiche in tutti i tipi di pacchetto:

  • NuGet: Supporto di SemVer 2.0 nativo.
  • npm: SemVer è lo standard.
  • Maven: Compatibile con i principi SemVer.
  • Python: PEP 440 è compatibile con i concetti di SemVer.
  • Pacchetti universali: Usa SemVer 2.0.

Visualizzazioni feed e SemVer:

  • @Visualizzazione delle versioni preliminari: Include automaticamente le versioni con le etichette.
  • @Visualizzazione di rilascio: Includere solo versioni senza etichette.
  • @Vista locale: Mostra tutte le versioni indipendentemente dall'etichetta.

Implementazione del controllo delle versioni semantiche

Controllo delle versioni manuale:

  • Aggiornare i file del pacchetto: Aggiornare manualmente la versione in package.json, .nuspece così via.
  • Eseguire il commit con tag: Assegnare un tag al commit con il numero di versione.

Controllo delle versioni automatizzato:

# Using npm version command
npm version patch  # Increment patch: 1.0.0 -> 1.0.1
npm version minor  # Increment minor: 1.0.1 -> 1.1.0
npm version major  # Increment major: 1.1.0 -> 2.0.0

# With prerelease
npm version prerelease --preid=beta  # 1.0.0 -> 1.0.1-beta.0

In pipeline CI/CD:

# Azure Pipelines example
- task: GitVersion@5
  inputs:
    runtime: "core"
    configFilePath: "GitVersion.yml"

- script: |
    echo "Semantic Version: $(GitVersion.SemVer)"
    echo "NuGet Version: $(GitVersion.NuGetVersion)"
  displayName: "Display version"

Vedere anche Semantic Versioning 2.0.0.