Versioning semantico

Versioning semantico

1) Cos'è un SemVer e perché è necessario

• MAJOR - Modifiche incompatibili (breaking changes).
• MINOR è una nuova funzionalità compatibile con l'API.
• PATCH - Correzioni dei difetti reversibili.

Obiettivo: negoziare la stabilità dei contratti e ridurre il costo degli aggiornamenti.

2) Formato versione

• `MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD]`

`1. 4. 7 è un rilascio stabile.
`1. 5. 0-rc. 2 '- release candidate n ° 2.
`2. 0. 0+linux. arm64 '- I metadati build (non influiscono sulla comparazione delle versioni).

1. Prima si confrontano MAGGIOR, poi MINOR, poi PATCH.

2. Le release pre-release sono inferiori alla versione stabile corrispondente: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. I metadati build ('+...') non influenzano l'ordine: '1. 2. 0+001 == 1. 2. 0`.

3) Cosa è considerato breaking change

• Rimuove, rinomina o cambia la firma dei metodi/endpoint pubblici.
• Modifica il formato di accesso/uscita (schema JSON, tipi).
• Modifica dei contratti di errore (codici/strutture).
• Modifica side-effects/SLAs (ad esempio limiti rigorosi o nuovi campi obbligatori).

Non breaking (se implementato correttamente) - Aggiunge campi facoltativi, estensione enum con nuovi valori (se il client li ignora), nuovi endpoint, nuovi flag con default che non influiscono sulle chiamate correnti.

4) Release e strategie di canale

• Etichette: «alpha», «beta», «rc». Esempio: '2. 3. 0-beta. 3`.
• I canali sono nightly-alpha-beta-rc-stable.
• Criterio: le release pre-release non devono essere visualizzate come dipendenze transitive per gli assiemi prod predefiniti.

5) Intervalli di versione e precisione delle dipendenze

5. 1 Node/npm (SemVer predefinito)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(consente MINOR/PATCH, registra MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(consente PATCH entro MINOR).
`1. 4. X ', qualsiasi paghetta in 1. 4.
Pin esatto: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 'è un limite chiaro.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) '- inclusa/esclusiva.
Si consiglia un pino rigoroso per i manufatti critici prod.

5. 4 Go modules

I tag sono sempre completi. MINOR. PATCH ';' v2 + 'richiede il suffisso del modulo '/v2'.

Raccomandazione: per le applicazioni: pin precisi (reprodutile builds). Per le librerie - intervalli caret (agevolare gli aggiornamenti senza astinenza).

6) CHANGELOG и Conventional Commits

Il registro strutturato delle modifiche aumenta la trasparenza.

feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

Типы: `feat`, `fix`, `perf`, `docs`, `refactor`, `chore` и т. д.
Il punto esclamativo o il blocco «BREAKING CHANGE» dichiara l'aumento MAGGIORE.
CHANGELOG viene generato dalla storia dei commiti (release-note bot).

7) Criteri di versioning per API

API pubbliche: rigoroso; breaking → MAJOR.
HTTP/REST: versioning in base all'URL/titolo: '/v1/... ', '/v2/...' ó Accept: application/vnd. org. service. v2+json`.
Schemi JSON - Estensioni minori - nuovi campi opzionali major - Rimuovi/modifica le impostazioni obbligatorie.
gRPC/Protobuf - Aggiungere nuovi campi con nuovi numeri non utilizzare i numeri di campo. eliminare i → deprecate anziché «rompere» quelli esistenti.

8) Diagrammi di dati e migrazione

Le migrazioni del database vengono sincronizzate con le versioni dell'applicazione: 'app @ 1. 8. 0 'richiede' schema @ 1. 8. x`.
Per breaking le modifiche allo schema sono le fasi: espand (aggiungi), migrate, contract (elimina). Aumentare la versione a MAJOR solo quando si elimina il vecchio contratto.
Supporto della doppia scrittura/lettura durante la migrazione.

9) Monorepo e microservizi

Multi-package: ogni pacchetto ha il proprio «MAJOR». MINOR. PATCH`; ciclo di release radice generico solo per meta-manufatti.

• Indipendent versions (Lerna/Changesets) - Aumenta l'isolamento.
• Lock-step è più facile da comunicare, ma più falso MAJOR-ov.
• Per i microservizi, fissa i contratti (OpenAPI/Protobuf) con una versione separata: 'contract @ 2. 1. 0 ', il servizio la segue.

10) Automazione delle release in CI/CD

• `fix` → `PATCH`, `feat` → `MINOR`, `!`/`BREAKING` → `MAJOR`.

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

Generazione CHANGELOG, pubblicazione dei notti di release, aggiornamento delle dipendenze in GitOps-repo, verifica che «main» indica sempre l'ultimo tag stabile.

11) Criteri di deprivazione (deprecation policy)

Annuncio: contrassegna la funzione come deprecated nel comunicato MINOR, diamo un termine EOL (ad esempio 90 giorni).
Osservabilità: logica l'uso di endpoint obsoleti con un contesto user/tenant.
Elimina: in MAGGIORE: Documentare il percorso di migrazione.

12) Esempi e modelli

12. 1 Espressione regolare di validazione

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12. 2 Esempi di confronto

`1. 2. 3` < `1. 10. 0 '(confronto MINOR).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Criteri di dipendenza (esempio YAML)

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13) Anti-pattern

Utilizzo dì latest "/tag flottanti in vendita.
Aumento di MAJOR senza interruzioni reali (versioni marketing).
Modifiche breaking nascoste sotto l'aspetto PATCH.
Release pre-release nelle dipendenze transitive delle applicazioni prod.
Cambia l'artefatto senza nuovo tag (versioni mutabili).
Versioni incoerenti del codice e dello schema di database.

14) Assegno foglio di implementazione (0-45 giorni)

0-10 giorni

Accettate come standard obbligatorio, approvate i criteri di astinenza.
Includere Conventional Commits e il modello PR con il campo «BREAKING CHANGE».

11-25 giorni

Collegare semantic-release/changesets, generazione automatica CHANGELOG.
Configura la firma e la pubblicazione degli artefatti con il tag "vX. Y.Z`.

26-45 giorni

Immettere la deprecazione policy e la telemetria di utilizzo delle API obsolete.
Sincronizzare le versioni dei contratti (OpenAPI/Proto) e dei servizi.
Vietare i tag latest e mutabili a livello di criterio (ORA/Regolamenti CI).

15) Metriche di maturità

Il percento degli artefatti emessi solo con il tag SemVer.
Tempo medio di migrazione tra le versioni MINOR.
Numero di incidenti dovuti a cambiamenti di breaking nascosti.
Copertura Conventional Commits nei repository (> 95%).
Percentuale di dipendenze senza intervalli flottanti (> 90%).

16) Quando non è necessario un SemVer

Prototipi interni veloci senza consumatori esterni (adatto a versioning datato).
Dati/modelli con fiocchi sperimentali (meglio Model/Schema Versioning con compatibilità a livello di convertitori).
Pacchetti di contenuti senza API pubblica stabile.

17) Conclusione

SemVer è un contratto di fiducia tra produttore e consumatore. Determinare chiaramente cosa rompe la compatibilità, automatizza il riconoscimento dei tipi di release e la pubblicazione degli artefatti, gestisce CHANGELOG trasparente e rispetta le regole di deprivazione. In questo modo gli aggiornamenti saranno di routine, prevedibili e sicuri, mentre l'infrastruttura e l'API si svilupperanno senza shock per le aziende.