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

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

セマンティックバージョニング (SemVer) は、MAJOR.MINOR.PATCH の 3 桁でソフトウェアの互換性を表現するバージョニング規約である。Tom Preston-Werner (GitHub 共同創業者) が策定。

バージョン番号の意味

バージョン番号の意味を図で示す。

MAJOR.MINOR.PATCH
  2.    1.    3

MAJOR: 後方互換性のない変更 (破壊的変更)
MINOR: 後方互換性のある機能追加
PATCH: 後方互換性のあるバグ修正

具体例

具体例を以下に示す。

変更内容	バージョン変更
バグ修正	1.0.0 → 1.0.1
新機能追加 (既存 API は変更なし)	1.0.1 → 1.1.0
API の破壊的変更	1.1.0 → 2.0.0
セキュリティパッチ	2.0.0 → 2.0.1

npm でのバージョン指定

npm でのバージョン指定の例を示す。

{
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "~4.17.0",
    "typescript": "5.3.3"
  }
}

記法	意味	許容範囲
^4.18.0	MINOR, PATCH の更新を許可	4.18.0 〜 4.x.x
~4.17.0	PATCH の更新のみ許可	4.17.0 〜 4.17.x
5.3.3	完全固定	5.3.3 のみ

破壊的変更の例

破壊的変更の例を示す。

// v1: 文字列を返す
function getUser(id: string): string { ... }

// v2: オブジェクトを返す (破壊的変更 → MAJOR を上げる)
function getUser(id: string): User { ... }

プレリリースバージョン

プレリリースバージョンを図で示す。

1.0.0-alpha.1  → アルファ版
1.0.0-beta.1   → ベータ版
1.0.0-rc.1     → リリース候補
1.0.0          → 正式リリース

0.x.x の特別ルール

0.x.x の特別ルールを図で示す。

0.x.x: 初期開発段階
  → MINOR の変更でも破壊的変更が許容される
  → 1.0.0 で安定版を宣言

Conventional Commits との連携

Conventional Commits との 連携を図で示す。

feat: 新機能追加 → MINOR を上げる
fix: バグ修正 → PATCH を上げる
feat!: 破壊的変更 → MAJOR を上げる
BREAKING CHANGE: → MAJOR を上げる

自動的にバージョンを決定し、CHANGELOG を生成できる。

さらに掘り下げるなら関連書籍が参考になる。