Quelle est la syntaxe de la version bower (et npm)?

Bower me permet de spécifier les exigences de version pour les packages à l'aide de la syntaxe suivante:

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

Mais je n'ai pas pu trouver quelle est la syntaxe à utiliser pour le <version>. Je sais que je peux spécifier que les versions doivent être:

• supérieur à une certaine version avec ">1.0.0"
• supérieur ou égal à une version: ">=1.0.0"
• ou dans une plage: "1.0.0 - 2.0.0".

Je sais aussi qu'il ya une syntaxe de version commune contenant le tilde: "~1.0.0". Mais je ne sais pas ce que cela signifie et si c'est la même chose que "=1.0.0".

Je suis également intéressé de savoir si je suis capable de spécifier plusieurs versions non consécutives, telles que des 1.0.3versions exactement plus supérieures à 1.5.0, etc.

En résumé, la syntaxe des numéros de version de Bower (et des NPM) est appelée SemVer, qui est l'abréviation de «Semantic Versioning». Vous pouvez trouver de la documentation pour la syntaxe détaillée de SemVer utilisée dans Bower et NPM sur l'API pour l'analyseur semver dans Node / npm . Vous pouvez en savoir plus sur la spécification sous-jacente (qui ne mentionne pas~ ou d'autres détails de syntaxe) sur semver.org .

Il y a une calculatrice visuelle très pratique avec laquelle vous pouvez jouer, ce qui rend tout cela beaucoup plus facile à tester et à tester.

SemVer n'est pas seulement une syntaxe! Il a des choses assez intéressantes à dire sur les bonnes façons de publier des API, qui aideront à comprendre ce que signifie la syntaxe. Crucialement:

Une fois que vous avez identifié votre API publique, vous lui communiquez les modifications avec des incréments spécifiques à votre numéro de version. Considérez un format de version de XYZ (Major.Minor.Patch) . Les corrections de bogues n'affectant pas l'incrémentation de l'API de la version du correctif, les ajouts / modifications d'API rétrocompatibles incrémentent la version mineure et les modifications d'API incompatibles en arrière incrémentent la version principale.

