Versionnement et dépréciation
Une version nomme un contrat qui existe, pas un contrat planifié.
Les versions des formats ESFI identifient un contrat implémenté. Une version décrit ce qu’une implémentation conforme émet ou accepte réellement ; ce n’est pas une étiquette de feuille de route.
Numéros de version
Les spécifications publiées utilisent une version mineure telle que 0.7. Le document et la sortie générée déclarent cette version mineure.
Une nouvelle version mineure est requise lorsque le contrat du format change : des champs sont ajoutés ou supprimés, un comportement obligatoire change, les règles de sérialisation ou d’identité changent, ou un consommateur existant ne peut plus s’appuyer sur la spécification précédente. Une modification incompatible est toute modification susceptible de rendre incompatibles des producteurs ou consommateurs auparavant conformes, y compris le changement de sens d’un champ existant ou le passage d’un champ facultatif à obligatoire.
Les correctifs patch ne modifient pas la version déclarée par un document. Les corrections qui laissent le contrat du format inchangé sont consignées comme entrées de changelog pour la version mineure publiée. Cela comprend, par exemple, la correction de la prose, la clarification d’une règle déjà implémentée ou la correction d’un défaut d’implémentation afin que la sortie corresponde à nouveau au contrat publié.
Si une modification change le contrat au lieu de le restaurer ou de le clarifier, ce n’est pas un correctif patch ; elle exige une nouvelle version mineure.
Spécification, implémentation et pratique
La documentation MPF marque chaque règle avec l’un de trois statuts : Specification 0.7, Reference implementation ou ESFI practice. Voir la Vue d’ensemble.
Ces marqueurs décrivent également comment une règle peut changer de statut :
- Un comportement de Reference implementation que le texte de la spécification ne décrit pas ne devient normatif que lorsqu’une version publiée de la spécification le décrit. Jusque-là, les implémenteurs peuvent s’y fier en pratique, mais pas comme partie du contrat.
- Une ESFI practice, telle qu’une convention de découverte utilisée sur les sites ESFI, ne devient partie du contrat qu’au travers d’une nouvelle version de la spécification. Le fait de la documenter ne la rend pas normative.
- Une règle n’est jamais promue dans la spécification par un correctif patch. Une promotion modifie le contrat, et un contrat modifié exige une nouvelle version mineure.
Cela maintient la spécification publiée étroite et fiable : elle indique ce dont les producteurs et consommateurs conformes peuvent dépendre, et rien de ce qui est seulement pratique ou habituel.
Les versions publiées sont permanentes
Une fois qu’une version d’un format ESFI est publiée, sa page de spécification reste publiée et accessible. Une version plus récente ne remplace pas la page historique sur place.
Cela donne aux implémenteurs une référence stable pour les documents qui continuent de déclarer une ancienne version et permet d’interpréter les sorties historiques lisibles par machine sans reconstruire une spécification antérieure.
Dépréciation et retrait
Une version peut être dépréciée lorsqu’ESFI recommande de migrer vers une version plus récente. La dépréciation modifie la recommandation, pas la spécification historique : la version dépréciée reste accessible et son contrat documenté n’est pas réécrit pour correspondre à son successeur.
Une version est retirée lorsqu’ESFI ne la considère plus comme une cible d’implémentation actuelle. Le retrait est consigné sur la page de cette version avec son successeur, lorsqu’il existe. Le retrait ne supprime pas la page.
Les consommateurs devraient lire la version déclarée par le document qu’ils traitent. Les producteurs devraient émettre la version dont ils implémentent le contrat publié.
Versions MPF actuelle et précédente
Les documents MPF déclarent actuellement mpf: '0.7'. Le comportement implémenté est documenté dans la Spécification 0.7.
MPF 0.6 est la version publiée précédente. Sa Spécification 0.6 reste disponible pour les documents qui déclarent encore mpf: '0.6'.
Les positions sont versionnées différemment
Les pages thématiques de ce site sont des positions, pas des contrats de format. Elles ne portent pas de numéro de version. Lorsqu’une position change de manière substantielle, le changement est consigné au bas de la page thématique avec sa date. Voir Comment lire nos affirmations.
Associé : Vue d’ensemble · Registre des implémentations · Publication et découverte