Semantische Versionierung

Semantic Versioning (SemVer) ist ein Vertrag darüber, wie die Versionsnummer die Art der Änderungen widerspiegelt. Format: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - inkompatible Änderungen (Breaking).
• MINOR - Umkehrbare Funktionen/Erweiterungen.
• PATCH - Inverse Fehler-/Sicherheitskorrekturen.

Das Ziel: eine vorhersehbare Entwicklung von APIs, Ereignissen, Datenschemata, SDKs und Config ohne plötzliche Verbraucherpannen.

1) Zahlenkonvention

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

Pre-release ('-alpha', '-beta', '-rc') - instabile Baugruppen; Sie versprechen keine Kompatibilität.
Build metadata ('+ sha') - hat keinen Einfluss auf die Reihenfolge des Vergleichs, ist nützlich für die Verfolgung.
Bis zum 1. 0. 0 jede Änderung kann als Breaking betrachtet werden (aber es ist besser, die Regeln von Anfang an zu befolgen).

2) Was ist Breaking/Minor/Patch?

• Bugfixes und Sicherheit ohne Vertragswechsel.
• Dock-Upgrades, die den Vertrag nicht berühren.
• Optimierungen ohne Änderung der Antworten/Ereignisse/Schemata.

• Neue optionale Felder/Methoden/Endpunkte hinzufügen.
• enum mit Werten erweitern, wenn Verbraucher ungewohnte Werte tolerieren.
• Neue DB-Indizes, nullbare Spalten mit Ausfall, neue Ereignisse zusätzlich zu den alten.

• Löschen/Umbenennen von Feldern, Ändern von Typen, Obligationen.
• Änderung der Semantik/Status/Fehlercodes.
• Änderung des Serialisierungsformats, des Schlüsselschemas, des Transportprotokolls.
• Komprimieren/Verschmelzen von Topics, Übertragen der Bedeutung eines Ereignisses, Ändern des Partitionierungsschemas.
• OBD-Migrationen, die eine „zweiphasige“ Umschaltung ohne Abwärtskompatibilität erfordern.

3) Versionierung nach Artefakten

3. 1 REST

Optionen: 'URI/v1/...', Header ('Accept: application/vnd. acme. game+json; version = 1'), Parameter.
Empfehlung: Version in URI für öffentliche APIs; für intern - über die Überschrift c negotiation.
MINOR: optionale Felder, neue Filter/Ressourcen hinzufügen; Ändern Sie keine bestehenden Antworten.
PATCH: Fixes, Verfeinerung der Beschreibungen, stabile Sortierung.

3. 2 gRPC

Änderung der Signaturen/Typen → MAJOR (neues Paket/Service: 'acme. wallet. v2`).
Neue Felder - optional beschriftet; Der Server sollte Unbekannte ignorieren.
Wir löschen die Felder nicht: „depricate + reservate number“, löschen erst im nächsten MAJOR.

3. 3 GraphQL

MINOR: neue Felder/Typen/query; Löschen - über'@ deprecated'+ Migrationsfenster, vollständiges Löschen - MAJOR.
Änderung nullable→non -nullable - MAJOR.

3. 4 Events und Topics (Kafka/SQS)

Schemas in Schema Registry: evolution additive (fügen Sie Felder mit Standardwerten hinzu).
Eine neue inkompatible Version → ein neues subject/topic ('bet. settled. v2`).
Der Partitionierungsschlüssel ist innerhalb von MAJOR unverändert.

3. 5 OBD-Schaltungen

1. Spalte hinzufügen (nullable/c default) →

2. Füllen Sie das Backfill →

3. Lektüre übersetzen →

4. Alte entfernen (nur in MAJOR).

Typ/RK/Unikate ändern - MAJOR, unter Ficheflag und Doppeleintrag.

3. 6 SDK/CLI

Öffentliche Methoden/Signaturen sind die gleichen Regeln.
Für die Autogenerierung (OpenAPI/Proto) - Version des Batch-Namens und der Artefakte.

4) Entbehrungspolitik und Lebenszyklus

Jeder Breaking-Änderung geht eine Deprivation voraus (normalerweise 90-180 Tage für extern, 30-60 für intern).
Kommunikation: changelog, E-Mail/Webhooks an Partner, Banner im Entwicklerportal.
Dual-Run-Modus: Wir halten 'v1' und 'v2' parallel und überwachen den Anteil des Verkehrs' v1'.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

Der Kunde sendet die gewünschte Version + maximal unterstützte (z.B. 'Accept-Version: 1,2').
Der Server antwortet mit 'Content-Version: 2', wenn er erhöhen konnte.
In bidirektionalen Protokollen (WebSocket, gRPC) - Austausch von Hello-Frames mit 'supported _ versions'.

6) Integration mit Provider Adapters (ACL)

Ein externer Anbieter ändert das Schema - innerhalb des Adapters halten wir v1/v2-Mapper und geben MINOR für ein internes Ereignis frei, während wir unseren Domainvertrag behalten.
Wenn externe Änderungen ihren Weg nach innen finden, ist dies der MAJOR unseres Domain-Events und das neue Thema.