Votre question spécifique ~concerne donc ce schéma Major.Minor.Patch. (De même que l'opérateur caret associé ^.) Vous pouvez utiliser ~pour réduire la gamme de versions que vous êtes prêt à accepter:

• des modifications ultérieures au niveau du correctif vers la même version mineure ( «corrections de bogues n'affectant pas l'API» ), ou
• modifications ultérieures de niveau mineur à la même version principale ( "ajouts / modifications d'API rétrocompatibles" )

Par exemple: pour indiquer que vous prendrez toutes les modifications ultérieures au niveau du correctif sur l'arborescence 1.2.x, en commençant par 1.2.0, mais moins de 1.3.0, vous pouvez utiliser:

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

Cela vous donne également les mêmes résultats que l'utilisation de la .xsyntaxe:

"angular": "1.2.x"

Mais, vous pouvez utiliser le tilde / ~syntaxe pour être encore plus spécifique: si vous êtes seulement prêt à accepter les changements au niveau du patch commençant par 1.2.4 , mais toujours inférieur à 1.3.0, vous utiliseriez:

"angular": "~1.2.4"

Déplacement vers la gauche, vers la version principale , si vous utilisez ...

"angular": "~1"

... c'est la même chose que ...

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

... et correspond à toute modification mineure ou au niveau du patch supérieure à 1.0.0 et inférieure à 2.0:

Notez cette dernière variation ci-dessus: elle s'appelle une 'gamme de carets' . Le signe d'insertion ressemble énormément à un >, donc vous seriez excusé de penser que cela signifie "toute version supérieure à 1.0.0". (J'ai certainement glissé là-dessus.) Non!

Les plages de signes d'insertion sont essentiellement utilisées pour dire que vous vous souciez uniquement du chiffre le plus à gauche - généralement la version principale - et que vous autoriserez tous les changements mineurs ou au niveau du patch qui n'affectent pas ce chiffre le plus à gauche. Pourtant, contrairement à une plage tilde qui spécifie une version majeure, les plages caret vous permettent de spécifier un point de départ mineur / correctif précis. Ainsi, tandis ^1.0.0 === ~1qu'une plage de points d'insertion telle que ^1.2.3vous permet de dire que vous prendrez toutes les modifications >=1.2.3 && <2.0.0. On ne pouvait pas faire ça avec une gamme tilde.

Tout cela semble déroutant au début, quand on regarde de près. Mais faites un zoom arrière pendant une seconde et pensez-y de cette façon: le curseur vous permet simplement de dire que vous êtes le plus préoccupé par le chiffre significatif le plus à gauche. Le tilde vous permet de dire que vous êtes le plus préoccupé par le chiffre le plus à droite. Le reste est un détail.

C'est la puissance expressive du tilde et du curseur qui explique pourquoi les gens les utilisent beaucoup plus que la .xsyntaxe plus simple : ils vous laissent simplement faire plus. C'est pourquoi vous verrez souvent le tilde utilisé même là où .xil servirait. Par exemple, voyez npm lui-même: son propre fichier package.json inclut beaucoup de dépendances au ~2.4.0format, plutôt que le 2.4.xformat qu'il pourrait utiliser. En respectant ~, la syntaxe est cohérente tout au long d'une liste de plus de 70 dépendances versionnées, quel que soit le numéro de patch de début acceptable.

Quoi qu'il en soit, SemVer contient encore plus, mais je n'essaierai pas de tout détailler ici. Vérifiez-le dans le fichier Lisez-moi du paquetage node semver . Et assurez-vous d'utiliser la calculatrice de gestion des versions sémantique pendant que vous vous entraînez et essayez de comprendre comment fonctionne SemVer.

RE: Numéros de version non consécutifs: La dernière question d'OP semble être de spécifier les numéros de version / plages non consécutifs (si je l'ai édité de manière équitable). Oui, vous pouvez le faire, en utilisant la double conduite commune « ou » opérateur: ||. Ainsi:

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

Basé sur semver , vous pouvez utiliser

• Gammes de trait d'union XYZ - ABC 1.2.3-2.3.4 indique > = 1.2.3 <= 2.3.4

• Gammes X 1.2.x 1.X 1.2.*

• Tilde Ranges ~1.2.3 ~1.2 Indique autoriser des modifications au niveau du correctif ou des modifications de version mineures.

• Plages Caret ^ 1.2.3 ^ 0.2.5 ^ 0.0.4

  Permet les modifications qui ne modifient pas le chiffre non nul le plus à gauche dans le tuple [majeur, mineur, patch]

  • ^1.2.x (signifie> = 1.2.0 <2.0.0)
  • ^0.0.x (signifie> = 0,0,0 <0,1,0)
  • ^0.0 (signifie> = 0,0,0 <0,1,0)

Bower utilise la syntaxe semver , mais voici quelques exemples rapides:

Vous pouvez installer une version spécifique:

$ bower install jquery#1.11.1

Vous pouvez utiliser ~ pour spécifier «toute version commençant par ceci»:

$ bower install jquery#~1.11

Vous pouvez spécifier plusieurs exigences de version ensemble:

$ bower install "jquery#<2.0 >1.10"

Vous pouvez également utiliser le latestmot - clé pour installer la version la plus récente disponible:

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

S'il n'y a pas de numéro de patch, ~équivaut à l'ajouter .xà la version non tilde. S'il y a un numéro de patch, ~autorise tous les numéros de patch> = celui spécifié.

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

Je n'ai pas assez de points pour commenter la réponse acceptée, mais certaines des informations tilde est en désaccord avec le lien semver documentation: "angular": "~1.2"ne pas correspondre à 1.3, 1.4, 1.4.9. Aussi "angular": "~1"et ne"angular": "~1.0" sont pas équivalents. Cela peut être vérifié avec la calculatrice semver npm .