Versionnement sémantique Ce que signifient les nombres dans votre package.json

Chaque projet JavaScript possède package.json. La plupart des développeurs ont tapé npm install some-library des centaines de fois sans faire attention au sens du numéro de version. Mais si vous demandez à quelqu'un ce que ^1.2.3 permet — c’est-à-dire, quelles versions npm va accepter — vous obtenez souvent un haussement d’épaules.

Ce n’est pas une lacune négligeable. Une plage de version mal comprise est la cause d’un problème de pipeline CI sur une machine fraîche qui fonctionnait parfaitement pendant des mois. Comprendre le contrat derrière ces chiffres est l’un de ces éléments à faible coût, à forte récompense, qui distingue les développeurs qui résolvent les problèmes de version en quelques minutes des autres qui y passent des heures. npm install Le contrat MAJOR.MINOR.PATCH

Le versionnement sémantique (semver) est un format à trois chiffres :

. Chaque position porte une promesse précise sur ce qui a changé : MAJOR.MINOR.PATCHMAJOR

• — des changements brisants. Une mise à jour vers une version majeure peut nécessiter une modification de votre code. MINOR
• — des nouvelles fonctionnalités, compatibles avec les versions antérieures. Votre code existant devrait continuer à fonctionner. — des corrections de bugs uniquement. Il est possible de mettre à jour sans changement d’API.
• PATCHER C’est le

contrat sous lequel les paquets sont publiés. Passer de doit ajouter de nouvelles fonctionnalités sans briser le comportement existant. Passer à 2.3.1 à 2.4.0 est votre avertissement : lisez le changelog avant de mettre à jour. 3.0.0 En pratique, les mainteneurs peuvent parfois commettre une erreur et glisser un changement brisant dans une mise à jour mineure. Le versionnement sémantique ne se force pas lui-même — c’est une convention. Mais il vous donne un cadre pour raisonner sur les risques, et c’est ce sur quoi sont basés tous les opérateurs de plage.

Qu’est-ce qu’un changement brisant ?

Un changement brisant est tout ce qui oblige les consommateurs à modifier leur code :

Suppression ou renommage d’une fonction, d’une classe ou d’une constante exportée

• Changement de la signature d’une fonction — suppression de paramètres, ajout de paramètres obligatoires ou changement des types de retour
• Changement du comportement observable de manière à ce que le code appelant se comporte maintenant incorrectement
• Changement du format d’un fichier de configuration de manière incompatible
• Ajout d’un nouveau paramètre optionnel ? C’est MINOR. Ajout d’une nouvelle exportation ? MINOR. Correction d’un bug que quelqu’un utilisait accidentellement comme une fonctionnalité ? C’est une question de jugement, mais selon la convention, c’est PATCH. Si vous êtes en doute, augmentez MINOR et documentez-le clairement.

Les opérateurs de plage dans package.json

Ouvrez n’importe quel

et vous verrez des chaînes de version comme package.json . Ce ne sont pas des points fixes — ce sont des "^4.17.21" ou "~1.0.4"plages qui indiquent à npm ou yarn quelles versions sont acceptables lors de la résolution de votre arbre de dépendances. Caret ^ — Compatible avec la version

Le caret est l’opérateur par défaut lorsque vous exécutez

. Cela signifie : « acceptez toute version qui ne change pas le chiffre non nul de gauche ». En pratique, pour les paquets stables, cela signifie même version majeure, toute version mineure ou patch : npm installLe comportement de zéro majeur est intentionnel. Les paquets à

^1.2.3  →  >=1.2.3 <2.0.0   (any 1.x.x at or above 1.2.3)
^0.2.3  →  >=0.2.3 <0.3.0   (zero-major: pins to minor)
^0.0.3  →  >=0.0.3 <0.0.4   (zero-zero: pins to exact patch)

indiquent une « API instable » — toute version mineure pourrait briser les choses. Le caret respecte ce signal et devient beaucoup plus conservateur. 0.x.x Tilde ~ — Mises à jour au niveau patch uniquement

La tilde est plus conservatrice. Elle accepte de nouvelles mises à jour de patch, mais ne touche pas la version mineure :

Utilisez

~1.2.3  →  >=1.2.3 <1.3.0   (any 1.2.x at or above 1.2.3)
~1.2    →  >=1.2.0 <1.3.0
~1      →  >=1.0.0 <2.0.0   (when only major given — same as ^1)

lorsque vous souhaitez des correctifs de bugs, mais que vous n’êtes pas confiant que la bibliothèque respecte le versionnement sémantique pour les mises à jour mineures, ou lorsque votre code est étroitement couplé à une surface d’API spécifique et qu’une nouvelle version de fonctionnalité historiquement apporte des changements subtils de comportement. ~ Opérateurs de comparaison : >=,

Vous pouvez écrire des plages arbitraires en utilisant des opérateurs de comparaison. Un espace entre deux contraintes signifie ET : <=, >

Ces plages apparaissent le plus souvent dans

>=1.2.0           # at least 1.2.0, no upper bound
>=1.2.0 <2.0.0   # same as ^1.2.0 (explicit AND)
>1.2.0 <=1.5.0   # between these values, exclusive/inclusive

