毎度調べては忘れるセマンティックバージョニング。
忘備録の意味も兼ねてまとめてみた。
セマンティックバージョニング1とは
ソフトウェアのバージョンをどう管理するかについての決めごと。
具体的には、メジャーバージョン マイナーバージョン パッチバージョン の3パートから構成され、それぞれを x, y, z とすると x.y.z と表記される。
メジャーバージョン は、後方互換性のないAPIを変更した場合
マイナーバージョン は、後方互換性を保ちつつAPIを変更・追加した場合
パッチバージョン は、APIに影響を及ぼさないバグを修正した場合
にそれぞれバージョンアップされる。
「どのバージョンを上げるかを意識するのは API 提供側のため、単に API を利用するのみの場合は、続けて記載するバージョン指定方法を理解した上で適切なバージョンを指定して開発を進めていくことになる」 と認識している。
npm におけるパッケージのバージョン指定
npm install <package> により npm パッケージをインストールすると、package.json ファイルにインストールしたパッケージ名とセマンティックバージョンが追記される。
...
"dependencies": {
"hoge": "^1.2.3"
},
..
この時、多くのパッケージに対して ^(キャレット) や ~(チルダ) がバージョンの前に付与されていることがわかる。
これは、単に指定されたバージョンをインストールするのではなく、以下のルールに従うことを意味する。
-
^: 一番最初のゼロでないバージョンを固定し、それ以下は指定されたバージョン以上が対象となる。 -
~:- メジャーバージョンのみ指定されている場合: マイナーバージョン以下は、それらより大きなものが対象となる(メジャーバージョンのみ固定)。
- マイナーバージョン以下も指定されている場合: パッチバージョンは指定したものより大きなものが対象となる。
^ と ~ を伴うバージョン指定によりインストールされることが想定される例をいくつか示す。
| バージョン指定 | 想定インストールバージョン | 備考 |
|---|---|---|
| 1.2.3 | 1.2.3 |
^ や ~ がない場合は単一バージョンが対象 |
| ^1.2.3 | 1.y.z(y>=2, z>=3) で一番大きいの | メジャーバージョン 1 が固定、マイナー以下は任意 |
| ^0.2.3 | 0.2.z(z>=3) で一番大きいの | マイナーバージョン 2 が固定、パッチは任意 |
| ^0.0.3 | 0.0.3 | パッチバージョン 3 固定 |
| ^1.2 | 1.y.z(y>=2, z>=0) で一番大きいの | ^1.2.0 と同義。マイナーバージョン以下は任意 |
| ^1 | 1.y.z(y>=0, z>=0) で一番大きいの | ^1.0.0 と同義。マイナーバージョン以下は任意 |
| ^0.2 | 0.2.z(z>=0) で一番大きいの | ^0.2.0 と同義。パッチバージョンは任意 |
| ~1.2.3 | 1.2.z(z>=3) で一番大きいの | パッチバージョンは任意 |
| ~0.2.3 | 0.2.z(z>=3) で一番大きいの | パッチバージョンは任意 |
| ~0.0.3 | 0.0.z(z>=3) で一番大きいの | パッチバージョンは任意 |
| ~1.2 | 1.2.z(z>=0) で一番大きいの | ~1.2.0 と同義。パッチバージョンは任意 |
| ~1 | 1.y.z(y>=0, z>=0) で一番大きいの | ~1.0.0 と同義。マイナーバージョン以下は任意 |
| ~0.2 | 0.2.z(z>=0) で一番大きいの | ~０.2.0 と同義。パッチバージョンは任意 |
npm install によるパッケージのインストールの結果、package.json では特に ^ によるバージョン指定が多いが、これは 「後方互換性のないAPIを変更するメジャーバージョンアップ」を避ける範囲において最新のバージョンにするという挙動となっており、make sense である。
ツールによる確認
なお、指定したセマンティックバージョンでどのバージョンが対象となるかは、こちらのサイトで確認できる。
例1)lodash: ^1.1.1
例2)lodash: ^4.3
例3)lodash: ~4.3
参考にさせていただいたページ