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

どのようなものか

セマンティックバージョニングは、通常SemVerと略され、リリースにどのよ
うな変更が含まれるかを番号自体で示すための規則です。Tom
Preston-Wernerが最初に書いたこの仕様は、現在バージョン2.0.0で、
MAJOR.MINOR.PATCHという形式の三つの数値を使います。公開APIの互換性を
壊すリリースではメジャー番号を上げ、後方互換性を保って機能を追加する
場合はマイナー番号を上げ、APIを変えずにバグだけを修正する場合はパッ
チ番号を上げます。ある番号を上げると、その右側の番号はゼロに戻しま
す。また、それぞれを文字列ではなく数値として比較するので、`1.10.0`は
`1.9.0`の後になります。

すべての前提になる要件は一つです。番号が表すのは公開APIの変更だけな
ので、プロジェクトはコードか文書で公開APIを宣言しなければなりませ
ん。一度リリースしたバージョンの内容は変更してはならず、修正するなら
新しいバージョンにします。メジャーバージョンがゼロの`0.y.z`は初期開
発用で、何もかもいつでも変わる可能性があり、APIを安定していると見な
すべきではありません。`1.0.0`は公開APIが定義される時点であり、それ以
降の番号はAPIの変化に従います。

形式には、必要に応じて二種類のラベルを追加できます。プレリリースはハ
イフンの後に付け、対応する正式リリースより前に並びます。したがって、
`1.0.0-alpha`、`1.0.0-alpha.1`、`1.0.0-beta`、`1.0.0-rc.1`、最後に
`1.0.0`という順序になります。ビルドメタデータは、
`1.0.0+20130313144700`のようにプラス記号の後に付けますが、バージョン
の順序を決めるときには無視するため、その部分だけが違う二つのバージョ
ンの順位は同じです。Gitのタグ`v1.2.3`のように先頭に付くvは、セマン
ティックバージョンの一部ではありません。仕様では、バージョン番号を示
す一般的な方法と説明しています。Goではこれが必須で、正規のGoモジュー
ルバージョンは、文字vにセマンティックバージョンを続けたものです。

なぜ重要なのか

仕様は、依存関係地獄と呼ぶ問題から説明を始めます。依存関係の指定を厳
しくしすぎると、あるパッケージを更新するには、それに依存するすべての
パッケージも新しいバージョンをリリースしなければならない、バージョン
ロックに陥ります。緩くしすぎると、互換性を期待できる確かな根拠もなく
将来のリリースを受け入れる、仕様のいう「バージョンの無節操」が起きま
す。番号の意味に合意があれば、プロジェクトは受け入れる範囲を指定でき
ます。3.1.0で初めて追加された関数を必要とするライブラリは、3.1.0以上
4.0.0未満を受け入れ、要件を誰も編集することなく、その後の修正や機能
追加を取り込めます。

パッケージマネージャーは、その約束に基づいて確認なしに動作します。
RustのパッケージマネージャーCargoでは、`"1.2.3"`のような単純な指定は
キャレット要件であり、1.2.3以上2.0.0未満を意味します。Cargoは
`Cargo.lock`を書くとき、その範囲内の最大のバージョンを選びます。
2.0.0を非互換と扱うため、2.0.0の公開後も1.x系にとどまります。npm向け
のセマンティックバージョン処理ツールと名乗るnode-semverでは、
`^1.2.3`は`>=1.2.3
<2.0.0-0`を意味し、`~1.2.3`はパッチ単位の変更だけ、つまり`>=1.2.3
<1.3.0-0`を許可します。Goは、この規則をインポートパスに組み込んでい
ます。メジャーバージョン2以降は、モジュールのパスの末尾に`/v2`などの
接尾辞が必要なので、互換性のない二つのメジャーバージョンは、異なるイ
ンポートパスになります。そのうえでGoの最小バージョン選択は、各モ
ジュールについて、いずれかの要件が求めるバージョンのうち最も高いもの
を選びます。それが、すべての要件を満たす最小のバージョンです。結果は
ロックファイルに保存されず、モジュール対応の各コマンドが毎回計算し直
します。

