Versioning semantic

Semantic Versioning (SemVer) - un contract cu privire la modul în care numărul versiunii reflectă natura modificărilor. Format: MAJOR. MINOR. PLASTURE [-PRERELEASE] [+ BUILD].

• MAJOR - Modificări incompatibile (rupere).
• MINOR - caracteristici/extensii reciproc compatibile.
• PATCH - Corecții de eroare/securitate compatibile înapoi.

Scop: evoluția previzibilă a API-urilor, evenimentelor, schemelor de date, SDK-urilor și configurațiilor fără defecțiuni bruște ale consumatorilor.

1) Numerele convenției

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

Pre-eliberare ("-alfa", "-beta", "-rc') - ansambluri instabile; nu promit compatibilitate.
Construiți metadate ('+ sha') - nu afectează ordinea de comparare, utilă pentru urmărire.
Până la 1. 0. 0 Orice schimbare poate fi considerată rupere (dar este mai bine să urmați regulile de la început).

2) Ce să ia în considerare de rupere/minor/plasture

• Remedieri pentru bug-uri și securitate fără a schimba contractul.
• Actualizări de andocare care nu afectează contractul.
• Optimizare fără modificarea răspunsurilor/evenimentelor/schemelor.

• Adăugați noi câmpuri opționale/metode/puncte finale.
• Extinderea valorilor enumului în cazul în care consumatorii tolerează valori necunoscute.
• Noi indici de baze de date, coloane nullable cu implicit, evenimente noi în plus față de cele vechi.

• Ștergerea/redenumirea câmpurilor, schimbarea tipurilor, obligatorie.
• Schimbați semantica/stările/codurile de eroare.
• Schimbarea formatului de serializare, schema cheie, protocolul de transport.
• Comprimați/îmbinați subiecte, transferați sensul evenimentului, schimbați schema de partiționare.
• Migrări de baze de date care necesită comutarea „în două faze” fără compatibilitate înapoi.

3) Versioning artefact

3. 1 REST

Variante: "URI/v1/...", antete ("Accept: application/vnd. acme. joc + json; versiunea = 1 '), parametru.
Recomandare: versiune in URI pentru API-uri publice; pentru intern - prin negocierea antetului c.
MINOR: adăugați câmpuri opționale, filtre/resurse noi; nu modificați răspunsurile existente.
PATCH: remedieri, rafinament definiție, sortare stabilă.

3. 2 gRPC

Schimbarea semnăturilor/tipurilor de → MAJORE (pachet nou/serviciu: 'acme. portofel. v2 ').
Câmpuri noi - etichetate opțional; serverul trebuie să ignore necunoscutul.
Nu ștergem câmpurile: „depricket + rezervă un număr”, ștergeți - numai în următorul MAJOR.

3. 3 GraphQL

MINOR: câmpuri/tipuri/interogări noi; eliminare - prin „@ depreciate” + fereastră de migrare, îndepărtarea completă - MAJOR.
Schimbarea nullable→non -nullable - MAJOR.

3. 4 Evenimente și subiecte (Kafka/SQS)

Scheme în Registrul Schema: evoluția aditivului (adăugați câmpuri cu valori implicite).
Noua versiune incompatibila → nou subiect/subiect ('bet. settled. v2 ').
Cheia de partiționare este imuabilă în cadrul MAJOR.

3. 5 diagrame DB

1. Adăugați o coloană (nullable/default) →

2. Completează rambleul →

3. Traduceţi → Citeşte

4. Scoateți vechi (numai MAJOR).

Schimbați tipul/PK/unicitate - MAJOR, sub phicheflag și intrare dublă.

3. 6 SDK/CLI

Metodele/semnăturile publice sunt aceleași reguli.
Pentru autogenerare (OpenAPI/Proto) - versiunea numelui lotului și a artefactelor.

4) Politica de privare și ciclul de viață

Fiecare schimbare de rupere este precedată de depricție (de obicei 90-180 de zile pentru extern, 30-60 pentru intern).
Comunicații: changelog, e-mail/webhooks către parteneri, bannere în portalul dezvoltatorului.
Modul dual-run: păstrați „v1” și „v2” în paralel, monitorizați cota de trafic „v1”.
Anteturi apus de soare (REST): 'Apus de soare: 2026-03-31', 'Legătură: <url>; rel = „depreciere” '.

5) Negocierea versiunii

Clientul trimite versiunea dorită + versiunea maximă acceptată (de exemplu, „Accept-Version: 1,2”).
Serverul răspunde cu 'Content-Version: 2' dacă poate promova.
În protocoalele bidirecționale (WebSocket, gRPC) - schimbul de cadre Hello cu 'supported _ versions'.

6) Integrarea adaptorului furnizorului (ACL)

