npmのバージョン管理まとめ - 文系プログラマー

たまにしか活用しないから忘れるのでメモ

参考: semver | npm Documentation

バージョン管理

npmでは、「セマンティックバージョニング」と呼ばれるバージョン管理法によって、依存パッケージやリリース物のバージョンを定義している。

npmにあるプロジェクトは少し異なるものもあるが、他の人と共有するようなプロジェクトは、普通 1.0.0 から始めるべきだ。

このルールに加えて、プロジェクトに変更を行った時のバージョンは次のように扱われる。

バグの修正やその他のマイナーチェンジ: パッチリリースでは最後の数字をインクリメントする (e.g. 1.0.1)
既存の機能を壊さないような新しい機能: マイナーリリースでは、真ん中の数字をインクリメントする (e.g. 1.1.0)
後方互換性のない変更: メジャーリリースでは、最初の数字をインクリメントする (e.g. 2.0.0)

npm では依存パッケージを package.json ファイルで管理する。そこでは、パッケージのバージョンを範囲指定することもできる。

もし、あるパッケージ 1.0.4 を範囲指定する時、次のようになる。

パッチリリースの範囲指定: 1.0 / 1.0.x / ~1.0.4
マイナーリリースの範囲指定: 1 / 1.x / ^1.0.4
メジャーリリースの範囲指定: * / x

詳しくは、このエントリの最後の後半で説明する。

演算子を用いて、更に細かく範囲指定することができる。これを、comparatorと呼ぶ。

< 未満
<= 以下
> より大きい
>= 以上
= イコール(演算子の指定がなければ適応される)

例えば、>=1.2.7 は 1.2.7 / 1.2.8 / 2.5.3 / 1.3.9 に一致するが、1.2.6 / 1.1.0 には一致しない。

また、comparator はホワイトスペースで結合できる(comparator set)。範囲指定は、さらにこの comparator set を || で結合して示されることがある。

例えば、 >=1.2.7 <1.3.0 は 1.2.7 / 1.2.8 / 1.2.99 に一致するが、1.2.6 / 1.3.0 / 1.1.0 には一致しない。

1.2.7 || >=1.2.9 <2.0.0 は 1.2.7 / 1.2.9 / 1.4.6 には一致するが、 1.2.8 / 2.0.0には一致しない。

プレリリースタグ (Prerelease Tags)

もし、バージョンがプレリリースタグ(e.g. 1.2.3-alpha.3)を持っていれば、同じ [major, minor, patch] で、プレリリースタグを持つ comparator しか、指定できない。

例えば、 >1.2.3-alpha.3 は 1.2.3-alpha.7 に一致するが、 3.4.5-alpha.9 には、一致しない。この場合、バージョンの範囲指定は、1.2.3のプレリリースタグにのみ適応される。3.4.5はプレリリースタグを持たず、1.2.3-alpha.3 より大きいので、これは条件を満たす。

こうした振る舞いには2つの理由があり、ひとつはプレリリースバージョンは頻繁に更新され、多くの前衛的変更を含む。従って、デフォルトでは範囲指定から外されている。

また、プレリリースバージョンを使用することを選んだユーザーは、特定の alpha/beta/rc バージョンを使用する意思をはっきりと示すことができる。範囲指定にプレリリースタグを含めることで、ユーザーはそれを使用することのリスクを自覚していることを示している。

更に詳しく

Hyphen Rangees X.Y.Z - A.B.C

以上/以下の範囲指定:

1.2.3 - 2.3.4 := >=1.2.3 <=2.3.4

最初と最後を含めて範囲指定する。欠けているものがあれば、0が代わりに使われる。

1.2 - 2.3.4 := >=1.2.0 <=2.3.4
1.2.3 - 2 := >=1.2.3 <3.0.0

X-Ranges 1.2.x / 1.x / 1.2.* /*

X / x / * はあらゆる数字の代わりになる。

* := >=0.0.0 (すべてのバージョン)
1.x := >=1.0.0 <2.0.0 (メジャーバージョンの範囲指定)
1.2.x := >=1.2.0 <1.3.0 (メジャーバージョン、マイナーバージョンの範囲指定)

Tilde Ranges ~1.2.3 / ~1.2 / ~1

Tilde rangesでは、comparator 上でマイナーバージョンを指定していれば、パッチレベルの変更は許容される。

~1.2.3 := >=1.2.3 <1.(2+1).0 := >=1.2.3 <1.3.0
~1.2 := >=1.2.0 <1.(2+1).0 := >=1.2.0 <1.3.0 (Same as 1.2.x)
~1 := >=1.0.0 <(1+1).0.0 := >=1.0.0 <2.0.0 (Same as 1.x)
~0.2.3 := >=0.2.3 <0.(2+1).0 := >=0.2.3 <0.3.0
~0.2 := >=0.2.0 <0.(2+1).0 := >=0.2.0 <0.3.0 (Same as 0.2.x)
~0 := >=0.0.0 <(0+1).0.0 := >=0.0.0 <1.0.0 (Same as 0.x)
~1.2.3-beta.2 := >=1.2.3-beta.2 <1.3.0 (プレリリースタグの範囲指定は 1.2.3 上でのみ適応される)

Caret Ranges ^1.2.3 / ^0.2.5 / ^0.0.4

Caret ranges ではパッチとマイナーチェンジは許容される。

Caret ranges は 0.2.4 と 3.0.0 の間にブレイキングチェンジ(既存の機能の削除など後方互換性のない変更)があることを想定している。しかし、 0.2.4 と 0.2.5 の間にブレイキングチェンジが絶対にないと想定していることに注意する。