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

1） SemVerとは何か、なぜ必要なのか

SemVerは、バージョンをアーティファクト（ライブラリ、API、サービス、スキーマ）に割り当てるための予測可能なルールを設定し、消費者がアップデートから何を期待するかを理解できるようにします：

MAJOR-変更を破る。
MINORは新しいAPI互換機能です。
パッチ-リバーシブル欠陥の修正。

目標：契約の安定性に同意し、アップグレードのコストを削減する。

2）バージョン形式

基本フォーマット：

'MAJOR。マイナー。PATCH ［-PRERELEASE］［+BUILD］'

`1.4.7'は安定したリリースです。
`1.5.0-rc。2'-プレリリース（リリース候補第2号）。
`2.0.0+Linux。arm64'-ビルドメタデータ（バージョン比較には影響しません）。

比較ルール：

1.まず、'MAJOR'と比較し、'MINOR'と'PATCH'を比較します。

2.プレリリースは対応する安定版'1より小さい。2.0-rc。1 < 1.2.0`.

3.ビルドメタデータ（'+……'）は順序に影響しません：'1。2.0+001 == 1.2.0`.

3）壊れ目の変化としてカウントするもの

変革-消費者の行動を必要とする変更：

パブリックメソッド/エンドポイントの署名を削除/名前変更/変更します。
入出力フォーマット（JSONスキーム、タイプ）を変更します。
エラーコントラクト（コード/構造）を変更します。
副作用/SLA（厳格な制限や新しい必須フィールドなど）を変更します。

壊れない（正しく実装されている場合）：オプションフィールドの追加、新しい値でenumを展開する（クライアントが無視した場合）、新しいエンドポイント、現在の呼び出しに影響を与えないデフォルトの新しいフラグ。

4）プレリリースとチャネル戦略

プレリリースでは、SemVerの約束を破ることなくテストすることができます：

タグ：'alpha'、 'beta'、 'rc'。例：'2。3.0-beta。3`.
チャンネル：夜間→アルファ→ベータ→rc→安定。
ポリシー：プリリリースは、デフォルトの本番アセンブリのトランジティブな依存関係としては該当しません。

5）バージョン範囲と制約精度

実際の生態系は範囲表現を使用します：

5.1 ノード/npm（デフォルトのSemVer）

`^1.4.2` ≈ `>=1.4.2 <2.0.0 '（MINOR/PATCHを許可し、MAJORを修正）。
`~1.4.2` ≈ `>=1.4.2 <1.5.0 '（MINOR内のPATCHを許可）。

`1.4.x'は1の任意のパッチです。4.

正確なピン： '1。4.2`.

5.2 Python （PEP 440、 pip）

`~=1.4.2` ≈ `>=1.4.2,==1.4.`.

