Home

Allajah's Reservoir

28 Jun 2017

package.jsonでのセマンティックバージョン指定方法

このエントリーをはてなブックマークに追加

はじめに

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

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

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

バージョン

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

レンジ

  • バージョンレンジは、レンジを満たすようにバージョンを指定する、comparatorにセットされる
  • comparatorはoperatorとバージョンによって構成される。プリミティブなoperatorとして、
    • < 未満
    • <= 以下
    • > を超える
    • >= 以上
    • = 等しい(operatorが指定されてなかった場合は、 =とみなされるため=は必須ではないが、書いたほうが良い)

    がある。

    例えば、comparatorが >=1.2.7 だったら、1.2.71.2.82.5.31.3.9、にはマッチするが、1.2.61.1.0にはマッチしない。

    複数のcomparatorはスペースによって結合されることで、comparator setを形成し、comparator setは全てのcomparatorが含んでいる交点によって満たされる。

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

    例えば、>=1.2.7 <1.3.0というcomparator setは1.2.71.2.81.2.99にはマッチするが、1.2.61.3.01.1.0、にはマッチしない。

    さらに、1.2.7 || >=1.2.9 <2.0.0 というレンジは、1.2.71.2.91.4.6にはマッチするが、1.2.82.0.0にはマッチしない

プリリリースタグ

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

例えば、>1.2.3-alpha.31.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.* *

Xx* はいずれもタプルの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.40.3.0でブレイキングチェンジを行うかもしれない場合は理想的であり、一般的な手法である。 しかし、これは0.2.40.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

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

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

まとめ

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

Allajah at 16:02