Parser SemVer

Qu’est-ce que le versionnage semantique ?

Le versionnage semantique (SemVer) est une convention de versionnage qui attribue une signification a chaque numero d’une chaine de version. Au lieu de numeros de version arbitraires, SemVer encode la nature des changements directement dans la version — permettant aux humains comme aux machines de comprendre ce qui a change entre deux publications.

L’idee centrale est capturee en une seule phrase de la specification : “Etant donne un numero de version MAJEUR.MINEUR.CORRECTIF, incrementez la version MAJEURE lorsque vous effectuez des modifications incompatibles de l’API, la version MINEURE lorsque vous ajoutez des fonctionnalites de maniere retrocompatible, et la version CORRECTIVE lorsque vous apportez des corrections de bogues retrocompatibles.”

SemVer est le fondement de la gestion moderne des dependances. Les gestionnaires de paquets comme npm, Cargo, Composer et NuGet s’appuient sur SemVer pour resoudre automatiquement les versions compatibles, empechant les applications de recuperer accidentellement des changements incompatibles tout en continuant a recevoir les corrections de bogues et les nouvelles fonctionnalites.

Les trois numeros expliques

Chaque version semantique se compose de trois entiers non negatifs separes par des points :

MAJEUR.MINEUR.CORRECTIF

Composant	Quand incrementer	Exemple
MAJEUR	Changements incompatibles de l’API publique	1.0.0 vers 2.0.0 — fonction renommee, endpoint supprime
MINEUR	Nouvelles fonctionnalites retrocompatibles	1.0.0 vers 1.1.0 — nouvel endpoint d’API ajoute
CORRECTIF	Corrections de bogues retrocompatibles	1.0.0 vers 1.0.1 — erreur de calcul corrigee

Lorsque vous incrementez un numero de priorite superieure, tous les numeros inferieurs sont remis a zero. Incrementer MAJEUR remet MINEUR et CORRECTIF a zero. Incrementer MINEUR remet uniquement CORRECTIF a zero.

Avant	Type de changement	Apres	Explication
1.4.2	Changement incompatible	2.0.0	Increment MAJEUR, MINEUR et CORRECTIF remis a zero
1.4.2	Nouvelle fonctionnalite	1.5.0	Increment MINEUR, CORRECTIF remis a zero
1.4.2	Correction de bogue	1.4.3	Increment CORRECTIF uniquement

Pre-release et metadonnees de build

SemVer prend en charge deux extensions optionnelles ajoutees au noyau MAJEUR.MINEUR.CORRECTIF :

Identifiants de pre-release

Une version de pre-release est indiquee en ajoutant un tiret et une serie d’identifiants separes par des points apres la version CORRECTIVE :

1.0.0-alpha
1.0.0-alpha.1
1.0.0-beta.2
1.0.0-rc.1

Les versions de pre-release indiquent que la version est instable et peut ne pas satisfaire les exigences de compatibilite de la version normale. Elles ont une precedence inferieure a la version normale associee : 1.0.0-alpha < 1.0.0.

Les identifiants de pre-release sont compares de gauche a droite. Les identifiants numeriques sont compares en tant qu’entiers ; les identifiants alphanumeriques sont compares lexicalement. Les identifiants numeriques ont toujours une precedence inferieure aux identifiants alphanumeriques. Cela signifie 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-rc.1.

Metadonnees de build

Les metadonnees de build sont ajoutees a l’aide d’un signe plus apres la version (ou apres le tag de pre-release s’il est present) :

1.0.0+20240315
1.0.0-beta.1+build.456

Les metadonnees de build sont completement ignorees lors de la determination de la precedence des versions. Deux versions qui ne different que par leurs metadonnees de build sont considerees comme egales : 1.0.0+build.1 == 1.0.0+build.2. Les metadonnees de build sont generalement utilisees pour enregistrer des informations comme les hachages de commit, les horodatages de build ou les identifiants de pipeline CI.

Version 0.x.y — Developpement initial

La specification SemVer prevoit une exception speciale pour les versions avec un MAJEUR de 0 :

La version majeure zero (0.y.z) est destinee au developpement initial. Tout PEUT changer a tout moment. L’API publique NE DEVRAIT PAS etre consideree comme stable.

Cela signifie que pendant la phase 0.x.y, il n’y a aucune garantie. Un passage de 0.2.3 a 0.3.0 peut inclure des changements incompatibles. Un passage de 0.2.3 a 0.2.4 peut introduire de nouvelles fonctionnalites. Les regles normales ne prennent pleinement effet qu’une fois le projet arrive a 1.0.0.

Cette distinction est importante pour la gestion des dependances. Les gestionnaires de paquets traitent les plages 0.x.y avec plus de prudence. Par exemple, dans npm, ^0.2.3 se resout en >=0.2.3 <0.3.0 plutot qu’en >=0.2.3 <1.0.0 — l’operateur caret devient plus strict pour tenir compte de l’instabilite des versions pre-1.0.

Regles de precedence des versions

SemVer definit un ordre clair pour les versions :

1. MAJEUR, MINEUR, CORRECTIF sont compares numeriquement de gauche a droite : 1.9.0 < 1.10.0 < 2.0.0
2. Les versions pre-release ont une precedence inferieure a la version normale : 1.0.0-alpha < 1.0.0
3. Les identifiants de pre-release sont compares de gauche a droite : numerique < alphanumerique, numerique par valeur, alphanumerique lexicalement
4. Les metadonnees de build sont entierement ignorees pour la precedence

Cet ordonnancement permet aux gestionnaires de paquets de trier, comparer et selectionner automatiquement la version la plus appropriee.

Cas d’utilisation courants

• npm / Node.js : Chaque paquet npm utilise SemVer. Le champ dependencies du package.json attend des plages SemVer (^1.2.3, ~1.2.3)
• Rust / Cargo : Cargo applique strictement SemVer pour tous les crates publies sur crates.io
• PHP / Composer : Composer utilise SemVer pour la resolution des dependances des paquets PHP
• Versionnage d’API : Les API REST et GraphQL utilisent les versions MAJEURES (v1, v2) pour signaler les changements incompatibles des endpoints
• Outils en ligne de commande : Les outils CLI suivent SemVer pour communiquer la retrocompatibilite des options, sorties et comportements
• Bibliotheques et frameworks : React, Vue, Angular, Django, Rails — tous utilisent SemVer pour guider les decisions de mise a jour