Versioning semantico

Semantic Versioning (SemVer) - Un contratto per capire come il numero di versione riflette la natura delle modifiche. Formato MAGGIORE. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - Modifiche incompatibili (breaking).
• MINOR - Fici/estensioni riconducibili.
• PATCH - Correzioni di errore/protezione invertite.

Obiettivo: l'evoluzione prevedibile di API, eventi, schemi di dati, SDK e configure senza guasti improvvisi dei consumatori.

1) Convenzione dei numeri

X.Y.Z[-alpha.1    -rc.1][+build.sha]

Pre-release - Assemblaggi instabili non promettono compatibilità.
Build metadata ('+ sha') - Non influisce sull'ordine di confronto, utile per la traccia.
Fino a 1. 0. 0 qualsiasi modifica può essere considerata breaking (ma è meglio rispettare le regole fin dall'inizio).

2) Cosa conta breaking/minore/patch

• Registrazioni di bagagli e sicurezza senza cambio di contratto.
• I Doc Update che non interessano il contratto.
• Ottimizzazioni senza modificare risposte/eventi/diagrammi.

• Aggiunge nuovi campi/metodi/endpoint opzionali.
• Espansione enum con valori se i consumatori sono tollerati con valori sconosciuti.
• Nuovi indici di database, colonne nullable con default, nuovi eventi in aggiunta ai vecchi.

• Elimina o rinomina i campi, modifica i tipi e l'obbligatorietà.
• Modifica semantica/stato/codice di errore.
• Cambia il formato di serializzazione, lo schema delle chiavi, il protocollo di trasporto.
• Compressione/fusione di topic, trasferimento del significato dell'evento, modifica dello schema di partitura.
• Migrazioni di database che richiedono un failover dual-fase senza interoperabilità.

3) Versioning per manufatti

3. 1 REST

Le opzioni sono "URI/v1/...", intestazioni ("Accept: application/vnd. acme. game+json; versione = 1 '), parametro.
Raccomandazione: versione URI per API pubbliche; per interni - attraverso il titolo c negotion.
MINOR - Aggiungere campi opzionali, nuovi filtri/risorse non cambiare le risposte esistenti.
PATCH - Fissi, descrizioni, ordinamenti stabili.

3. 2 gRPC

Cambia le firme/tipi di → MAJOR (nuovo pacchetto/servizio: 'acme. wallet. v2`).
Nuovi campi con etichetta optional; il server deve ignorare quelli sconosciuti.
I campi non vengono eliminati: «depricate + prenotare il numero», ma solo in MAGGIORE.

3. 3 GraphQL

MINOR: nuovi campi/tipi/query; rimuovendo - «@ deprecated» + la finestra di migrazione, l'eliminazione completa è MAGGIORE.
Modifica nullable→non -nullable - MAJOR.

3. 4 Eventi e topici (Kafka/SQS)

Schemi in Schema Registry - Evoluzione additive (aggiungere campi con default).
La nuova versione incompatibile → un nuovo subject/topic ('bet. settled. v2`).
La chiave di partitura è invariata all'interno di MAJOR.

3. 5 Diagrammi di database

1. Aggiungi colonna (nullable/con default)

2. Riempire il backfill

3. Traduce le letture

4. Rimuovi il vecchio (solo in MAJOR).

Cambia il tipo/RC/Unicità - MAGGIORE, sotto il phicheflag e il doppio record.

3. 6 SDK/CLI

Metodi/firme pubblici sono le stesse regole.
Per la genetica automatica (OpenAPI/Proto), la versione del nome batch e degli artefatti.

4) Politica di depricaggio e ciclo di vita

Ogni modifica breaking è preceduta da depricaggio (generalmente 90-180 giorni per gli esterni, 30-60 per quelli interni).
Comunicazioni: changelog, e-mail/webhoop ai partner, banner sul portale dello sviluppatore.
Modalità dual-run: in parallelo, teniamo v1 e v2, monitor la quota di traffico v1.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

Il client invia la versione desiderata + massima supportata (ad esempio, 'Accept-Variante: 1,2').
Il server risponde à Content-Variante: 2 "se è stato in grado di aumentare.
Nei protocolli bidirezionali (WebSocket, gRPC), lo scambio di cornici Hello con'supported _ variations '.

6) Integrazione con i provider (ACL)

Il provider esterno cambia schema - all'interno dell'adattatore, teniamo i maker v1/v2 e rilasciiamo MINOR per l'evento interno, mantenendo il nostro contratto di dominio.
Se le modifiche esterne vengono apportate all'interno, sono MAJOR del nostro evento di dominio e un nuovo subject.

7) Changelog e etichette dei commiti

