Versionnement sémantique Le système de numérotation que votre installation npm repose sur

Votre build a échoué. Cela fonctionnait vendredi. npm install lundi, j'ai intégré react-query@5 et maintenant, la moitié de vos hooks est disparue. Vous regardez une trace d'erreur qui n'était pas là avant, et quelque part, un changelog s'empile.

C'est une histoire de semver. Spécifiquement, c'est votre faute.

Ce que signifient les trois nombres

MAJOR.MINOR.PATCH — c'est tout. Trois cases, trois règles :

• PATCHER (1.2.3 → 1.2.4) : Correction d'un bug. Rien dans votre code n'a besoin de changer. Vous obtenez simplement moins de comportements défectueux.
• — des nouvelles fonctionnalités, compatibles avec les versions antérieures. Votre code existant devrait continuer à fonctionner. (1.2.3 → 1.3.0) : Une nouvelle fonction a été ajoutée, compatible vers l'arrière. Vous n'avez pas besoin de l'utiliser, mais elle est là.
• — des changements brisants. Une mise à jour vers une version majeure peut nécessiter une modification de votre code. (1.2.3 → 2.0.0) : Quelque chose a été cassé. Une fonction a été renommée, supprimée ou son signature a changé. L'ancienne API est disparue ou fonctionne différemment.

Le mot clé dans les trois cas est compatible vers l'arrière. MINOR et PATCH sont des promesses : « nous n'avons pas cassé ce que vous utilisiez déjà ». MAJOR est une alerte : « nous l'avons fait. »

Quand un mainteneur augmente MAJOR et que vous ne l'avez pas remarqué parce que vous avez fixé ^1.0.0 dans package.json et que le fichier de verrouillage était obsolète — c'est à vous. La spécification fonctionnait exactement comme conçue.

Le contrat social de semver

Le semver est une convention, pas une loi. Les packages peuvent affirmer de suivre ce système et ensuite livrer une mise à jour MINOR avec des changements cassants. Dans ce cas, c'est une mauvaise foi du mainteneur. Mais quand un package augmente correctement MAJOR pour signaler une rupture et que vous l'installez sans y faire attention — c'est vous qui avez cassé votre propre build.

C'est pourquoi existent les changelogs. Une CHANGELOG.md entrée qui dit « Supprimé la version dépréciée v1Api — utilisez v2Api au lieu » est le mainteneur qui tient son côté. Ne pas la lire, c'est vous qui ignorez votre propre obligation. Le changelog est une lecture de deux minutes. La session de débogage qu'il évite n'est pas.

^ vs ~ — les mécanismes réels

Dans package.json, ^ (caret) et ~ (tilde) définissent des gammes de versions. Elles ressemblent et se comportent très différemment.

Caret (^) : Permet tout ce qui ne monte pas au MAJOR. C'est la valeur par défaut de npm quand vous exécutez npm install some-package.

• ^1.2.3 se résout à >=1.2.3 <2.0.0
• ^0.2.3 se résout à >=0.2.3 <0.3.0 — cas spécial : 0.x considère les MINOR comme cassantes
• ^0.0.3 se résout à >=0.0.3 <0.0.4 — 0.0.x fixe exactement, sans marge de manœuvre

Tilde (~) : Permet uniquement les mises à jour PATCH, dans la MINOR spécifiée.

• ~1.2.3 se résout à >=1.2.3 <1.3.0
• ~1.2 se résout à >=1.2.0 <1.3.0 — même que ~1.2.0
• ~1 se résout à >=1.0.0 <2.0.0 — équivalent à ^1.0.0 à ce stade

Exemples de gammes de versions