Furnizorul extern modifică schema - în interiorul adaptorului păstrăm mapperii v1/v2 și eliberăm MINOR pentru evenimentul intern, păstrând contractul nostru de domeniu.
Dacă schimbările externe își fac loc în interior, acesta este PRINCIPALUL eveniment al domeniului nostru și un nou subiect.

7) Changelog și comite etichete

• „feat:”... → MINOR
• "fix:... „/” corvoadă „,” docs', „perf” (fără contract) → PATCH
• 'feat!: '/' fix!: '/' refactor!:' sau 'BREAKING CHANGE:' în corpul MAJOR →

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

8) Automatizarea lansării

CI: validatoare de circuit (OpenAPI/Protobuf/Avro/JSON-Schema), detectare difuză de rupere. mai mult

SemVer-bot: analiza convenționale Commits → calculează cucui (major/minor/patch), pune o etichetă, generează un changelog.
CD: implementare și lansare separată (phicheflags/configs activează noua versiune).
De control: nu publica „cele mai recente” pe PRO până la succes canar și SLO-uri convenite.

9) Semantică pentru configurații și politici

Configs (YAML/JSON) au, de asemenea, o versiune schemă: 'schema _ version: 3'.
MINOR - noi domenii opționale/reguli MAJORE - schimbarea structurii/obligației.
suport v2/v3 în validator; config migrator cu raport de incompatibilitate.

10) Testarea compatibilității

Testele contractuale conduse de consumatori (pact): per integrare.
Teste de schemă-evoluție: rulați sarcini utile vechi pe o schemă nouă și invers.
Replay - Redă traficul de producție „v1” la „v2” în umbră.
Bazat pe proprietate: rezistență la câmpuri necunoscute/enum.

11) Observabilitate după versiune

Tag metrics/logs: 'api _ version', 'schema _ version', 'event _ version'.
Tablouri de bord pentru migrare: partajarea traficului pe versiuni, eroare/latență pe 'v1/v2'.
Alerte: dacă „v1” nu scade conform planului; 4xx/5xx după eliberarea „v2”.

12) Modele de migrare fără downtime

Extindeți → migrați → contract (БД).
Scrieți dual + comparați divergențele înainte de a comuta citirea.
Shadow compara pentru clasament/reguli.
Canare după chiriaș/regiune; caracteristici steaguri pentru rollback-uri rapide.
Read-compat/Write-compat windows: noua versiune citește date vechi, dar scrie într-un format nou.

13) Anti-modele

„Versiune în fiecare domeniu” în loc de versionarea resursei/evenimentului.
Modificări de rupere ascunse sub MINOR (de exemplu, schimbarea defaults).
Îndepărtarea depricated fără ferestre și măsurători de consum.
„Forever v1”: nici un plan pentru a elimina versiunile vechi ale datoriilor tehnice → și vulnerabilități.
Se amestecă versiunea de afaceri și versiunea de imagine container.

14) Lista de verificare a politicii de versioning

• Format de versiune fixă și surse de adevăr (Registry/Portal).
• Lista aprobată a criteriilor de rupere după artefacte (REST/gRPC/GraphQL/events/DB).
• Procesul de deprications: calendarul, comunicații, apus de soare/bannere, dual-run.
• Verificator automat diff și Commits convenționale.
• Versiunea și tablourile de bord de consum de alertă.
• Playbook-uri de migrare (extinde/migra/contract, dual-write, shadow).
• Configs și SDKs au propriile versiuni și caz.
• Documentație „cum să alegeți o versiune” pentru clienți și „cum să faceți upgrade” pentru echipe.

15) Exemple de versioning (cazuri iGaming)

'BetSettled v1' event → 'v2': adăugat 'void _ reason' (opţional) şi 'tax. suma "(opţional) - MINOR. Redenumit „payout'→'win_amount” - MAJOR, un nou subiect.
RESTUL "/portofele/transfer ": filtru adăugat"? tenant _ id = '- MINOR. Modificat codul de eroare „409'→'422” - MAJOR.
GraphQL: marcat 'Player. vârstă „ca” @ depreciate „în favoarea” Jucător. AgeGroup '- eliberare în MINOR, ştergere în MAJOR după perioada X.
DB: coloana adăugată "bonus _ wager _ left' nullable - MINOR. Făcut non-nul și șters "bonus _ left' - MAJOR (prin extensie/contract).

Concluzie

Versionarea semantică nu se referă la cifre, ci la încredere și predictibilitate. Regulile clare, controalele automate, depricțiile controlate și telemetria transparentă permit API-urilor, evenimentelor și schemelor fără durere să evolueze pentru integrări - și să elibereze modificări frecvente, sigure și semnificative.