Versioning sémantique

Semantic Versioning est un contrat sur la façon dont le numéro de version reflète la nature des changements. Format : MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - Modifications incompatibles (breaking).
• MINOR - fiches/extensions rétrocompatibles.
• PATCH - corrections de bogues/de sécurité rétrospectives.

Objectif : évolution prévisible de l'API, des événements, des schémas de données, des SDK et des configues sans brusques pannes des consommateurs.

1) Convention des numéros

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

Pre-release ('-alpha', '-beta', '-rc') sont des assemblages instables ; ne promettent pas la compatibilité.
Build metadata ('+ sha') - n'affecte pas l'ordre de comparaison, utile pour le traçage.
Jusqu'à 1. 0. 0 tout changement peut être considéré comme un breaking (mais il vaut mieux respecter les règles dès le début).

2) Quoi compter breaking/mineur/patch

• Fixations de bogues et de sécurité sans changement de contrat.
• Les doc-updates qui n'affectent pas le contrat.
• Optimisations sans modification des réponses/événements/schémas.

• Ajout de nouveaux champs/méthodes/endpoints facultatifs.
• Étendez enum avec des valeurs si les consommateurs tolèrent des valeurs inconnues.
• De nouveaux indices OBD, des colonnes nulles avec défaut, de nouveaux événements en plus des anciens.

• Supprimer/renommer les champs, modifier les types, être obligatoire.
• Modifier la sémantique/les statuts/les codes d'erreur.
• Changement de format de sérialisation, schéma de clé, protocole de transport.
• Compression/fusion des tops, transfert du sens de l'événement, modification du schéma de lot.
• Migration OBD nécessitant une commutation « biphasée » sans compatibilité inverse.

3) Versioning par artefacts

3. 1 REST

Variantes : 'URI/v1/...', titres ('Accept : application/vnd. acme. game+json; version = 1 '), paramètre.
Recommandation : version en URI pour les API publiques ; pour l'intérieur - via le titre c negotiation.
MINEUR : ajout de champs facultatifs, de nouveaux filtres/ressources ; ne modifiez pas les réponses existantes.
PATCH : fiches, clarification des descriptions, tri stable.

3. 2 gRPC

Changer les signatures/types de → MAJOR (nouveau paquet/service : 'acme. wallet. v2`).
Nouveaux champs - avec l'étiquette optional ; le serveur doit ignorer les inconnus.
Les champs ne sont pas supprimés : « dépricate + réserver le numéro », supprimer - seulement dans le MAJOR suivant.

3. 3 GraphQL

MINEUR : nouveaux champs/types/query ; suppression - via '@ deprecatated' + la fenêtre de migration, suppression complète - MAJOR.
Modifier nullable→non -nullable - MAJOR.

3. 4 Événements et topics (Kafka/SQS)

Schémas dans Schema Registry : évolution additive (ajouter des champs en défaut).
Une nouvelle version incompatible → un nouveau sujet/topic ('bet. settled. v2`).
La clé de lot est inchangée dans MAJOR.

3. 5 Schémas OBD

1. Ajouter une colonne (nullable/avec défaut) →

2. Remplir le backfill →

3. Traduire les lectures →

4. Supprimer l'ancien (en MAJOR seulement).

Changement de type/RC/Unicités - MAJOR, sous ficheflag et double entrée.

3. 6 SDK/CLI

Les méthodes/signatures publiques sont les mêmes règles.
Pour la génération automatique (OpenAPI/Proto) - version du nom de lot et des artefacts.

4) Politique de privation et cycle de vie

Chaque changement est précédé d'une privation (généralement 90-180 jours pour l'extérieur, 30-60 pour l'intérieur).
Communications : changelog, e-mail/webhooks aux partenaires, bannières dans le portail du développeur.
Mode dual-run : en parallèle, nous tenons 'v1' et 'v2', nous surveillons la part du trafic 'v1'.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

Le client envoie la version souhaitée + prise en charge maximale (par exemple, 'Accept-Version : 1,2').
Le serveur répond 'Content-Version : 2' s'il a pu l'augmenter.
Dans les protocoles bidirectionnels (WebSocket, gRPC), échange des cadres Hello avec 'supported _ versions'.

6) Intégration avec les adaptateurs de fournisseurs (ACL)

Le fournisseur externe change de schéma - à l'intérieur de l'adaptateur, nous gardons les mappers v1/v2 et libèrent MINOR pour un événement interne, tout en conservant notre contrat de domaine.
Si des changements externes se produisent à l'intérieur, c'est le MAJOR de notre événement de domaine et le nouveau sujet.

