Що таке синтаксис версії bower (та npm)?

Bower дозволяє мені вказати вимоги до версії для пакетів, використовуючи наступний синтаксис:

"dependencies": {
  "<name>": "<version>",
},

Але я не зміг знайти синтаксис, який слід використовувати для <version>. Я знаю, що можу вказати версії, які будуть:

• більше, ніж певна версія з ">1.0.0"
• більше або дорівнює версії: ">=1.0.0"
• або в якому - то діапазоні: "1.0.0 - 2.0.0".

Я також знаю , що є загальна версія синтаксис , що містять тильди: "~1.0.0". Але я не впевнений, що це означає і чи це те саме "=1.0.0".

Мені також цікаво дізнатись, чи можу я вказати кілька непослідовних версій, таких як точно 1.0.3плюс версії більше, ніж 1.5.0тощо.

У двох словах, синтаксис номерів версій Bower (і NPM) називається SemVer, що скорочується як "Semantic Versioning". Ви можете знайти документацію для детального синтаксису SemVer, який використовується в Bower та NPM, в API для синтаксичного аналізатора в межах Node / npm . Ви можете дізнатися більше про базову специфікацію (яка не згадує ~та інші деталі синтаксису) на semver.org .

Існує надзвичайно зручний візуальний калькулятор semver, з яким ви можете грати, що робить все це набагато простішим для того, щоб пограбувати та перевірити.

SemVer - це не просто синтаксис! Є кілька цікавих речей про правильні способи публікації API, що допоможе зрозуміти, що означає синтаксис. Принципово важливо:

Після того, як ви ідентифікуєте свій загальнодоступний API, ви повідомляєте про нього зміни з певними кроками до номера своєї версії. Розглянемо формат версії XYZ (Major.Minor.Patch) . Виправлення помилок, які не впливають на приріст API версії патча, додатково сумісні додатки API / зміни, збільшуючи незначну версію, і назад несумісні зміни API збільшують основну версію.

Отже, ваше конкретне питання щодо ~стосується цієї схеми Major.Minor.Patch. (Як і пов'язаний оператор карет ^.) Ви можете використовувати ~для звуження діапазону версій, які ви готові прийняти:

• наступні зміни на рівні патчу на ту ж незначну версію ( "виправлення помилок, що не впливають на API" ), або:
• наступні незначні зміни на тій же основній версії ( "назад / сумісні доповнення / зміни API" )

Наприклад: щоб вказати, що ви будете приймати будь-які наступні зміни рівня патчу на дереві 1.2.x, починаючи з 1.2.0, але менше 1.3.0, ви можете використовувати:

"angular": "~1.2"
  or:
"angular": "~1.2.0"

Це також отримує ті самі результати, що і за допомогою .xсинтаксису:

"angular": "1.2.x"

Але ви можете використовувати ~синтаксис tilde / синтаксису, щоб бути ще більш конкретним: якщо ви готові прийняти зміни лише на рівні патчу, починаючи з 1.2.4 , але все ще менше 1.3.0, ви будете використовувати:

"angular": "~1.2.4"

Рухаючи вліво, до основної версії, якщо ви використовуєте ...

"angular": "~1"

... це те саме, що ...

"angular": "1.x"
  or:
"angular": "^1.0.0"

... і відповідає будь-яким незначним змінам або змінам на рівні патчу вище 1,0,0 і менше 2,0:

Зауважте, що остання версія вище: вона називається "діапазон карет" . Карета виглядає жахливо багато як >, так що ви б вибачили, думаючи, що це означає "будь-яка версія, що перевищує 1,0,0". (Я, звичайно, прослизнув на цьому.) Ні!

Діапазони карет в основному використовуються для того, щоб говорити про те, що ви дбаєте лише про найзначнішу ліву цифру - як правило, про основну версію - і що ви допускаєте будь-які зміни на рівні другого або латки, які не впливають на цю найбільшу ліву цифру. Однак, на відміну від діапазону тильди, який визначає основну версію, діапазони карет дозволяють вказати точну початкову точку другорядного / виправлення. Тож, ^1.0.0 === ~1діапазон карет, наприклад, ^1.2.3дозволяє сказати, що ви вживатимете будь-які зміни >=1.2.3 && <2.0.0. З діапазоном тильда ви цього не могли зробити.

Це спочатку здається заплутаним, коли ви дивитесь на це близько. Але зменшіть на секунду і подумайте про це так: карета просто дозволяє вам сказати, що вас найбільше турбує те, що залишається найбільш значущою цифрою. Тильда дозволяє вам сказати, що вас найбільше турбує той, який цифр є найбільш правильним. Решта - деталі.

Саме виразна сила тильди і карета пояснюють, чому люди використовують їх набагато більше, ніж простіший .xсинтаксис: вони просто дозволяють робити більше. Ось чому ви побачите тильду, яку часто використовують, навіть там, де вона .xбуде служити. Як приклад, див. Сам npm: його власний файл package.json включає багато залежностей у ~2.4.0форматі, а не 2.4.xформат, який він може використовувати. Дотримуючись ~, синтаксис узгоджується на весь перелік залежностей від 70+, незалежно від того, який початковий номер виправлення є прийнятним.

У всякому разі, у SemVer є ще багато, але я не намагатимусь тут все це деталізувати. Перевірте це в режимі readme пакета вузла . І не забудьте використовувати калькулятор семантичної версії, коли ви тренуєтесь і намагаєтесь навчитись, як працює SemVer.

RE: Непослідовні номери версій: Кінцеве питання ОП, схоже, стосується конкретизації номерів / діапазонів непослідовних версій (якщо я це правильно відредагував). Так, ви можете зробити це, використовуючи загальну подвійну трубу «або» оператор: ||. Так:

"angular": "1.2 <= 1.2.9 || >2.0.0"

На основі semver ви можете використовувати

• Діапазон дефісів XYZ - ABC 1.2.3-2.3.4 Позначає > = 1.2.3 <= 2.3.4

• X-діапазони 1.2.x 1.X 1.2.*

• Діапазони нахилів ~1.2.3 ~1.2 Позначає, що дозволяє змінити рівень патча або незначні зміни версій.

• Діапазони карет ^ 1.2.3 ^ 0.2.5 ^ 0.0.4

  Дозволяє зміни, які не змінюють найбільшу нульову цифру в кортежі [основний, другорядний, виправлення]

  • ^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)

Bower використовує синтаксис semver , але ось кілька швидких прикладів:

Ви можете встановити конкретну версію:

$ bower install jquery#1.11.1

Ви можете використовувати ~, щоб вказати "будь-яку версію, яка починається з цього":

$ bower install jquery#~1.11

Ви можете разом вказати кілька вимог до версії:

$ bower install "jquery#<2.0 >1.10"

Ви також можете скористатися latestключовим словом, щоб встановити останню доступну версію:

  "dependencies": {
    "fontawesome": "latest"
  }

Якщо номер патча відсутній, ~він еквівалентний додаванню .xдо нетильдової версії. Якщо є номер виправлення, ~дозволяє всі номери виправлень> = вказаний.

~1     := 1.x
~1.2   := 1.2.x
~1.2.3 := (>=1.2.3 <1.3.0)

У мене немає достатньо очок , щоб прокоментувати загальноприйнятому відповідь, але частина інформації тильди знаходиться в протиріччі з пов'язаним semver документації: "angular": "~1.2"буде НЕ відповідати 1.3, 1.4, 1.4.9. Крім того, "angular": "~1"і "angular": "~1.0"це НЕ еквівалентні. Це можна підтвердити за допомогою калькулятора npm semver .