こうした仕組みがあっても、番号が保証になるわけではありません。これは
パッケージの公開者がする約束であり、何を互換性を壊す変更と見なすかと
いう、その人たちの判断次第です。そのため、Cargoは変更をメジャー、マ
イナー、互換性を壊す可能性があるものに分類した、詳細な互換性ガイドを
公開しています。その大半は、昨日までコンパイルできたコードが、今日コ
ンパイルできなくなる変更を扱っています。ガイド自体も、ほぼどの変更に
も実行時の挙動へ影響するリスクがあり、その変更を非互換と見なすかは、
通常、保守担当者の判断になると述べています。

実際の活用例

架空のRustライブラリtallyのリリースを追ってみます。0.4.2は、まだ初期
開発の段階です。1.0.0で、公開APIが安定したと宣言します。1.0.1では丸
め処理のバグを修正し、パッチリリースになります。1.1.0では
`parse_strict`関数を追加し、従来の`parse`を非推奨にします。仕様は、
非推奨化にはマイナーリリースを要求し、関数を削除する前に少なくとも一
度、そのようなリリースを出すよう求めています。2.0.0では`parse`を削除
するため、メジャーリリースになります。2.1.0-rc.1は、次のマイナーバー
ジョンのプレリリースです。

tallyと、他の三つの架空のクレートに依存するアプリケーションは、
`Cargo.toml`に要件を書きます。コメントは、Cargoが各行から読み取る範
囲を示しています。

```toml
[dependencies]
tally = "1.0.1"         # >=1.0.1, <2.0.0: takes 1.1.0, never 2.0.0
ledger = "0.4.2"        # >=0.4.2, <0.5.0: 0.5.0 counts as breaking
stamp = "~1.2.3"        # >=1.2.3, <1.3.0: patch releases only
quill = "=2.1.0-rc.1"   # exactly this pre-release
```

`ledger`の行は、仕様ではなくツールの慣習を示しています。仕様では
1.0.0未満はいつでも変わり得るとする一方、Cargoは、左から最初のゼロで
ない番号を、互換性を壊す変更を表すものとして扱います。Cargoは、要件
にプレリリースが明記されていない限り、それを候補から除外するため、
`"2.0"`という要件ではtallyのリリース候補は選ばれません。最終行の厳密
な`=`形式は、プレリリースに依存しながら、プレリリース間の非互換変更
を避けるための指定です。Cargoの文書も、こうした場合には、バージョン
を完全に指定する要件が妥当になり得るとしています。依存関係の解決で確
定したバージョンは`Cargo.lock`に記録され、`cargo
update`で、これらの範囲内のバージョンへ更新できます。`--locked`を指
定すると、ロックファイルの変更が必要なビルドは、代わりにエラーを返し
ます。

番号が扱わないのは、APIの外側にある事柄すべてです。2026年9月に実施し
た644個のRustクレートのライセンス監査では、ビルドのたびに、各クレー
トのライセンスを許可リストに照らして検査します。依存関係グラフの奥で
日常的なバージョン更新が起きるだけでも、アプリケーションをどの条件で
配布できるかが、誰も全文を読まないロックファイルの中で、気付かれずに
変わり得るためです。検査が機能することを確かめるため、意図的に二度失
敗させました。一つはクレートのライセンス式を書き換えるテストです。こ
れは、バージョン間で依存先の利用条件が変わる場合に相当し、クレート自
体は新しくないため、人のレビューでは見落とされます。もう一つは、監査
を再生成せずに、固定したコアのリビジョンを変更するテストです。セマン
ティックバージョンは、1.4.0が1.0.0を対象に書かれたコードで動くことを
意図しているとは示せます。しかし、引き続き配布してよいかどうかは示せ
ません。

問題が起きるところ

