Compatibilité et dépréciation
Anticipez les évolutions des contrats publics et préparez les migrations de vos extensions.
Sur cette page
Choisir une plage compatible
Après 1.0, une correction compatible augmente PATCH, une fonctionnalité compatible augmente MINOR et une rupture exige MAJOR. Pendant le développement 0.x, une rupture exige une nouvelle version mineure et un guide de migration. Une version publiée ne change plus d’octets.
Le protocole /api/v1 est distinct de la version du produit. Les exports publics du SDK et les formats documentés constituent des contrats ; les chemins internes et composants React de l’administration ne sont pas une API d’extension. Déclarez vos plages requiresCms, requiresNode et dépendances, puis testez les versions annoncées.
Recevoir un avertissement avant un retrait
Une dépréciation indique sa première version, l’alternative, la version de retrait envisagée et la migration. Elle figure dans le changelog et la documentation ; les symboles TypeScript utilisent @deprecated et les contrats HTTP sont signalés dans OpenAPI.
Après 1.0, le contrat reste disponible pendant au moins une version mineure publiée avant son retrait dans une version majeure. En 0.x, une version mineure publiée sépare la dépréciation du retrait dans une version mineure ultérieure. Une annonce seule ne remplit pas ce délai.
Une correction de sécurité peut retirer immédiatement un comportement dangereux. La publication doit expliciter cette exception, les versions concernées et la migration sûre, sans option réactivant la faille.
Éprouver la migration en staging
Le guide de migration donne un exemple avant/après et l’impact sur les permissions, configurations et données persistées. Une migration appliquée n’est jamais réécrite. Les contenus et brouillons restent conservés jusqu’à une conversion explicite ou un refus documenté.
Vérifiez contrats, packages, installation neuve, mise à jour de la version précédente, sauvegarde et récupération. Après migration, revenir au seul ancien code ne suffit pas : restaurez ensemble base, fichiers et clés compatibles selon le protocole d’exploitation.