où une bibliothèque indique quelque chose comme peerDependenciespour déclarer les versions d’hôte compatibles. "react": ">=16.8.0 <19.0.0" Les étoiles et x

Les formes avec étoile sont principalement destinées à la lisibilité de la documentation ; npm les traite comme équivalent au caret/tilde avec une base de zéro :

— toute version. Ne l’utilisez pas en production.

• * ou "" — toute version 1.x.x (équivalent à
• 1.x ou 1.x.x — toute version 1.2.x (équivalent à ^1.0.0)
• 1.2.x Versions préliminaires ~1.2.0)

Les versions préliminaires ont l’air de

. Elles sont considérées comme 1.0.0-alpha.1, 2.0.0-beta.3, ou 3.1.0-rc.1inférieures à la version de sortie ayant les mêmes chiffres — Critiquement, 1.0.0-alpha.1 < 1.0.0.

les opérateurs de plage ne prennent pas automatiquement en compte les versions préliminaires . Une plage ne tirera pasmême si elle satisfait techniquement ^1.0.0 . Vous devez l’opter explicitement : 1.1.0-beta.1C’est une sécurité intentionnelle. Vous n’auriez presque jamais envie que votre CI prenne automatiquement une version préliminaire d’une dépendance parce qu’elle satisfait une plage de version. Si vous testez des versions préliminaires, faites-le de manière volontaire. >=1.0.0 <2.0.0Les fichiers de verrouillage ne sont pas optionnels

npm install some-library@next
npm install some-library@2.0.0-beta.3

Lorsque npm résout votre -alpha plage, il choisit la version la plus élevée disponible à ce moment-là

. Exécutez

aujourd’hui et vous obtenez ^1.2.3 . Exécutez-le six mois plus tard et vous pourriez obtenir . Même, arbre de dépendances différent, comportement potentiellement différent. npm install C’est ce que les fichiers de verrouillage résolvent. 1.5.0(npm) et 1.9.2(yarn) enregistrent la version exacte installée pour chaque dépendance — directe et transitive. Lorsque quelqu’un clone votre dépôt et exécute package.json, ils obtiennent un arbre identique.

Commitez votre fichier de verrouillage. Toujours. package-lock.json Ne le commettez pas : cela signifie que yarn.lock des développeurs peuvent exécuter des versions différentes de dépendances sans le savoir npm ciVotre environnement CI peut se dériver silencieusement de votre environnement local

Une mise à jour d’une dépendance transitive peut changer le comportement en production sans changement visible dans votre La principale exception : les bibliothèques publiées (et non les applications) laissent généralement les fichiers de verrouillage non commis afin que les consommateurs puissent résoudre leur propre arbre de dépendances. Si vous développez une application, il n’y a pas de bonnes raisons de laisser le fichier de verrouillage hors contrôle source.

• "latest" dans package.json est toujours une erreur
• Parfois, vous verrez cela dans un
• Ne le faites pas. git diff

correspond à la version actuellement marquée

sur npm — elle change chaque fois que le mainteneur publie une nouvelle version. Un nouveau

sur une machine nouvelle pourrait tirer une version majeure complètement différente de celle que vous avez testée. package.json:

"dependencies": {
  "some-package": "latest"
}

Cela peut fonctionner parfaitement pendant des semaines, puis briser silencieusement lorsqu’une nouvelle version majeure est publiée. Pire encore, cela rend "latest" inutilisable comme spécification reproductible — vous ne pouvez pas raisonner sur la version que vous exécutez sans vérifier manuellement npm. Fixez une version réelle et laissez le caret gérer les mises à jour sûres dans cette plage. latest Vérifiez si une version satisfait une plage npm install Si vous n’êtes pas sûr que la version correspond à une plage donnée — surtout avec des paquets à zéro majeur ou des expressions composées inhabituelles — l’outil

sur iotools.cloud vous donne une réponse immédiate. Entrez la plage ( package.json ) et la version candidate, et il vous indique si la contrainte est satisfaite.

Cela est utile lors de la révision des demandes de mise à jour de dépendance, pour déboguer pourquoi

a été résolu à une version inattendue, ou pour vérifier une plage Calculateur de versions Semver et testeur de gammes avant de publier une bibliothèque.^1.2.3, ~0.5.0, >=2.0.0 <3.0.0Opérateur

Résout à npm install 1.2.0 ou supérieur, sans limite peerDependencies Toute version (à éviter)

Référence Rapide

Toute version 1.2.x	Exemple	exacte
^	^1.2.3	>=1.2.3 <2.0.0
~	~1.2.3	>=1.2.3 <1.3.0
>=	>=1.2.0	Exactement 1.2.3
*	*	Versionnement sémantique : Ce que signifient les nombres dans votre package.json 2
x	1.2.x	Versionnement sémantique : Ce que signifient les nombres dans votre package.json 1
Chaque package.json possède des chaînes de version, mais la plupart des développeurs se contentent de croire au caret sans comprendre ce qu’il permet. Ce guide explique le contrat MAJOR.MINOR.PATCH et exactement quelles mises à jour ^, ~, >= et * seront acceptées.	1.2.3	Exactement 1.2.3

Vous aimerez peut-être aussi