• `feat:...` → MINOR
• "fix:... '/' chore ',' docs', 'perf' (senza contratto) → PATCH
• "feat!: '/' fix!: '/' refactor! 'o' BREAKING CHANGE: 'NEL CORPO DEL MAGGIORE

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) Automazione dei lanci

CI: Validatori di diagrammi (OpenAPI/Protobuf/Avro/JSON-Schema), oggetto di breaking-diffusi.
SemVer-bot - L'analisi Conventional Commits calcola bump (major/minore/patch), crea un tag, genera changelog.
CD: deploy separati e release (phicheflagi/confighi attivano una nuova versione).
Controllo: non pubblichiamo «latest» su PRO prima di canary di successo e SLO concordati.

9) Semantica per configurazioni e regole

Anche i confighi (YAML/JSON) hanno una versione dello schema: 'schema _ variante: 3'.
MINOR - nuovi campi o regole facoltativi MAJOR - Cambia struttura/obbligatorietà.
Supporto v2/v3 nel valico; Un migratore di configurazioni con un rapporto di incompatibilità.

10) Test di compatibilità

Consumer-driven contract test (Pact) - Per ogni integrazione.
Schema-evolution test: prova dei vecchi payload su un nuovo schema e viceversa.
Replay: riproduce il traffico «v1» su «v2» nell'ombra.
Property-based - Resistenza a campi/enum sconosciuti.

11) Osservazione delle versioni

Etichetta metriche/logi: 'api _ version', 'schema _ version', 'event _ variante'.
Dashboard migrazione: quota di traffico su versioni, errore/latitanza su «v1/v2».
Alert: se «v1» non diminuisce come previsto; 4xx/5xx dopo il lancio dì v2 ".

12) Pattern migratori senza interruzioni

Expand → Migrate → Contract (БД).
Dual write + confronto di divergenze prima di passare alla lettura.
Shadow compare per classificare/regole.
Canary per tenanti/regioni; feature flags per i rimborsi rapidi.
Read-compat/Write-compat della finestra: la nuova versione legge i vecchi dati, ma scrive in un nuovo formato.

13) Anti-pattern

Versione in ogni campo invece di versionare la risorsa/evento.
Modifiche di breaking nascoste sotto MINOR (ad esempio, modifica dei default).
Rimuove i senza finestra e le metriche di consumo.
«Per sempre v1» non c'è nessun piano per rimuovere le vecchie versioni di tecnologia e vulnerabilità.
Combinazione tra la versione aziendale e quella dell'immagine contenitore.

14) Foglio di assegno del criterio di versioning

• Il formato di versione e le origini di verità sono stati registrati.
• L'elenco dei criteri di breaking per gli artefatti (REST/gRPC/GraphQL/events/DB) è stato approvato.
• Processo di depricaggio: tempi, comunicazioni, sunset/banner, dual-run.
• Checker di diagrammi differente automatico e Conventional Commits.
• Dashboard di consumo di versioni e alert.
• Playbook di migrazione (expand/migrate/contract, dual-write, shadow).
• Confighi e SDK hanno le proprie versioni e minuscole.
• Documentazione «come scegliere una versione» per i client e «come aumentare» per i comandi.

15) Esempi di versioning (valigette iGaming)

Evento «BetSettled v1» → «v2»: aggiungono «void _ reason» e «tax». amount` (optional) — MINOR. Riassegnato' payout'→'win_amount '- MAGGIORE, nuovo subject.
REST'/wallets/transfer ': hanno aggiunto il filtro'? tenant _ id = '- MINOR. Ho cambiato il codice di errore «409'→'422» - MAGGIORE.
GraphQL: contrassegnato «Player». age'comè @ deprecated ', a favore dì Player'. ageGroup - rilascio in MINOR, rimozione in MAJOR dopo il periodo X.
BD: aggiungono la colonna bonus _ wager _ left'nullable - MINORE. Hanno eliminato «bonus _ left» - MAJOR (tramite expand/contract).

Conclusione

La versione semantica non riguarda i numeri, ma la fiducia e la prevedibilità. Regole chiare, controlli automatici, depricaggi controllati e telemetria trasparente permettono di evolvere API, eventi e schemi senza dolore per le integrazioni e rilasciare cambiamenti frequenti, sicuri e sensibili.