はじめに

今まで pacakge.json のバージョン指定をなんとなくやっていたり、npm install --saveで記述されるものをそのまま使ってたので、 ちゃんとバージョン指定方法を理解しようと思いました。

これはnpm の公式ドキュメントの一部を翻訳し、まとめたものです。 翻訳ミス等が分かり次第、修正しますので、教えていただけると幸いです。 また、翻訳に自信がない箇所が数カ所あります。

npm で使用するセマンティックバージョン

バージョン

• バージョニングは http://semver.org/ で説明されている
• =およびvの 2 つの文字は取り除かれ、無視させる

レンジ

• バージョンレンジは、レンジを満たすようにバージョンを指定する、comparator にセットされる

• comparator は operator とバージョンによって構成される。プリミティブな operator として、

  • < 未満
  • <= 以下
  • > を超える
  • >= 以上
  • = 等しい(operator が指定されてなかった場合は、 =とみなされるため=は必須ではないが、書いたほうが良い)

  がある。

  例えば、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 は全ての comparator が含んでいる交点によって満たされる。

  レンジは||で連結された 1 つ以上の comparator set で構成される。バージョンは 、||で分離された comparator set のうち最低 1 つがバージョンによって満たされる場合にのみ、マッチする。

  例えば、>=1.2.7 <1.3.0という comparator set は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にはマッチしない

プリリリースタグ

バージョンが 1.2.3-alpha.3 のようにプリリリースタグを持っていた場合、最低 1 つ以上の comparator がプリリリースを持っている[major, minor, patch]タプルと同じ場合のみ、comparator set を満たすことが許される

例えば、>1.2.3-alpha.3は1.2.3-alpha.7とマッチ可能だが、3.4.5-alpha.9では満たされない。3.4.5-alpha.9が、セマンティックバージョニングで技術的には1.2.3-alpha.7より大きくてもだ。

このふるまいの意図は 2 つある。

1 つは、プリリリースバージョンは非常に高頻度でアップデートされ、多数の未だ一般的な消費と合わない破壊的変更を含むことだ。したがって、デフォルトでは、プリリリースバージョンは意味論的なマッチングのレンジからは除外される。

2 つ目として、プリリースバージョンの使用を選んだユーザーは alpha/beta/rc バージョンのセットを使用する意図が明確に示されている。 レンジにプリリースバージョンタグを含めることで、ユーザーはリスクを認識していることを示している。 しかし、ユーザーが次のプリリリースバージョンでも同様なリスクを取ることを選択したと改定するには、適切ではない。

応用的なレンジシンタックス

応用的レンジシンタックスはプリミティブな comparator を決定論的な方法で desugar する 応用的なレンジはスペースまたは||を用いたプリミティブ comparator と同じ方法で結合される

ハイフンレンジ X.Y.Z - A.B.C

包括的セットを指定 1.2.3 - 2.3.4 := >=1.2.3 <=2.3.4 包括的レンジの最初のバージョンとして部分的なバージョンが提供されていたら、省略された部分はゼロに置き換えられる。 1.2 - 2.3.4 := >=1.2.0 <=2.3.4 部分的なバージョンが包括的レンジの 2 つ目の値として与えられていたら、タプルの与えられた部分で始まる全てのバージョンが受け入れられるが、 提供されたタプルパーツよりも大きくなることはない。 1.2.3 - 2.3 := >=1.2.3 <2.4.0 1.2.3 - 2 := >=1.2.3 <3.0.0

X-レンジ 1.2.x 1.X 1.2.* *

X、x、* はいずれもタプルの 1 つの数値で、「すべての値」を表すのに用いられる。

• * := >=0.0.0 (どんなバージョンでも満たす)
• 1.x := >=1.0.0 <2.0.0 (メジャーバージョンが同じものにマッチする)
• 1.2.x := >=1.2.0 <1.3.0 (メジャーバージョンとマイナーバージョンが同じものにマッチする) 部分的バージョンは X-レンジとして扱われるため、特別な文字は事実上オプショナルである。
• "" (空文字) := * := >=0.0.0
• 1 := 1.x.x := >=1.0.0 <2.0.0
• 1.2 := 1.2.x := >=1.2.0 <1.3.0

チルダレンジ ~1.2.3 ~1.2 ~1

マイナーバージョンが 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 (1.2.x と同じ)
• ~1 := >=1.0.0 <(1+1).0.0 := >=1.0.0 <2.0.0 (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 (0.2.x と同じ)
• ~0 := >=0.0.0 <(0+1).0.0 := >=0.0.0 <1.0.0 (0.x と同じ)
• ~1.2.3-beta.2 := >=1.2.3-beta.2 <1.3.0 (beta.2 以上の 1.2.3 のプリリースバージョンが許可されることに注意。 1.2.3-beta.4は許可されるが、1.2.4-beta.2は[major, minor, patch]タプルとマッチしないプリリースのため許可されない。)

キャレットレンジ ^1.2.3 ^0.2.5 ^0.0.4

[major, minor, patch]タプルの一番左のゼロではない数字を変更しない変更を許可する。 言い換えると、これはバージョン1.0.0以上では patch と minor のアップデートを許容し、0.X >= 0.1.0では patch アップデートを許可し、 0.0.Xではアップデートが行われない。

多くの作者はxがブレイキングチェンジインディケータであるように0.xバージョンを扱う。 キャレットレンジは作者が0.2.4で0.3.0でブレイキングチェンジを行うかもしれない場合は理想的であり、一般的な手法である。 しかし、これは0.2.4と0.2.5の間でブレイキングチェンジがないということを仮定している。 これは一般的に観察されているプラクティスによると、(ブレイキングチェンジではない)追加があることが仮定された変更を許可する。

• ^1.2.3 := >=1.2.3 <2.0.0
• ^0.2.3 := >=0.2.3 <0.3.0
• ^0.0.3 := >=0.0.3 <0.0.4
• ^1.2.3-beta.2 := >=1.2.3-beta.2 <2.0.0 1.2.3のプリリースバージョンがbeta.2以上の場合許可されることに注意。 そのため、1.2.3-beta.4は許可されるが、1.2.4-beta.2は許可されない。
• ^0.0.3-beta := >=0.0.3-beta <0.0.4 0.0.3のプリリリースのみが許可されることに注意。つまり、0.0.3-pr.2が許可される。

キャレットレンジをパースする時、省略されたpatchの値は0に desugar するが、major と minor の値がどちらも 0 の場合であってもその数値の柔軟性を許容する。

• ^1.2.x := >=1.2.0 <2.0.0
• ^0.0.x := >=0.0.0 <0.1.0
• ^0.0 := >=0.0.0 <0.1.0

省略されたminorとpatchの値は 0 に desugar するが、major の値が 0 であってもそれらの値の中で柔軟性を許容する。

• ^1.x := >=1.0.0 <2.0.0
• ^0.x := >=0.0.0 <1.0.0

まとめ

• ~と^ はよく使うけど、意味をちゃんと知らないと意図しないバージョンのパッケージがインストールされてしまうことがあるため注意。

変更履歴

360d0cfd Add icon variations