開発中のプログラムのバージョン番号付けで迷うことがあったので、セマンティックバージョニングのリファレンスのを読んでみました。
その時に覚えておきたいと思った内容をノート代わりに記録しておきます。
概要
- 基本的には3つの数の組み合わせでバージョンを管理する
- バージョンナンバーは、左から
メジャー.マイナー.パッチと呼ぶ。 - バージョンを上げる際の決まり
導入
パブリックなAPIを宣言したら、それを変更する際にはルールに従ってバージョン番号を上げなければなりません。つまり、X.Y.Z（メジャー.マイナー.パッチ）のバージョン形式を遵守しなければなりません。
『セマンティック バージョニング仕様書 (SemVer)』より
前提
この文書における各キーワード
「しなければならない（MUST）」、
「してはならない（MUST NOT）」、
「要求されている（REQUIRED）」、
「することになる（SHALL）」、
「することはない（SHALL NOT）」、
「する必要がある（SHOULD）」、
「しないほうがよい（SHOULD NOT）」、
「推奨される（RECOMMENDED）」、
「してもよい（MAY）」、
「選択できる（OPTIONAL）」は、
RFC 2119に記載されている内容に従い解釈してください。
１.
セマンティック バージョニングを適用するソフトウェアはパブリックAPIを宣言しなければなりません（MUST）。このAPIはコード自体で表現されているかもしれませんし、明確に文書として存在してるかもしれません。どちらにせよ、正確かつ漏れがないようにするべきです（SHOULD）。
２.
通常のバージョンナンバーは、X.Y.Zの形式にしなければなりません（MUST）。このときX、Y、Zは非負の整数であり（MUST）、各数値の先頭にゼロを配置してはなりません（MUST NOT）。Xはメジャーバージョン、Yはマイナーバージョン、Zはパッチバージョンを表します。各バージョンは数値的にバージョンアップしなければなりません（MUST）。例：1.9.0 -> 1.10.0 -> 1.11.0。
３.
一度パッケージをリリースしたのなら、そのバージョンのパッケージのコンテンツは修正してはなりません（MUST NOT）。いかなる修正も新しいバージョンとしてリリースしなければなりません（MUST）。
- 厳密にセマンティックバージョニングを運用するなら『タグのつけなおし』、は実施してはいけないということ。
４.
メジャーバージョンのゼロ（0.y.z）は初期段階の開発用です。いつでも、いかなる変更も起こりえます（MAY）。この時のパブリックAPIは安定していると考えるべきではありません（SHOULD NOT）。
0.y.zは運用ルールが特別
５.
バージョン1.0.0はパブリックAPIを定義します。このリリース後のバージョンナンバーの上げ方に関しては、パブリックAPIがどのくらい変更されるのかによって決まります。
1.0.0以降は運用ルールが厳密
６.
パッチバージョン Z （x.y.Z | x > 0）は、後方互換性を保ったバグ修正を取り込んだ場合のみ、上げなければなりません（MUST）。バグ修正とは間違った振る舞いを修正する内部の変更のことを指します。
７.
マイナーバージョン Y （x.Y.z | x > 0）は、後方互換性を保ちつつ機能性をパブリックAPIに追加した場合、上げなければなりません（MUST）。また、いかなるパブリックAPIも廃止予定としたのなら、上げなければなりません（MUST）。プライベートコード内での新しい機能の追加や改善を取り込んだ場合は、上げてもよいです（MAY）。その際にパッチレベルの変更も含めてもよいです（MAY）。マイナーバージョンを上げた際にはパッチバージョンを0にリセットしなければなりません（MUST）。
- バグ修正等の機能に影響がない内容の変更を実施したとしてもマイナーバージョンを更新してよい。
８.
メジャーバージョン X （X.y.z | X > 0）は、パブリックAPIに対して後方互換性を持たない変更が取り込まれた場合、上げなければなりません（MUST）。その際にマイナーおよびパッチレベルの変更も含めてもよいです（MAY）。メジャーバージョンを上げた際には、パッチおよびマイナーバージョンを0にリセットしなければなりません（MUST）。
- 一部のAPIを使えなくしたら、メジャーバージョンを上げる必要がある。
９.
プレリリースバージョンは、パッチバージョンの直後にハイフンとドットで区切られた識別子を追加することで表現してもよいです（MAY）。識別子は必ずASCII英数字とハイフン [0-9A-Za-z-] でなければなりません（MUST）。識別子は空であってはなりません（MUST NOT）。数値の識別子はゼロから始めてはなりません（MUST NOT）。プレリリースバージョンは関連する通常のバージョンよりも低い優先度です。プレリリースバージョンは、不安定であり、関連する通常のバージョンが示す要件と互換性を満たさない可能性があります。例：1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92。
１０.
ビルドメタデータはパッチまたはプレリリースバージョンの直後にプラス記号とドットで区切られた識別子を追加することで表現してもよいです（MAY）。識別子は必ずASCII英数字とハイフン [0-9A-Za-z-] でなければなりません（MUST）。識別子は空であってはなりません（MUST NOT）。バージョンの優先度を決める際にはビルドメタデータは無視されなければなりません（MUST）。つまり、2つのビルドメタデータだけが違うバージョンは、同じ優先度ということです。例：1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85。
１１.
バージョン同士をどのように比較するのかは優先度によって決まります。優先度はメジャー、マイナー、パッチ、プレリリース識別子の順番（ビルドメタデータは優先度に関して考慮しない）で分けて評価されなければなりません（MUST）。優先度は、各識別子を左から右に比較して最初の違いによって評価します。以下のように、メジャー、マイナー、パッチバージョンと常に数値的に比較します。例：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。メジャー、マイナー、パッチが同じ場合、プレリリースバージョンを持っている方が通常のバージョンよりも低い優先度です。例：1.0.0-alpha < 1.0.0。同じ、メジャー、マイナー、パッチを持つプレリリースバージョンの優先度の決定は、ドットで区切れた識別子を左から右に、異なるところが見つかるまで比較し決定しなければなりません（MUST）。数値のみで構成される識別子は数値的に比較され、文字列やハイフンを含む識別子はASCIIソート順に辞書的に比較されます。数値的な識別子は常に数値的でない識別子よりも低い優先度です。もし先行する識別子が同じ場合、プレリリースのフィールドが小さいセットよりも大きいセットのほうが高い優先度です。例：1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0。
