セマンティックバージョニング

セマンティックバージョニング（SemVer）-バージョン番号が変更の性質をどのように反映するかに関する契約。フォーマット：MAJOR。マイナー。PATCH ［-PRERELEASE］［+BUILD］。

• MAJOR-互換性のない変更（破損）。
• MINOR-互換性のある機能/拡張。
• PATCH-後方互換性のあるバグ/セキュリティ修正。

目標：API、イベント、データスキーマ、SDK、およびコンフィギュレーションの予測可能な進化。突然の消費者の故障はありません。

1）コンベンション番号

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

プレリリース（'-alpha'、 '-beta'、 '-rc'）-不安定なアセンブリ；互換性を約束しないでください。
ビルドメタデータ（'+sha'）-比較順序には影響しません。トレースに便利です。
1まで。0.0任意の変更は破損と見なすことができます（しかし、最初からルールに従うことをお勧めします）。

2）破損/マイナー/パッチを考慮するもの

• 契約を変更せずにバグやセキュリティを修正しました。
• 契約に影響を与えないドッキングアップデート。
• 応答/イベント/スキームを変更せずに最適化。

• 新しいオプションのフィールド/メソッド/エンドポイントを追加します。
• 消費者が慣れない値を許容する場合の列挙値の拡張。
• 新しいデータベースインデックス、デフォルトのnullableカラム、古いイベントに加えて新しいイベント。

• フィールドの削除/名前変更、タイプの変更、必須。
• セマンティクス/ステータス/エラーコードを変更します。
• シリアライズフォーマット、キースキーム、トランスポートプロトコルの変更。
• トピックを圧縮/マージし、イベントの意味を転送し、パーティショニングスキームを変更します。
• 後方互換性なしで「二相」スイッチングを必要とするデータベース移行。

3）アーティファクトバージョニング

3.1 REST

バリアント：'URI/v1/……'、ヘッダ（'Accept： application/vnd。アクメだよ。ゲーム+json；version=1'）、パラメータ。
推奨事項：公開API用のURIのバージョン。内部-ヘッダcネゴシエーションを介して。
MINOR：オプションのフィールド、新しいフィルタ/リソースを追加します。既存の回答を変更しないでください。
PATCH：修正、定義の洗練、安定したソート。

3.2 gRPC

MAJOR→signatures/types （new package/service： 'acme。財布だよ。v2'）。
新しいフィールド-ラベル付きオプション；サーバーは未知を無視しなければなりません。
私たちはフィールドを削除しません：「depricket+reserve a number」、 delete-次のMAJORのみ。

3.3 GraphQL

MINOR：新しいフィールド/タイプ/クエリ；removal-'@deprecated'+マイグレーションウィンドウ、完全削除-MAJOR。
nullable→non -nullable-MAJORを変更します。

3.4イベントとトピックス（カフカ/SQS）

スキーマレジストリのスキーマ：additiveの進化（デフォルトでフィールドを追加）。
新しい互換性のないバージョン→新しい主題/トピック（'bet。 settled。v2'）。
パーティションキーはMAJOR内で不変です。

3.5つのDBダイアグラム

1.列を追加する（nullable/default）→

2.バックフィルを記入→

3.翻訳→読み取り

4.古い（MAJORのみ）を削除します。

type/PK/uniquenessを変更する-MAJOR、 phicheflagとダブルエントリの下。

3.6 SDK/CLI

パブリックメソッド/署名は同じルールです。
オートジェネレーション（OpenAPI/Proto）-バッチ名とアーティファクトのバージョン。

4）剥奪政策とライフサイクル

各破壊変化の前には、減価償却が行われます（通常、外部の場合は90-180日、内部の場合は30-60日）。
コミュニケーション：changelog、パートナーへの電子メール/webhook、開発者ポータルのバナー。
デュアルランモード：'v1'と'v2'を並列に保ち、トラフィック'v1'の共有を監視します。
サンセットヘッダー（REST）： 'Sunset： 2026-03-31'、 'Link： <url>；rel=「deprecation」'。

5）バージョン交渉

クライアントは、必要なバージョン+サポートされている最大バージョン（例：'Accept-Version： 1,2'）を送信します。
サーバーは'Content-Version： 2'で応答します。
双方向プロトコル（WebSocket、 gRPC）では、Helloフレームを'supported_version'で交換します。

6）プロバイダアダプター統合（ACL）