`>=1.4,<2.0'-明示的な境界。

5.3 Maven/Gradle （Java）

`[1.4,2.0）'-包括的/排他的。
厳密な蹴ることは食糧重大なアーティファクトのために推薦されます。

5.4 Goモジュール

常に'vMAJOR'タグを完了します。マイナー。PATCH'；'v2+'はモジュール接尾辞'/v2'を必要とする。

推奨事項：アプリケーション-正確なピン（再現可能なビルド）。ライブラリの場合-キャレット範囲（破損のない更新を容易にします）。

6） CHANGELOG○Conventionalコミット

構造化された変更ログは透明性を向上させます。

従来のコミット：


feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

'feat'、 'fix'、 'perf'、 'docs'、 'refactor'、 'chore'。д.

感嘆ポイントまたは'BREAKING CHANGE' blockはMAJORを宣言します。
CHANGELOGはコミット履歴（ボットによるリリースノート）から生成されます。

7） APIのバージョン管理ポリシー

パブリックAPI：厳格なSemVer；breaking→MAJOR。
HTTP/REST： URL/headerによるバージョン管理：'/v1/……'、'/v2/……'または'Accept： application/vnd。ORG。サービス。v2+json'。
JSONスキーマ：マイナーエクステンション-新しいオプションフィールド；major-削除/変更が必須です。
gRPC/Protobuf：新しい数字で新しいフィールドを追加します。deprecate→を削除するフィールド番号を再利用しないでください。既存のフィールドを壊すことはありません。

8）データと移行スキーム

データベース移行はapp@1バージョンと同期されます。8.0'は'schema@1'を要求します。8.X'。
スキーマの変更を破る-フェーズ：展開（追加）、マイグレート、コントラクト（削除）。古い契約を削除した場合にのみMAJORにアップグレードします。
移行期間中の二重書き込み/読み取りをサポートします。

9）モノレポとマイクロサービス

マルチパッケージ：各パッケージには独自の'MAJORがあります。マイナー。PATCH'；メタアーティファクトの一般的なルートリリースサイクルのみ。

さまざまな戦略：

独立したバージョン（Lerna/Changesets）-分離が増加します。
ロックステップ-簡単なコミュニケーションが、より多くの偽のメジャー。
マイクロサービスの場合、contracts （OpenAPI/Protobuf）を別のバージョンで修正します：'contract@2。1.0'、サービスはそれに従います。

10） CI/CDのリリースの自動化

従来のコミットに基づくバージョンの自動計算：

'fix'→'PATCH'、 'feat'→'MINOR'、'！'/'BREAKING'→'MAJOR'。

Autotegsとアーティファクト署名：

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

CHANGELOGの生成、リリースノートの公開、GitOpsレポの依存関係の更新、'main'が常に最後の安定したタグを指すことを確認します。

11）剥奪の方針

お知らせ：MINORリリースで非推奨として機能をマークし、EOL用語を付与します（例：90日）。
Observability：ユーザー/テナントのコンテキストでレガシーエンドポイントの使用を記録します。
削除：次のMAJORで。移行パスを文書化します。

12）例とテンプレート

12.1通常のSemVer検証式

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12.2比較の例

`1.2.3` < `1.10.0 '（MINOR比較）。

`2.0.0-rc。1` < `2.0.0`.

`1.2.3+ビルド。5` == `1.2.3`.

12.3依存関係ポリシー（YAML例）

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13）アンチパターン

prodで'latest '/floatingタグを使用します。
MAJORの強化（「マーケティングバージョン」）。
「PATCH」を装った隠れたブレイクチェンジ。
本番アプリケーションのトランジティブな依存関係におけるプレリリース。
新しいタグ（変更可能なバージョン）なしでアーティファクトを変更します。
一貫性のないコードバージョンとデータベーススキーマ。

14）実装チェックリスト（0-45日）

0-10日

SemVerを必須の基準として受け入れ、破損基準を承認します。
従来のコミットと「BREAKING CHANGE」フィールドを持つPRテンプレートを含める。

11-25日

セマンティックリリース/チェンジセット、CHANGELOG自動生成を接続します。
vXタグに対するアーティファクトの署名と公開を構成します。Y。Z。

26-45日

レガシーAPIの使用に関する非推奨ポリシーとテレメトリーを入力します。
契約バージョン（OpenAPI/Proto）とサービスを同期します。
ポリシーレベル（OPA/CI規制）で「最新の」タグと変更可能なタグを禁止します。

15）成熟度の指標

SemVerタグでのみ公開されたアーティファクトの％。
マイナーバージョン間の平均移行時間。
隠れた破損の変化によるインシデントの数。
リポジトリにおける従来のコミットのカバレッジ（>95％）。
製品に浮動範囲を持たない依存関係の割合（>90％）。

16） SemVerが不要な場合

外部消費者のいない内部高速プロトタイプ（日付のバージョン管理に適しています）。
実験的な機能を備えたデータ/モデル（コンバータレベルでの互換性を備えたより良いモデル/スキーマバージョン）。
安定した公開APIを持たないコンテンツパッケージ。

17）結論

SemVerはメーカーと消費者の間の信頼契約です。互換性を破るものを明確に定義し、リリースタイプの認識とアーティファクトのパブリッシングを自動化し、透明なCHANGELOGを維持し、剥奪ポリシーを遵守します。その後、更新は定期的で予測可能で安全になり、インフラストラクチャとAPIはビジネスに衝撃を与えることなく発展します。

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