Версии зависимостей

Семантическое управление версиями

Пакеты в Yarn используют семантическое управление версиями, также известным как «semver». При установке нового пакета из реестра он будет добавлен в package.json с диапазоном версий semver.

Эти версии разбиты на major.minor.patch и выглядят примерно так: 3,14,1, 0,42,0, 2,7,18. Каждая часть версии увеличивается в разное время:

  • major версия увеличивается, когда вносятся изменения ломающие совместимость или несовместимые с API пакета.
  • Увеличивайте minor версию, если добавляется новая функциональность, или работает обратная совместимость
  • Увеличивайте patch версию если произведены исправления и осталась обратная совместимость

Примечание: иногда существуют также “метки” или “расширения” для semver формата, обозначающие предварительные релизы или бета-версии (например: 2.0.0-beta.3)

Когда разработчики говорят о том, что две версии semver «совместимы» друг с другом, они имеют ввиду изменения, имеющие обратную совместимость (minor и patch версии).

Диапазоны версий

Когда вы хотите указать зависимость, вы указываете ее имя и диапазон версий в package.json, например, одно из следующих:

{
  "dependencies": {
    "package-1": ">=2.0.0 <3.1.4",
    "package-2": "^0.4.2",
    "package-3": "~2.7.1"
  }
}

Вы заметите, что есть много символов кроме версии. Это символы: >=, <, ^ и ~. Они являются операторами и используются для указания диапазона версий.

Цель диапазона версий - указать, какие версии зависимостей будут работать с вашим кодом.

Компараторы

Каждый диапазон версий состоит из компараторов. Они являются просто оператором, за которым следует версия. Вот некоторые из основных:

Компаратор Описание
<2.0.0 Любая версия, которая меньше 2.0.0
<=3.1.4 Любая версия, которая меньше или равна 3.1.4
>0.4.2 Любая версия, которая больше 0.4.2
>=2.7.1 Любая версия, которая больше или равна 2.7.1
=4.6.6 Любая версия, равная 4.6.6

Примечание: если оператор не указан, то предполагается допущение, что указан оператор = диапазону указанных версий. Таким образом, знак = является, по сути, необязательным.

Пересечения

Компараторы могут быть объединены пробелами для создания набора компараторов. Это создает пересечение компараторов, которые оно включает. Например, набор сравнения >=2.0.0 <3.1.4 означает “больше или равно 2.0.0 и меньше 3.1.4.

Объединения

Полный диапазон версий может включать в себя объединение нескольких наборов компараторов вместе ||. Если одна из сторон объединения верна, то весь диапазон версий считается подходящим. Например версия с диапазоном &lt;2.0.0 || &gt;3.1.4 означает: «Меньше, чем 2.0.0 или больше, чем 3.1.4».

Предрелизные теги

Версии могут иметь и предрелизные теги (например: 3.1.4-beta.2). Если компаратор включает версию с тегом предварительной версии, он будет сопоставляться только с версиями, входящими в ту же ветку готовности major.minor.patch.

Например, диапазон >= 3.1.4-beta.2 будет соответствовать 3.1.4-beta.2 или 3.1.4-beta.12, но не будет соответствовать 3.1.5-beta.1, даже если это технически «больше или равно» (>=) 3.1.4-beta.2 версии.

Предварительные выпуски, как правило, содержат критические изменения. Обычно не хотят сопоставлять предварительные выпуски со стабильной версией, поэтому такое поведение полезно.

Расширенные диапазоны версий

Диапазоны через дефис

Диапазоны через дефис (например, 2.0.0 - 3.1.4) определяют набор версий включительно. Если часть версии не указана (например, 0.4 или 2), то она заполняются нулями.

Диапазон версий Расширенный диапазон версий
2.0.0 - 3.1.4 >=2.0.0 <=3.1.4
0.4 - 2 >=0.4.0 <=2.0.0
X-диапазоны

Если нужно оставить неопределённой любую часть версии, то вместо неё подставляют знаки X, x, или *.

Диапазон версий Расширенный диапазон версий
* >=0.0.0 (любая версия)
2.x >=2.0.0 <3.0.0 (соответствует основной версии)
3.1.x >=3.1.0 <3.2.0 (соответствует основной и второстепенной версии)

Если часть версии опущена, предполагается, что это x-диапазон.

Диапазон версий Расширенный диапазон версий
``(пустая строка) * или >=0.0.0
2 2.x.x или >= 2.0.0 <3.0.0
3.1 3.1.x или >=3.1.0 <3.2.0
Диапазоны с тильдой

Использование ~ с указанием второстепенной версии позволяет изменять версию патча patch. Использование ~ с указанием только основной версии позволит указать второстепенные изменения.

Диапазон версий Расширенный диапазон версий
~3.1.4 >=3.1.4 <3.2.0
~3.1 3.1.x или >=3.1.0 <3.2.0
~3 3.x или >=3.0.0 <4.0.0

Примечание: указание предварительных выпусков в диапазоне с тильдой будет соответствовать предварительным выпускам только в той же основной версии. Например, диапазон версий ~3.1.4-beta.2 будет соответствовать 3.1.4-beta.4, но не 3.1.5-бета.2 потому что major.minor.patch версии отличается.

Диапазоны со знаком возведения в степень

Разрешить изменения версии, которые не затрагивают первую ненулевую цифру: либо 3 в 3.1.4, либо 4 в <0 >0.4.2</code>.

Диапазон версий Расширенный диапазон версий
^3.1.4 >=3.1.4 <4.0.0
^0.4.2 >=0.4.2 <0.5.0
^0.0.2 >=0.0.2 <0.0.3

Примечание: по умолчанию при запуске yarn add [package-name] будет использоваться диапазон со знаком возведения в степень.

Если часть версии пропущена, недостающие части заполняются нулями. Однако по-прежнему можно менять это значение.

Диапазон версий Расширенный диапазон версий
^0.0.x >=0.0.0 <0.1.0
^0.0 >=0.0.0 <0.1.0
^0.x >=0.0.0 <1.0.0
^0 >=0.0.0 <1.0.0

Дополнительные ресурсы

  • Для полной спецификации того, как работает эта система управления версиями, смотрите node-semver README.
  • Протестируйте систему управления версиями на реальных пакетах возможно с помощью npm semver calculator.