外部プロバイダはスキームを変更します-アダプタ内ではv1/v2マッパーを保持し、内部イベントのMINORをリリースし、ドメイン契約を維持します。
外部の変更が内部を変えた場合、これは私たちのドメインイベントのMAJORであり、新しい主題です。

7） changelogおよびコミットラベル

• 'feat：'……→MINOR
• 'fix：……'/'chore'、'docs'、 'perf'（契約なし）→PATCH
• 'feat！：'/'fix！：'/'refactor！：'または'BREAKING CHANGE：' in MAJOR→body

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

8）解放のオートメーション

CI： 回路バリデータ（OpenAPI/Protobuf/Avro/JSON-Schema）、 breaking-diffuse detect。より多くの

SemVer-bot：解析従来のコミット→bump（メジャー/マイナー/パッチ）を計算し、タグを付け、changelogを生成します。
CD：別々のデプロイとリリース（phicheflags/configsは新しいバージョンをアクティブにします）。
Control： canaryと合意されたSLOが成功するまで、PROで「最新」を公開しないでください。

9）構成とポリシーのセマンティクス

Configs （YAML/JSON）にはスキーマバージョン'schema_version： 3'もあります。
MINOR-新しいオプションフィールド/ルールMAJOR-構造/義務の変更。
バリデータでのv2/v3サポート。非互換性レポートを持つconfigマイグレータ。

10）両立性試験

消費者主導の契約テスト（協定）：統合あたり。
スキーマ進化テスト：新しいスキーマで古いペイロードを実行し、その逆も同様です。
「再生」（Replay）-本番トラフィック'v1'から'v2'までをシャドウで再生します。
プロパティベース：慣れないフィールド/列挙に対する抵抗。

11）バージョンごとの観測可能性

タグメトリック/ログ：'api_version'、 'schema_version'、 'event_version'。
移行ダッシュボード：バージョン別のトラフィック共有、'v1/v2'によるエラー/レイテンシ。
アラート：'v1'が計画通りにダウンしない場合；'v2'リリース後の4xx/5xxの増加。

12）ダウンタイムのない移行パターン

［展開］→［マイグレート］→［コントラクト］を選択します。
読み取りを切り替える前に、二重書き込み+差分を比較します。
ランク/ルールの影を比較します。
テナント/地域別カナリア；速いロールバックのための特徴の旗。
Read-compat/Write-compatウィンドウ：新しいバージョンは古いデータを読み込みますが、新しい形式で書き込みます。

13）アンチパターン

リソース/イベントをバージョニングする代わりに「各フィールドのバージョン」を指定します。
MINORでの非表示のブレイクチェンジ（デフォルトの変更など）。
窓および消費のメートル法なしでdepricatedの取り外し。
「Forever v1」：古いバージョンの→技術的債務と脆弱性を削除する計画はありません。
ビジネスバージョンとコンテナイメージのバージョンをミックスします。

14）バージョン管理ポリシーのチェックリスト

• バージョン形式と真実のソース（レジストリ/ポータル）を修正しました。
• アーティファクト（REST/gRPC/GraphQL/events/DB）による破損基準の承認リスト。
• 減価償却プロセス：タイミング、通信、日没/バナー、デュアルラン。
• 自動差分チェッカーと従来のコミット。
• バージョンとアラートの消費ダッシュボード。
• マイグレーションプレイブック（展開/マイグレート/コントラクト、デュアルライト、シャドウ）。
• ConfigsとSDKには独自のバージョンとケースがあります。
• クライアント向けのドキュメント「バージョンの選択方法」とチーム向けの「アップグレード方法」。

15）バージョン管理の例（iGamingケース）

'BetSreted v1' event→'v2'： 'void_reason'（オプション）と'tax。amount'（オプション）-MINOR。名前を変更した'payout'→'win_amount'-MAJOR、新しい件名。
REST '/wallets/transfer'：追加フィルタ'？tenant_id='-MINOR。エラーコード'409'→'422'-MAJORを変更しました。
GraphQL： 'Player。ageは'@deprecated'として'Player'を支持します。ageGroup'-MINORでのリリース、期間X後のMAJORでの削除。
DB：カラム'bonus_wager_left' nullable-MINORを追加しました。nullではなく"bonus_left'を削除しました-MAJOR （expand/contract経由）。

おわりに

セマンティックバージョニングは数字ではなく、信頼と予測可能性についてです。明確なルール、自動化されたチェック、制御されたデプロイメント、透過的なテレメトリーにより、API、イベント、痛みのないスキーマが統合のために進化し、変更を頻繁に、安全に、そして有意義にリリースできます。