マイナーリリースで互換性を壊します。
うっかり起きることも、何を非互換と見なすかの考え方が違って起きること
もあります。Cargoのガイドには、無害に見えてそうではない変更が挙げら
れています。公開enumにバリアントを追加すると、最初から
`#[non_exhaustive]`が付いていない限り、すべてのバリアントを網羅する
マッチを行うコードが壊れます。また、globインポートが関わるまれな状況
では、新しい公開項目を追加するだけでもコンパイルエラーが起きます。誤
りに気付いた場合に仕様が示す対処は、互換性を回復する新しいマイナー
バージョンをリリースし、公開済みのリリースを変更することは決してせ
ず、どのバージョンに問題があったか利用者に伝えることです。利用する側
では、コミットされたロックファイルと、更新のたびに実行するテストに
よって、本番で発覚する前に検出します。

何年も0.xのままです。
仕様上、メジャーバージョンがゼロの間は、安定したAPIという約束はあり
ません。FAQは率直に、「本番環境で使われているソフトウェアなら、おそ
らくすでに1.0.0にしておくべきでしょう」と述べています。ツールは、独
自の慣習でこの隙間を埋めています。Cargoとnode-semverは、左から最初の
ゼロでない番号を非互換変更の番号とするため、`^0.2.3`が受け入れるの
は、その後の0.2.xリリースだけであり、`^0.0.3`は一切の更新を受け入れ
ません。何年も0.xのままのライブラリには、それに依存する利用者がいる
のに、明確な約束がありません。APIが頼りにされるようになったら、1.0.0
をリリースします。変えるのは番号であって、コードではありません。

番号から読み取れる以上のことを読み込みます。
仕様がいう互換性は、公開APIについてのものです。Cargoのガイドは、ク
レートが必要とするRustの最低バージョンを上げる変更を、互換性を壊す可
能性があるものに分類し、一般にはマイナー変更として扱うよう勧めていま
す。そのため、マイナー更新でも、古いツールチェーンではビルドできなく
なることがあります。`package.rust-version`を設定すれば、必要に応じて
Cargoのリゾルバーが、そのクレートの古いバージョンを試せるようになり
ます。ライセンス条件、性能、APIが文書化していない挙動は、そもそも番
号の対象外です。マイナーリリースだからと推測せず、ライセンス監査とテ
ストで別々に確認します。

一つのビルドに二つのメジャーバージョンが入ります。
二つの依存先が、同じクレートの非互換なバージョン、例えば0.6と0.7を必
要とすると、Cargoは両方をビルドします。名前が一致していても、コンパ
イラーはそれらの型を別物として扱います。通常はコンパイルエラーになり
ますが、実行時にしか分からないこともあります。Cargoの文書には、オブ
ジェクトを生成したライブラリは1.0.0を使っているのに、呼び出し側は
2.0.0の型へダウンキャストするため、失敗する例があります。`cargo
tree -d`は、重複するバージョンと、それぞれがどこから来るかを一覧にし
ます。ライブラリの作者は、Cargoの文書がsemver
trickと呼ぶ方法で、メジャーリリースの影響を和らげられます。新しいメ
ジャーバージョンを公開した後、古いメジャーバージョンのポイントリリー
スを出し、新しい方の型を再エクスポートします。

参考資料

  * Semantic Versioning 2.0.0 —
仕様とFAQです。誤って互換性を壊す変更をリリースした場合の対処も含み
ます。

  * SemVerの互換性 —
Rustライブラリのどの変更がメジャー、マイナー、互換性を壊す可能性のあ
るものに当たるかを、例付きで説明するCargo
Bookのガイドです。

  * 依存関係の指定 — デフォルト、キャレット、チルダ、比較によるCargo
の要件構文と、プレリリースの照合方法を説明しています。

  * 依存関係の解決 —
Cargoによるバージョンの選択、ロックファイルに保存される内容、一つの
グラフに非互換な二つのバージョンが入る危険を説明しています。

  * node-semver —
npm向けのセマンティックバージョン処理ツールです。キャレット、チル
ダ、プレリリース範囲の規則を説明しています。

  * Goモジュールリファレンス — メジャーバージョンの接尾辞、インポー
ト互換性の規則、最小バージョン選択を説明しています。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/semantic-versioning/	engineer.company	70
