Étant donné un numéro de version MAJEUR.MINEUR.CORRECTIF, il faut incrémenter :
Des libellés supplémentaires peuvent être ajoutés pour les versions de pré-livraison et pourdes méta-données de construction sous forme d’extension du format MAJEURE.MINEURE.CORRECTIF.
Dans le monde de la gestion des logiciels, il existe un endroit redouté appelé« l’enfer des dépendances » (de l’anglaisdependency hell). Plus votre système sedéveloppe et plus vous intégrez de composants dans votre logiciel, plus vous êtessusceptible de vous trouver un jour dans cet abîme de désespoir.
Dans les systèmes comportant de nombreuses dépendances, publier une nouvelleversion d’un composant peut vite devenir un cauchemar. Si les règles dedépendance sont trop strictes, vous risquez de verrouiller vos versions(incapacité de mettre à jour un composant sans avoir à publier une nouvelleversion de chaque composant qui en dépend). Si les règles de dépendances sonttrop lâches, vous allez inévitablement subir la promiscuité de version (supposerune compatibilité avec plus de futures versions que raisonnable). L’enfer desdépendances est l’endroit où vous vous trouvez lorsque vous êtes bloqué dansune version et/ou qu’une incompatibilité de version vous empêche d’avancersans risque dans votre projet.
Comme solution à ce problème, je propose un ensemble de règles et d’exigencessimples qui dictent la façon dont les numéros de version sont attribués etincrémentés. Ces règles sont basées mais pas nécessairement limitées à despratiques très répandues aussi bien dans les domaines du logiciel privé que dulogiciel libre. Pour que ce système fonctionne, vous devez d’abord déclarer une APIpublique. Il peut s’agir d’un document ou de règles imposées par le code lui-même. Quoi qu’il en soit, il est important que cette API soit claire et précise.Une fois celle-ci prête, vous communiquez ses modifications par des incrémentationssuccessives de son numéro de version. Considérons le format de version X.Y.Zoù X, Y et Z identifient la version (Majeure.Mineure.Corrective). Les corrections quin’affectent pas l’API incrémentent le dernier identifiant qui est l’identifiant deversion de correction. Lors d’ajouts ou de modifications rétrocompatibles de l’API,il faut incrémenter l’identifiant de version mineure. Enfin, pour des modificationsnon rétrocompatibles, il faut incrémenter l’identifiant de version majeure.
J’appelle ce système « gestion sémantique de version ». Avec ce système, les numéros deversion, et la façon dont ils changent, donnent du sens au code sous-jacent et à cequi a été modifié d’une version à l’autre.
Les mots clés “DOIT”, “NE DOIT PAS”, “OBLIGATOIRE”, “DEVRA”, “NE DEVRA PAS”,“DEVRAIT”, “NE DEVRAIT PAS”, “RECOMMANDÉ”, “PEUT”, et “OPTIONNEL” dans cedocument doivent être interprétés comme décrit dans laRFC 2119.
Tout logiciel utilisant la gestion sémantique de version DOIT déclarer une APIpublique. 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.
Un numéro de version standard DOIT prendre la forme X.Y.Z où X, Y et Z sontdes entiers non négatifs et NE DOIVENT PAS être préfixés par des zéros. Xreprésente l’identifiant de version majeure, Y représente l’identifiant de version mineureet Z l’identifiant de version de correction. Chaque élément DOIT s’incrémenternumériquement.Exemple : 1.9.0 -> 1.10.0 -> 1.11.0.
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.
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.
La version 1.0.0 définit l’API publique. La façon dont le numéro de versionest incrémenté après cette publication est dépendante de cette API publique etde ses évolutions.
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 correctionest définie comme un changement interne qui corrige un comportement incorrect.
L’identifiant de version mineure Y (x.Y.z | x > 0) DOIT être incrémenté si denouvelles fonctionnalités rétrocompatibles sont introduites dans l’APIpublique. Il DOIT être incrémenté si une fonctionnalité de l’API publiqueest marquée comme obsolète. Il PEUT être incrémenté si de nouvelles fonctionnalitésou améliorations substantielles sont introduites dans le code privé. Il PEUTinclure dans le même temps des corrections. L’identifiant de version de correctionDOIT être remis à zéro lorsque l’identifiant de version mineure est incrémenté.
L’identifiant de version majeur X (X.y.z | X > 0) DOIT être incrémenté si deschangements non rétrocompatibles sont introduits dans l’API publique. Cela PEUTinclure dans le même temps des changements mineurs et des corrections. Lesidentifiants de version mineure et de correction DOIVENT être remis à zéro quandl’identifiant de version majeure est incrémenté.
Une version de pré-livraison PEUT être notée par l’ajout d’un trait d’union et d’unesérie d’identifiants séparés par des points suivant immédiatement l’identifiant de versionde correction. Les identifiants DOIVENT être composés uniquement de caractèresalphanumé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 depré-livraison < version normale). Une version de pré-livraison indique que la versionn’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.
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édiatementl’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èrentseulement 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.
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 entremajeures, 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 comparaisonde chacun de ces identifiants dans l’ordre : majeur, mineur et correctif. Cesidentifiants 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 moinsprioritaire 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 deversion majeure, mineure et de correction DOIT être déterminée en comparant chaqueidentifiant séparé par un point de la gauche vers la droite jusqu’à ce qu’unedifférence soit trouvée, comme suit : les identifiants composés uniquement dechiffres sont comparés numériquement et les identifiants contenant des lettresou des traits d’union sont comparés dans l’ordre ASCII. Les identifiants numériquessont toujours moins prioritaires que les identifiants non numériques (identifiantsnumériques < identifiants non-numériques). Un ensemble de champs plus long estprioritaire par rapport à un ensemble de champs plus court si tous les identifiantspré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.
Il ne s’agit pas d’une idée nouvelle ou révolutionnaire. En fait, vous faitesprobablement déjà quelque chose d’approchant. Et le problème vient du fait que« quelque chose de proche » n’est pas suffisant. Sans conformité avec une méthodeformelle, les numéros de version deviennent inutilisables pour la gestion devos dépendances. En donnant un nom et une définition claire aux idées exposéesci-dessus, il devient facile de communiquer vos intentions aux utilisateursde votre logiciel. Une fois que vos intentions sont claires, une spécificationsouple (mais pas « trop » souple) des dépendances peut être réalisée.
Un exemple simple permet de montrer comment la gestion sémantique de version peutfaire de l’enfer des dépendances, une chose du passé. Considérons une bibliothèqueappelée « CamionDePompier ». Elle nécessite un composant appelé « Échelle » dont laversion est gérée sémantiquement. Lorsque la librairie CamionDePompier est créée,Échelle en est à sa version 3.1.0. Et puisque CamionDePompier utilise des fonctionnalitésqui ont été introduites en 3.1.0, vous pouvez spécifier, sans courir le moindre risque,une dépendance vers Échelle plus grande ou égale à 3.1.0 mais inférieure à 4.0.0.Maintenant, lorsque les versions 3.1.1 et 3.2.0 de Échelle seront disponibles, vouspourrez les publier dans votre système de gestion de dépendances en sachant qu’ellesseront compatibles avec les logiciels existants qui en dépendent.
En tant que développeur responsable, bien entendu, vous voudrez vérifier que toutemise à jour de composant fonctionne comme annoncée. Dans la réalité, les choses nesont pas forcément toujours très cohérentes ; il n’y a donc rien d’autre à faire quede rester vigilant. Ce que vous pouvez cependant faire est de laisser la gestionsémantique de version vous fournir une manière saine de publier et mettre à jour voscomposants et ainsi ne pas avoir besoin de déployer de nouvelles versions de vossous-composants vous permettant ainsi d’économiser du temps et du souci.
Si tout cela vous semble intéressant, tout ce que vous avez à faire pour commencerà utiliser la gestion sémantique de version est de déclarer que vous le faiteset d’en suivre les règles. Ajoutez ensuite un lien vers ce site web dans votreREADME pour que d’autres puissent en connaître les règles et en bénéficier.
La chose la plus simple à faire est de commencer vos développements avecune version initiale à 0.1.0 puis d’incrémenter l’identifiant de version mineurepour chaque nouvelle publication.
Si votre logiciel est utilisé en environnement de production ou que vous avezune API stable de laquelle des utilisateurs ont commencé à dépendre, vous devriezprobablement déjà être en version 1.0.0. Et si vous vous faites déjà du soucipour la rétro-compatibilité, vous devriez également avoir dépassé la 1.0.0.
La version majeure zéro est faite pour un développementrapide. Si vous changez votre API tous les jours, vous devriez toujours êtreen version 0.y.z ou sur une branche de développement séparée en préparant laprochaine version majeure.
C’est une question de développement responsable et d’anticipation. Les changementsincompatibles ne doivent pas être introduits à la légère dans du logiciel dontbeaucoup de code source dépend. Le coût d’une mise à jour vers une nouvelle versionpeut être important. Le besoin de faire évoluer la version majeure pour publier deschangements non rétrocompatibles signifie que vous aurez mesuré les implications devos modifications et évalué le rapport entre leur coût et leurs bénéfices.
Il est de votre responsabilité en tant que développeur professionnel de documentercorrectement le logiciel qui est destiné à être utilisé par d’autres. Gérer lacomplexité d’un logiciel est un élément extrêmement important pour maintenir sonprojet efficacement. Cela devient difficile à faire quand personne ne sait commentutiliser votre logiciel ou ne connaît les bonnes méthodes à appeler. Sur le longterme, la gestion sémantique de version et les efforts dans la conservation d’uneAPI publique bien définie permettront à tout le monde d’avancer sans problème.
Dès que vous réalisez que vous avez cassé votre gestion sémantique de version,corrigez le problème et publiez une nouvelle version mineure qui rétablit lacompatibilité avec les versions précédentes. Même dans de telles circonstances,il est inacceptable de modifier une version déjà publiée. Mettez à jour ladocumentation en signalant la version défectueuse et informez vos utilisateursde ce problème.
Cela peut être considéré comme compatible dans la mesure où cela n’affecte pas l’APIpublique. Les logiciels qui dépendent des mêmes librairies que votre composantdevraient avoir leur propre spécification de dépendances et l’auteur remarquera ainsitout conflit. Pour déterminer si la modification est de niveau correctif ou mineur,il faut vous poser la question de savoir si vous avez mis à jour vos dépendances pourcorriger un bug ou pour introduire une nouvelle fonctionnalité. Je considèregénéralement l’ajout de nouveau code comme la deuxième option ce qui sous-entendévidemment un incrément de l’identifiant de version mineure.
C’est à vous de décider. Si vous avez une large audience qui sera considérablementaffectée par un retour à ce que l’API publique prévoyait, alors il est peut être préférablede publier une version majeure, même si la livraison pourrait être uniquement considéréecomme un correctif. Souvenez-vous encore que la gestion sémantique de version consisteessentiellement à transmettre du sens dans la façon dont le numéro de version change. Sices changements sont importants pour vos utilisateurs, utilisez les numéros de versionpour les en informer.
Rendre des fonctionnalités obsolètes est une part normale du développement de logicielset cela est souvent nécessaire pour aller de l’avant. Lorsque vous dépréciez une partiede votre API publique, vous devez faire deux choses : (1) mettre à jour la documentationpour informer les utilisateurs du changement, (2) publier une nouvelle version mineureavec la dépréciation en place. Avant que vous ne supprimiez complètement la fonctionnalitédans une nouvelle version majeure, il devrait y avoir au moins une version mineure quicontient la dépréciation pour que les utilisateurs puissent effectuer la transition en douceur.
Non, mais faites preuve de bon sens. Par exemple, un numéro de version de 255 caractèresest probablement excessif. De plus, certains systèmes peuvent imposer leurs propres limitessur cette taille.
La spécification de la gestion sémantique de version est écrite parTomPreston-Werner, inventeur de Gravatars etcofondateur de GitHub.
Si vous souhaitez laisser des commentaires, veuillezouvrir un ticket surGitHub.