7) Changelog und Commit-Tags

• `feat:...` → MINOR
• „fix:“ .../„ chore “,„ docs “,„ perf “(ohne Vertrag) → PATCH
• 'feat!: '/' fix!: '/' refactor!:' oder 'BREAKING CHANGE:' im Körper → MAJOR

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

8) Automatisierung von Releases

CI: Scheme Validators (OpenAPI/Protobuf/Avro/JSON-Schema), Bruchdiffusionsdetail.
SemVer-Bot: Analyse von konventionellen Kommits → berechnet Bump (Major/Minor/Patch), kennzeichnet, generiert Changelog.
CD: separates Deploy und Release (Ficheflags/Configs aktivieren die neue Version).
Kontrolle: Wir veröffentlichen nicht 'neueste' auf PRO vor erfolgreichen kanarischen und vereinbarten SLOs.

9) Semantik für Konfigurationen und Richtlinien

Configs (YAML/JSON) haben auch eine Schemaversion: 'schema _ version: 3'.
MINOR - neue optionale Felder/Regeln; MAJOR - Veränderung der Struktur/Verbindlichkeit.
Unterstützung von v2/v3 im Validator; Config-Migrator mit Inkompatibilitätsbericht.

10) Kompatibilitätsprüfung

Verbrauchergetriebene Vertragstests (Pact): für jede Integration.
Schema-Evolution-Tests: Führen Sie alte Payloads in einem neuen Schema aus und umgekehrt.
Replay: Wiedergabe des Prod-Verkehrs' v1 'auf' v2 'im Schatten.
Property-based: Resistenz gegen ungewohnte Felder/enum.

11) Beobachtbarkeit nach Version

Taggen Sie die Metriken/Protokolle: 'api _ version', 'schema _ version', 'event _ version'.
Migrations-Dashboards: Traffic-Anteil nach Version, Fehler/Latenz nach 'v1/v2'.
Alerts: wenn 'v1' nicht planmäßig abnimmt; Wachstum von 4xx/5xx nach der Veröffentlichung von 'v2'.

12) Migrationsmuster ohne Ausfallzeiten

Expand → Migrate → Contract (БД).
Dual write + Vergleich der Divergenzen vor dem Lesewechsel.
Schattenvergleich für Ranking/Regeln.
Canary nach Tenanten/Regionen; feature flags für schnelle Pullbacks.
Read-compat/Write-compat des Fensters: Die neue Version liest alte Daten, schreibt aber im neuen Format.

13) Anti-Muster

„Version in jedem Feld“ statt Versionierung der Ressource/des Ereignisses.
Versteckte Breaking-Änderungen unter MINOR (z.B. Änderung von Standardwerten).
Entfernung von entricktem ohne Fenster und Verbrauchsmetriken.
„Forever v1“: Kein Plan zum Entfernen älterer Versionen → Techdolgs und Schwachstellen.
Mischen Sie die Business-Version und die Container-Image-Version.

14) Revisionspolitik Checkliste

• Das Versionsformat und die Quellen der Wahrheit (Registry/Portal) sind festgelegt.
• Liste der Breaking-Kriterien für Artefakte (REST/gRPC/GraphQL/events/DB) genehmigt.
• Entbehrungsprozess: Timing, Kommunikation, Sunset/Banner, Dual-Run.
• Automatischer Diff-Checker für Schemas und konventionelle Commits.
• Versionen Verbrauch Dashboards und Warnungen.
• Migration playbooks (expand/migrate/contract, dual-write, shadow).
• Configi und SDK haben ihre eigenen Versionen und Register.
• Dokumentation „Wie wähle ich eine Version aus“ für Kunden und „Wie erhöhe ich“ für Teams.

15) Beispiele für Versionierung (iGaming-Fälle)

Ereignis' BetSettled v1 '→' v2': hinzugefügt 'void _ reason' (optional) und 'tax. amount` (optional) — MINOR. Sie nannten es „payout'→'win_amount“ - MAJOR, ein neues Thema.
REST '/wallets/transfer': Filter'? tenant _ id ='- MINOR hinzugefügt. Fehlercode „409'→'422“ geändert - MAJOR.
GraphQL: markiert 'Player. age' als'@ deprecated 'zugunsten des' Players. ageGroup'- Freigabe in MINOR, Löschung in MAJOR nach Periode X.
DB: hinzugefügt die Spalte' bonus _ wager _ left 'nullable - MINOR. Sie haben non-null gemacht und 'bonus _ left' - MAJOR gelöscht (via expand/contract).

Schluss

Bei der semantischen Versionierung geht es nicht um Zahlen, sondern um Vertrauen und Berechenbarkeit. Klare Regeln, automatische Überprüfungen, kontrollierte Deprivationen und transparente Telemetrie ermöglichen es, APIs, Ereignisse und Schemata schmerzfrei für Integrationen zu entwickeln - und Änderungen häufig, sicher und sinnvoll freizugeben.