Versions de dépendances

Versioning Semantique

Les packages dans Yarn suivent le Versioning Semantique, aussi connu sous le nom de “semver”. Lorsque vous installez un nouveau package depuis un registre, il sera ajouté à votre package.json avec un intervalle de version semver.

Ces versions se découpent en major.minor.patch et ressemble à ceci : 3.14.1, 0.42.0, 2.7.18. Chaque partie de la version est incrémentée en différentes occasions :

  • Incrémentez major lorsque vous faites des changements qui cassent ou rendent incompatible l’API de votre package.
  • Incrémentez minor lorsque vous ajoutez de nouvelles fonctionnalités tout en étant rétro-compatible.
  • Incrémentez patch lorsque vous faites un correctif de bug tout en restant rétro-compatible.

Remarque : il y a parfois des “libellés” ou des “extensions” au format semver afin de signaler des versions comme des pré-releases ou des bétas (par exemple 2.0.0-beta.3).

Lorsque des développeurs disent que deux versions semver sont “compatibles” avec une troisième, ils font référence à des changements rétro-compatibles (minor et patch).

Intervalles de versions

Lorsque vous spécifiez une dépendance, vous spécifiez son nom et un intervalle de versions dans votre package.json, par exemple :

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

Vous noterez que nous avons plusieurs caractères en plus de la version. Ces caractères, >=, <, ^ et ~, sont des operateurs et sont utilisés pour spécifier des intervalles de versions.

Le but des intervalles de versions est de spécifier quelles versions d’une dépendance fonctionneront avec votre code.

Comparateurs

Chaque intervalle de versions est constitué de comparateurs. Ces comparateurs sont simplement un opérateur suivi d’une version. Voici certains opérateurs basiques :

Comparateur Description
<2.0.0 N’importe quelle version inférieure à 2.0.0
<=3.1.4 N’importe quelle version inférieure ou égale à 3.1.4
>0.4.2 N’importe quelle version supérieure à 0.4.2
>=2.7.1 N’importe quelle version supérieure ou égale à 2.7.1
=4.6.6 N’importe quelle version égale à 4.6.6

Remarque : si aucun opérateur n’est spécifié, alors = est considéré comme étant l’intervalle de version. Donc l’opérateur = est en fait optionnel.

Intersections

Les comparateurs peuvent être combinés avec des espaces pour créer un ensemble de comparateurs. Cela crée une intersection des comparateurs inclus. Par exemple l’ensemble de comparateurs >=2.0.0 <3.1.4 signifie “Supérieur ou égal à 2.0.0 et inférieur à 3.1.4“.

Unions

Un intervalle de versions complet peut contenir une union de plusieurs ensembles de comparateurs, groupés ensemble avec ||. Si l’un des deux côté de l’union est satisfait, alors l’intégralité de l’intervalle de versions est satisfait. Par exemple, l’intervalle de versions <2.0.0 || >3.1.4 signifie “Inférieur à 2.0.0 ou supérieur à 3.1.4“.

Tags de pré-release

Les versions peuvent également avoir des tags de pré-release (par exemple 3.1.4-beta.2). Si un comparateur inclut une version avec un tag de pré-release, il ne concordera qu’avec les versions qui ont le même major.minor.patch.

Par exemple, l’intervalle >=3.1.4-beta.2 concorderait avec 3.1.4-beta.2 ou 3.1.4-beta.12, mais ne concorderait pas avec 3.1.5-beta.1 même si la version est techniquement “supérieure ou égale à” (>=) la version 3.1.4-beta.2.

Ce comportement est utile car les pré-releases ont tendance à contenir d’accidentels changements incompatibles avec les versions précédentes et généralement vous ne voulez pas récupérer de pré-releases en dehors de la version que vous avez spécifiée.

Intervalles de versions avancés

Intervalles avec trait d’union

Les intervalles avec un trait d’union (par exemple 2.0.0 - 3.1.4) spécifient un espace inclusif. Si une partie de la version n’est pas précisée (par exemple 0.4 ou 2), cette partie manquante est remplacée par des zéros.

Intervalle de version Intervalle de version étendu
2.0.0 - 3.1.4 >=2.0.0 <=3.1.4
0.4 - 2 >=0.4.0 <=2.0.0
X-Ranges

Les syntaxes X, x ou * peuvent être utilisées pour laisser non-spécifiée une partie de la version.

Intervalle de version Intervalle de version étendu
* >=0.0.0 (n’importe quelle version)
2.x >=2.0.0 <3.0.0 (doit vérifier la version majeure)
3.1.x >=3.1.0 <3.2.0 (doit vérifier les parties majeure et mineure de la version)

Si une partie de la version est manquante, la version est considérée comme étant un x-range.

Intervalle de version Intervalle de version étendu
`` (chaîne vide) * ou >=0.0.0
2 2.x.x ou >=2.0.0 <3.0.0
3.1 3.1.x ou >=3.1.0 <3.2.0
Intervalles avec tilde

En utilisant ~ avec une version mineure spécifiée, cela autorise la partie patch à changer. En utilisant ~ avec uniquement la partie majeure spécifiée, cel autorise la partie mineure à changer.

Intervalle de version Intervalle de version étendu
~3.1.4 >=3.1.4 <3.2.0
~3.1 3.1.x ou >=3.1.0 <3.2.0
~3 3.x ou >=3.0.0 <4.0.0

Remarque : spécifier une pré-release avec un intervalle avec un tilde ne validera que les pré-releases avec la même version. Par exemple, l’intervalle de version ~3.1.4-beta.2 valide 3.1.4-beta.4 mais pas 3.1.5-beta.2 car la version major.minor.patch est différente.

Intervalles avec accent circonflexe

Cela autorise des changements qui ne modifient pas le premier chiffre non-égal à zéro dans la version. Par exemple le 3 dans 3.1.4 ou le 4 dans 0.4.2.

Intervalle de version Intervalle de version étendu
^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

Remarque : par défaut, quand vous exécutez yarn add [package-name] cela utilisera un intervalle avec un accent circonflexe.

Si une partie de la version est laissée vide, les parties manquantes seront remplacées par des zéros. Cependant, cela autorisera quand même à ce que cette partie change.

Intervalle de version Intervalle de version étendu
^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

Ressources complémentaires

← Types de dépendances Résolutions de dépendance sélectives →