Aller au contenu

Spécification de la gestion sémantique de version (SemVer)#

Cette spécification peut être consultée dans son intégralité à son adresse officielle à https://semver.org.

Spécification#

Les mots clés “DOIT”, “NE DOIT PAS”, “OBLIGATOIRE”, “DEVRA”, “NE DEVRA PAS”, “DEVRAIT”, “NE DEVRAIT PAS”, “RECOMMANDÉ”, “PEUT”, et “OPTIONNEL” dans ce document doivent être interprétés comme décrit dans la RFC 2119.

  1. Tout logiciel utilisant la gestion sémantique de version DOIT déclarer une API publique. Cette API peut être déclarée dans le code lui-même ou dans un document. Dans tous les cas, elle doit être précise et claire.
  2. Un numéro de version standard DOIT prendre la forme X.Y.Z où X, Y et Z sont des entiers non négatifs et NE DOIVENT PAS être préfixés par des zéros. X représente l’identifiant de version majeure, Y représente l’identifiant de version mineure et Z l’identifiant de version de correction. Chaque élément DOIT s’incrémenter numériquement. Exemple : 1.9.0 -> 1.10.0 -> 1.11.0.
  3. Une fois qu’un composant est publié, le contenu de sa version NE DOIT PAS être modifié. Toute modification DOIT être publiée dans une nouvelle version.
  4. L’identifiant de version majeure zéro (0.y.z) est destiné au développement initial. Tout ou partie peut être modifié à tout moment. L’API publique ne devrait pas être considérée comme stable.
  5. La version 1.0.0 définit l’API publique. La façon dont le numéro de version est incrémenté après cette publication est dépendante de cette API publique et de ses évolutions.
  6. L’identifiant de version de correction Z (x.y.Z | x > 0) DOIT être incrémenté si seules des corrections rétrocompatibles sont introduites. Une correction est définie comme un changement interne qui corrige un comportement incorrect.
  7. L’identifiant de version mineure Y (x.Y.z | x > 0) DOIT être incrémenté si de nouvelles fonctionnalités rétrocompatibles sont introduites dans l’API publique. Il DOIT être incrémenté si une fonctionnalité de l’API publique est marquée comme obsolète. Il PEUT être incrémenté si de nouvelles fonctionnalités ou améliorations substantielles sont introduites dans le code privé. Il PEUT inclure dans le même temps des corrections. L’identifiant de version de correction DOIT être remis à zéro lorsque l’identifiant de version mineure est incrémenté.
  8. L’identifiant de version majeur X (X.y.z | X > 0) DOIT être incrémenté si des changements non rétrocompatibles sont introduits dans l’API publique. Cela PEUT inclure dans le même temps des changements mineurs et des corrections. Les identifiants de version mineure et de correction DOIVENT être remis à zéro quand l’identifiant de version majeure est incrémenté.
  9. Une version de pré-livraison PEUT être notée par l’ajout d’un trait d’union et d’une série d’identifiants séparés par des points suivant immédiatement l’identifiant de version de correction. Les identifiants DOIVENT être composés uniquement de caractères alphanumériques ASCII et de traits d’union [0-9A-Za-z-]. Les identifiants NE DOIVENT PAS être vides. Les identifiants numériques NE DOIVENT PAS être préfixés par des zéros. Les versions de pré-livraison précèdent la version normale associée (version de pré-livraison < version normale). Une version de pré-livraison indique que la version n’est pas stable et ne satisfait pas forcément les exigences de compatibilité associées à une version normale. Exemples : 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
  10. Les méta-données de construction PEUVENT être notées par l’ajout d’un signe « plus » et d’une série d’identifiants séparés par des points suivant immédiatement l’identifiant de version de correction ou de pré-livraison. Les identifiants DOIVENT être composés uniquement de caractères alphanumériques ASCII et de traits d’union [0-9A-Za-z-]. Les identifiants NE DOIVENT PAS être vides. Les méta-données de construction DEVRAIENT être ignorées dans l’ordre des versions. Autrement dit, deux versions qui diffèrent seulement par leurs informations de construction ont la même priorité. Exemples : 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
  11. La priorité définit la façon dont sont ordonnées les versions entre elles. La priorité DOIT être calculée en séparant les identifiants de versions entre majeures, mineures, de correction et de pré-livraison, en suivant cet ordre (les informations de construction n’entrent pas en compte dans la comparaison). La priorité est déterminée par la première différence apparaissant dans la comparaison de chacun de ces identifiants dans l’ordre : majeur, mineur et correctif. Ces identifiants sont toujours comparés numériquement. Exemple : 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. Lorsque ces identifiants sont identiques, une version de pré-livraison est moins prioritaire qu’une version normale. Exemple : 1.0.0-alpha < 1.0.0. La priorité pour deux versions de pré-livraison ayant les mêmes identifiants de version majeure, mineure et de correction DOIT être déterminée en comparant chaque identifiant séparé par un point de la gauche vers la droite jusqu’à ce qu’une différence soit trouvée, comme suit : les identifiants composés uniquement de chiffres sont comparés numériquement et les identifiants contenant des lettres ou des traits d’union sont comparés dans l’ordre ASCII. Les identifiants numériques sont toujours moins prioritaires que les identifiants non numériques (identifiants numériques < identifiants non-numériques). Un ensemble de champs plus long est prioritaire par rapport à un ensemble de champs plus court si tous les identifiants précédents sont identiques. Exemple : 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.