🏷️
Semantic Versioning入門：patch / minor / major の違いと判断フロー
TL;DR
MAJOR.MINOR.PATCH の 3 ケタは “後方互換性” を軸に決める。
- 互換を壊す → major
- 互換を保った機能追加 → minor
- バグ修正やドキュメント更新 → patch
はじめに
最近はClaude Codeを活用したAI駆動開発を主に行っているのですが、Git worktreeを使ったパラレル開発を効率化（支援）するCLIツール開発したいなと思い、現在開発中なのですが、開発過程でソフトウェアのバージョン番号について学んだため、備忘録として記事にまとめます。
1. Semantic Versioning とは？
ソフトウェアのバージョン番号を X.Y.Z（メジャー・マイナー・パッチ）で管理し、
数値だけで互換性の有無を伝えるルールです。npm や Maven など主要エコシステムが採用しています。
| 桁 | 役割 | 互換性への影響 | 代表例 |
|---|---|---|---|
| MAJOR | 破壊的変更 | 後方互換性を壊す API 変更 | 1.x → 2.0.0 |
| MINOR | 機能追加 | 互換性 維持 した新機能 | 1.3.0 → 1.4.0 |
| PATCH | バグ修正 | 挙動を変えない修正・改善 | 1.4.2 → 1.4.3 |
0.x 系は「試験段階」とみなし、互換保証が緩いのが通例。
2. 判断フロー
例
| 変更 | 対応バージョン |
|---|---|
scj delete コマンドを削除 |
major (2.0.0) |
--json オプションを追加 |
minor (1.1.0) |
| CLI 出力の typo 修正 | patch (1.0.1) |
3. Changesets での指定方法
- コマンド実行
pnpm changeset # 対話式プロンプト
- 指定例
---
'shadow-clone-jutsu': minor
---
Add GitHub Projects integration
マージすると自動で scj@1.1.0 タグ & GitHub Release が生成されます。
4. よくある誤解
| 誤解 | 正 | 理由 |
|---|---|---|
| 「見た目が変わったら major」 | UI の非互換のみが対象 | 内部リファクタは影響なし |
| 「大きな実装量＝major」 | 量ではなく互換性 | 1 行の breaking change でも major |
| 「0.x は自由に壊して OK」 | ユーザーがいるなら慎重に | プロダクション利用例も多い |
5. まとめ
- 互換性の有無で patch / minor / major を決める
- 自動化ツール（Changesets / Release Please）を使うと運用が楽
- ドキュメント・CI もバージョンルールに合わせて更新しよう
バージョン番号は “契約” です。破壊的変更をしたら堂々と major を上げましょう！
Discussion