Le * La gamme est une stratégie de versionnage « crois-moi, mec ». Vous ne fixez rien. Si un package livre une API entièrement réécrite, vous l'obtenez à la prochaine v9.0.0 avec un cache propre. Utilisez-la uniquement dans les applications de niveau supérieur qui ne sont jamais dépendantes d'autres packages — et même alors, seulement si la reproductibilité n'est vraiment pas importante pour vous (elle l'est). npm install avec un cache propre. Utilisez-le uniquement dans les applications de niveau supérieur qui ne sont jamais dépendantes d'autres paquets — et même alors, uniquement si la reproductibilité n'est vraiment pas importante pour vous (elle l'est).

Les identifiants de version préliminaire

Avant une version stable, les auteurs marquent les versions avec un label de version préliminaire :

• 1.0.0-alpha.1 — précoce, instable, l'API est probablement encore en changement
• 1.0.0-beta.2 — fonctionnelle, toujours en test, attendez des irrégularités
• 1.0.0-rc.1 — candidat à la sortie, devrait être utilisable en production sauf si quelque chose apparaît lors du test final

Les versions préliminaires se classent en dessous de la version stable : 1.0.0-alpha.1 < 1.0.0Et cruciallement, ^1.0.0 installera pas — les versions préliminaires ne correspondent que si vous les spécifiez explicitement dans votre gamme. C'est ce comportement qui empêche que vous optiez accidentellement pour une version alpha alors que vous vouliez suivre les versions stables. 2.0.0-beta.1 — les versions préliminaires ne correspondent que si vous les spécifiez explicitement dans votre plage. C'est ce comportement qui vous empêche d'opter accidentellement pour une version alpha lorsque vous vouliez suivre des versions stables.

Si vous consommez un package qui ne dispose que de versions préliminaires, fixez la chaîne de version complète : "some-package": "1.0.0-beta.2". N'utilisez pas ^ ou ~ avec des versions préliminaires sauf si vous savez que le mainteneur les traite avec soin — la plupart ne le font pas.

Vérifier une gamme avant de la commiter

Avant de fixer une gamme de version dans package.json, il est utile de confirmer ce que vous acceptez d'installer. Le Calculateur de version semver prend une gamme de version et une liste de versions candidates et vous montre lesquelles correspondent — utile quand vous êtes incertain sur le fait que ~2.3 inclut une version spécifique que vous avez besoin, ou quand vous examinez une PR et que la gamme semble erronée.

Les trois modes d'échec

La plupart des échecs liés au semver suivent l'un des trois modèles suivants :

1. ^ + Augmentation MAJOR + fichier de verrouillage supprimé : Vous avez fixé ^1.0.0, le mainteneur a livré 2.0.0, le fichier de verrouillage a été supprimé ou n'a jamais été commité, CI installe 2.0.0. Solution : commitez votre fichier de verrouillage. Pour chaque projet. Aucune exception.
2. * dans une bibliothèque que vous publiez : Vous êtes un auteur de bibliothèque qui avez utilisé * pour une dépendance. Chaque utilisateur descendant de votre package hérite de votre wild card. Vous avez rendu le graphe de dépendance de leurs applications votre problème. Solution : utilisez des gammes explicites dans tout ce que vous publiez sur npm.
3. Version préliminaire sans fichier de verrouillage : Une gamme loose a intégré 1.0.0-alpha.3, l'API a changé de alpha.1, rien ne fonctionne. Solution : fixez explicitement les versions préliminaires et — dites-le avec moi — commitez le fichier de verrouillage.

Lisez le changelog

Quand une version MAJOR est livrée pour tout dans votre arbre de dépendances, passez deux minutes sur le changelog. Les auteurs l'ont écrit pour que vous n'ayez pas à déduire la rupture à partir d'une trace d'erreur à 3h du matin.

Si un package livre des changements cassants sous une mise à jour MINOR sans changelog — c'est une mauvaise foi. Faites un ticket. Le mentionnez publiquement. Mais si la version MAJOR était clairement présente, que la documentation de migration était détaillée, et que vous l'avez installée sans y jeter un œil : le logiciel a exactement fait ce que vous lui avez demandé. Le contrat était écrit dans trois chiffres. Vous n'avez simplement pas lu.

Vous aimerez peut-être aussi

Nouveau

GitHub Actions Secrets: How to Inject Config Without Hardcoding Anything Embarrassing

En savoir plus "

Mis à jour le Juin 23, 2026

Nouveau

Database Connection Pooling: Why Your App Crashes at 100 Users When Queries Take 10ms

En savoir plus "

Mis à jour le Juin 22, 2026

Nouveau

Git Interactive Rebase: Squash, Reorder, and Rewrite Commits Before They Hit main

En savoir plus "

Mis à jour le Juin 21, 2026

Nouveau

CORS Expliqué : Pourquoi votre requête fonctionne avec curl mais échoue dans le navigateur

En savoir plus "

Mis à jour le Juin 20, 2026