7) Changelog et les étiquettes de commit

• `feat:...` → MINOR
• 'fix : '/' chore', 'docs', 'perf' (sans contrat) → PATCH
• 'feat !: '/' fix !: '/' refactor !:' ou 'BREAKING CHANGE :' dans le corps de la → MAJOR

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

8) Automatisation des sorties

CI : Validateurs de schémas (OpenAPI/Protobuf/Avro/JSON-Schema), détail breaking-diffs.
BouVer-bot : l'analyse des Commits conventionnels calcule → le bump (major/mineur/patch), met une balise, génère un changelog.
CD : deploy et release séparés (ficheflagi/configi activent la nouvelle version).
Contrôle : nous ne publions pas 'latest' sur le PRO avant le succès du canary et le SLO convenu.

9) Sémantique pour les configurations et les politiques

Configi (YAML/JSON) a également une version du schéma : 'schema _ version : 3'.
MINOR - nouveaux champs/règles non obligatoires ; MAJOR - changement de structure/obligation.
Support v2/v3 dans le validateur ; migrateur de configus avec rapport d'incompatibilité.

10) Test de compatibilité

Tests de contrat de consommation (Pact) : pour chaque intégration.
Tests de schema-evolution : lancer les anciens payload's sur le nouveau schéma et vice versa.
Replay : lecture du trafic prod 'v1' sur 'v2' à l'ombre.
Property-based : résistance aux champs inconnus/enum.

11) Observabilité selon les versions

Étiquetez les métriques/logs : 'api _ version', 'schema _ version', 'event _ version'.
Dashboards de migration : part du trafic par version, erreur/latence par 'v1/v2'.
Alert : si 'v1' ne descend pas comme prévu ; croissance 4xx/5xx après la sortie de 'v2'.

12) Modèles de migration sans temps d'arrêt

Expand → Migrate → Contract (БД).
Double écriture + comparaison de divergences avant de changer de lecture.
Shadow compare pour le classement/règles.
Canary par tenants/régions ; feature flags pour les retours rapides.
Fenêtre Read-compat/Write-compat : la nouvelle version lit les anciennes données, mais écrit dans un nouveau format.

13) Anti-modèles

« Version dans chaque champ » au lieu de convertir la ressource/événement.
Modifications de rupture cachées sous MINOR (par exemple, modification des défauts).
Supprime le déchiffré sans fenêtre et les métriques de consommation.
« Pour toujours v1 » : pas de plan pour supprimer les anciennes versions de la → technique et la vulnérabilité.
Mélange de la version professionnelle et de la version conteneurisée.

14) Chèque de politique de versioning

• Le format des versions et les sources de vérité (Registry/Portal) ont été enregistrés.
• La liste des critères de rupture des artefacts (REST/gRPC/GraphQL/events/DB) a été approuvée.
• Processus de privation : délais, communications, sunset/bannières, dual-run.
• Checker diff automatique des schémas et des comités conventionnels.
• Dashboards de la consommation des versions et alerte.
• Pleybooks de migration (expand/migrate/contract, dual-write, shadow).
• Configi et SDK ont leurs propres versions et registre.
• Documentation « comment choisir la version » pour les clients et « comment augmenter » pour les équipes.

15) Exemples de versioning (cas iGaming)

Événement 'BetSettled v1' → 'v2' : ajout de 'void _ reason' (optional) et 'tax. amount` (optional) — MINOR. « payout'→'win_amount » - MAJOR, le nouveau sujet.
REST'/wallets/transfer ': vous avez ajouté le filtre' ? tenant _ id = '- MINEUR. Le code d'erreur '409'→'422' - MAJOR a été modifié.
GraphQL : marqué 'Player. age 'comme' @ deprecated 'en faveur de' Player. ageGroup '- sortie en MINOR, sortie en MAJOR après la période X.
OBD : ajout de la colonne 'bonus _ wager _ left' nullable - MINOR. Fait non-null et supprimé 'bonus _ left' - MAJOR (via expand/contract).

Conclusion

Le versioning sémantique ne concerne pas les chiffres, mais la confiance et la prévisibilité. Des règles claires, des contrôles automatiques, des privations contrôlées et une télémétrie transparente permettent aux API, aux événements et aux schémas d'évoluer sans douleur pour les intégrations - et de produire des modifications fréquentes, sûres et significatives.