セマンティックバージョニングの正しい使い方

ライブラリを使っていて突然 1.0.0 → 2.0.0 のアップデートが来たとき、それがどのくらい影響するか事前にわかるだろうか。セマンティックバージョニング（SemVer）はこの疑問に答えるための規約だ。

MAJOR.MINOR.PATCH の意味

v1.4.2
  │ │ └── PATCH: バグ修正（後方互換あり）
  │ └──── MINOR: 新機能追加（後方互換あり）
  └────── MAJOR: 破壊的変更（後方互換なし）

バージョン更新	意味	例
`1.4.2 → 1.4.3`	バグ修正	セキュリティパッチ、バグFix
`1.4.2 → 1.5.0`	新機能（互換あり）	新しいAPIの追加
`1.4.2 → 2.0.0`	破壊的変更	API削除・引数変更・動作変更

ルール:

MAJOR を上げたら MINOR と PATCH は 0 にリセット
MINOR を上げたら PATCH は 0 にリセット

0.x.x と 1.0.0

0.x.x の期間は「初期開発段階」を意味し、何でも変わりうる。1.0.0 は「公開APIが安定した」宣言だ。

0.1.0 → 0.2.0: MINORでも破壊的変更を許容（開発中）
1.0.0 → 2.0.0: 破壊的変更は MAJOR にしか許されない

プレリリース識別子

1.0.0-alpha    # 内部テスト用（壊れていることがある）
1.0.0-beta.1   # 外部テスト用（機能は揃っている）
1.0.0-rc.1     # リリース候補（本番同等の品質）
1.0.0          # 正式リリース

依存関係での使い方

// package.json
{
  "dependencies": {
    "lodash": "^4.17.21",  // ^: MINOR・PATCHを自動更新 (4.x.x)
    "react": "~18.2.0",    // ~: PATCHのみ自動更新 (18.2.x)
    "exact-lib": "2.3.1"   // 固定バージョン
  }
}

# Cargo.toml (Rust)
[dependencies]
serde = "1.0"       # >=1.0.0, <2.0.0
tokio = "=1.28.0"   # 完全固定

CHANGELOG の書き方

CHANGELOGは「何が変わったか」をユーザー向けに記録するファイル。Keep a Changelog が標準的なフォーマット。

# Changelog

## [Unreleased]
### Added
- 新機能の説明

## [2.1.0] - 2026-06-01
### Added
- 日本語対応を追加 (#123)
- ダークモードをサポート

### Changed
- ログイン画面のデザインを刷新

### Fixed
- Safariでのレイアウト崩れを修正 (#145)

## [2.0.0] - 2026-04-15
### Breaking Changes
- `getUserById(id)` を `getUser({ id })` に変更
- Node.js 16 以下のサポートを終了

### Added
- GraphQL エンドポイントを追加

[Unreleased]: https://github.com/owner/repo/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/owner/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/owner/repo/compare/v1.9.0...v2.0.0

自動化ツール

conventional commits + semantic-release

コミットメッセージの規約からバージョンを自動決定できる。

# コミットメッセージの形式
feat: ログイン機能を追加            → MINOR アップ
fix: パスワードリセットのバグを修正  → PATCH アップ
feat!: APIを再設計                  → MAJOR アップ（!が破壊的変更を示す）

# .github/workflows/release.yml
- uses: semantic-release/semantic-release@v22
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

semantic-release はコミットログを解析してバージョン番号を決定し、タグ付け・CHANGELOG生成・パッケージ公開を自動化する。

よくある間違い

間違い	正しい対応
バグ修正なのに MINOR を上げる	PATCH を上げる
新機能追加で MAJOR を上げる（互換あり）	MINOR を上げる
非公開の内部APIを変えて MAJOR を上げる	公開APIのみが対象
`1.0.0` を無意味に遅らせる	安定したらさっさと `1.0.0` に

まとめ

MAJOR.MINOR.PATCH: 破壊的変更 / 新機能 / バグ修正
^ は MINOR・PATCHを自動更新、~ は PATCHのみ
0.x.x は開発中、1.0.0 が安定APIの宣言
CHANGELOGは Added / Changed / Deprecated / Removed / Fixed / Security のカテゴリで記録
conventional commits + semantic-release でリリースプロセスを完全自動化できる

#バージョニング #SemVer #パッケージ管理 #開発フロー #リリース

免責事項 — 掲載情報は執筆時点のものです。料金・機能は変更される場合があります。最新情報は各公式サイトをご確認ください。