Un numéro de version n’est pas qu’une étiquette : dans le versionnage sémantique, chacun de ses trois chiffres porte une signification précise, comprise par quiconque intègre une extension dans son propre code. Beaucoup d’extensions maison, pourtant numérotées selon ce format à trois chiffres, n’en respectent pas réellement les règles, ce qui trompe les intégrateurs qui leur font confiance.
Le principe du versionnage sémantique associe le premier chiffre (majeur) à un changement incompatible avec les versions précédentes, le deuxième (mineur) à l’ajout d’une fonctionnalité sans rien casser, et le troisième (correctif) à une réparation de bug sans changement de comportement attendu. Une extension qui incrémente son chiffre mineur tout en modifiant la signature d’une fonction publique trahit ce contrat implicite, même si son numéro de version « ressemble » à une évolution mineure.
Ce que le contrat semver garantit réellement
Un intégrateur qui utilise une extension dans son propre code — via un hook exposé, une fonction publique, ou un filtre documenté — s’appuie sur cette convention pour décider s’il peut mettre à jour sans relire tout son propre code. Passer de 2.3.1 à 2.4.0 devrait pouvoir se faire sans surveillance particulière. Passer de 2.3.1 à 3.0.0 devrait, au contraire, déclencher une relecture attentive du changelog avant toute mise à jour en production.
Exemples concrets de changements mal classés
| Changement effectué | Classement correct | Erreur fréquente observée |
|---|---|---|
| Renommer un paramètre d’un filtre exposé | Majeur | Classé en mineur ou en correctif |
| Ajouter un nouveau filtre optionnel | Mineur | Souvent correctement classé |
| Corriger un calcul de date erroné | Correctif, sauf si le comportement corrigé était largement utilisé tel quel | Classé en mineur sans discussion |
| Changer la valeur de retour d’une fonction publique | Majeur | Classé en correctif car « c’était un bug » |
Le dernier exemple mérite une attention particulière : corriger un comportement objectivement erroné reste, du point de vue de l’intégrateur qui s’était construit autour de ce comportement, un changement cassant. La bonne pratique consiste alors à documenter clairement ce cas dans le changelog, même en version de correctif, plutôt que de prétendre qu’aucune adaptation n’est nécessaire.
Une règle simple à appliquer avant chaque publication
Avant de choisir le prochain numéro de version, une seule question suffit : un intégrateur qui a écrit du code contre la version précédente verra-t-il ce code continuer à fonctionner exactement de la même façon après la mise à jour ? Si la réponse est non, il s’agit d’un changement majeur, quelle que soit la taille apparente de la modification dans le code source.
- Renommer une fonction publique, un filtre ou une action documentée : toujours majeur.
- Modifier la signature d’une fonction publique (ajout, suppression ou réordonnancement de paramètres) : toujours majeur.
- Ajouter un paramètre optionnel à la fin d’une signature existante, sans changer le comportement par défaut : mineur.
- Corriger un bug sans changer aucune interface publique : correctif.
Documenter les exceptions plutôt que les cacher
Aucune règle ne couvre parfaitement chaque cas réel. Quand une correction de bug modifie un comportement auquel des intégrateurs s’étaient adaptés, la transparence reste la meilleure option : signaler explicitement, dans le changelog, qu’une version de correctif contient exceptionnellement un changement de comportement notable, avec la raison précise de ce choix.
Un numéro de version qui ment sur son propre contenu coûte plus cher, à terme, que le temps économisé à ne pas y réfléchir avant publication.
Notre verdict
Le versionnage sémantique n’est pas une contrainte administrative : c’est un langage commun entre une extension et ceux qui l’intègrent. Le respecter rigoureusement, y compris quand cela impose de classer une simple correction comme un changement majeur, protège la confiance qu’un intégrateur accorde à chaque mise à jour. C’est un effort de discipline modeste, largement compensé par le temps de support qu’il évite.
