Qu'est-ce que le Semantic Versioning ?

Vous est-il déjà arrivé de commencer un projet, de lui attribuer un numéro de version, disons 0.0.1 et de ne pas savoir comment le faire évoluer par la suite ?

Nous sommes habitués à voir passer de nombreuses mises à jours logicielles, mais que signifie la mise à jour d'une dépendance de la version 15.1.3 à la 15.2.1 ? Que veulent dire ses chiffres ? Sont-il choisis arbitrairement ou on-t'il chacun une signification particulière ?

Bienvenue dans le monde du "Semantic Versioning", aussi appelé "SemVer", et de ses bonnes pratiques.

SemVer

L'objectif du Semantic Versioning est de donner un numéro unique à chaque nouvelle version d'un logiciel (au sens large) afin de pouvoir identifier ce dernier, tout en apportant un maximum d'informations à l'utilisateur sur ses évolutions.

Un identifiant minimal de version qui ressemble à 0.0.1 se lira tout simplement MAJOR.MINOR.PATCH

Major

Le chiffre "MAJOR" est le plus critique, c'est le seul qui indique une évolution de l'API tellement importante que la rétrocompatibilité n'est plus assurée, indiquant donc que cette version ne sera pas forcément compatible avec les version précédentes.

Minor

Ce chiffre permet d'indiquer que des fonctionnalités ont été ajoutées (ou que des fonctionnalités ont été dépréciées) mais que l'API reste compatible avec les anciennes versions.

Patch

Ce dernier indique que des bugs ont été corrigés mais que la rétro-compatibilité est assurée.

Identifieurs et métadonnées

Il est aussi possible d'ajouter des informations supplémentaires au code de la version, en ajoutant des identifieurs pour identifier la version actuelle comme étant une release ou un pre-release par exemple.

On écrira alors : 10.3.6-rc pour "release candidate", mais on pourra aussi trouver des identifieurs comme alpha ou beta, toujours séparé par un tiret (hyphen)

D'autres métadonnées peuvent être ajoutée, comme le numéro de build interne par exemple, mais elles devront toujours être précédées du signe "+", exemple : 10.3.6-rc+1452

Quelques règles à connaitre

Il existe 11 règles à suivre dans la spécification de la version 2.0.0 du Semantic Versionning, je ne vais pas toutes vous les lister ici, mais en voici quelques-unes qui me paraissent importantes :

• Les chiffres MAJOR, MINOR et PATCH doivent être des entiers positifs supérieurs ou égaux à 0 et ne doivent pas contenir de 0 antéposé (comme 01 ou 046).
• Un chiffre MAJOR à 0 indique un développement initial, l'API peut donc changer à tout moment sans être reflétée dans le numéro de version. L'API ne doit pas être considérée comme étant stable.
• Si le chiffre MAJOR est incrémenté, MINOR et PATCH doivent être remis à zéro, il en va de même pour PATCH si MINOR est incrémenté.

A noter que les chiffres doivent toujours être incrémentés (sauf reset pour minor et patch), mais qu'il ne doivent pas forcément être linéaires. Il est possible de passer de la version 1.3.0 à la version 1.5.0 pour indiquer que de nombreuses fonctionnalités ont été ajoutées.

Je vous invite à lire la spécification de SemVer disponible à https://semver.org/ car elle est très bien écrite, accessible et vous y trouverez même une FAQ avec les réponses aux questions pour vous guider dans vos décisions.

Pour conclure, et comme il est expliqué dans la spécification, le Semantic Versioning n'est pas une idée révolutionnaire, et vous optez déjà sûrement pour une convention personnelle proche. Cependant l'utilisation stricte de SemVer est indispensable pour une gestion des dépendances fonctionnelle et robuste.