Versiebeheer en uitfasering
Een versie benoemt een contract dat bestaat, niet één dat gepland is.
Versies van ESFI-formaten identificeren een geïmplementeerd contract. Een versie beschrijft wat een conforme implementatie daadwerkelijk emitteert of accepteert; ze is geen roadmaplabel.
Versienummers
Gepubliceerde specificaties gebruiken een minorversie zoals 0.7. Het document en de gegenereerde output declareren die minorversie.
Een nieuwe minorversie is vereist wanneer het formaatcontract verandert: velden worden toegevoegd of verwijderd, vereist gedrag verandert, serialisatie- of identiteitsregels veranderen, of een bestaande afnemer niet langer op de vorige specificatie kan vertrouwen. Een breaking change is elke wijziging die eerder conforme producenten of afnemers incompatibel kan maken, waaronder het veranderen van de betekenis van een bestaand veld of het verplicht maken van een optioneel veld.
Patchfixes veranderen de versie die een document declareert niet. Correcties die het formaatcontract ongewijzigd laten, worden als changelogitems bij de gepubliceerde minorversie vastgelegd. Voorbeelden zijn tekstcorrecties, verduidelijking van een al geïmplementeerde regel of herstel van een implementatiefout zodat de output opnieuw overeenkomt met het gepubliceerde contract.
Als een wijziging het contract verandert in plaats van het te herstellen of verduidelijken, is het geen patchfix; dan is een nieuwe minorversie nodig.
Specificatie, implementatie en praktijk
De MPF-documentatie markeert elke regel met één van drie statussen: Specificatie 0.7, Referentie-implementatie of ESFI-praktijk. Zie het Overzicht.
De markers beschrijven ook hoe een regel van status kan veranderen:
- Gedrag van de referentie-implementatie dat de specificatietekst niet beschrijft wordt alleen normatief wanneer een gepubliceerde specificatieversie het beschrijft. Tot dan kunnen implementeerders er in de praktijk op steunen, maar niet als onderdeel van het contract.
- Een ESFI-praktijk, zoals een discoveryconventie op ESFI-sites, wordt alleen via een nieuwe specificatieversie onderdeel van het contract. Documentatie ervan maakt haar niet normatief.
- Een regel wordt nooit door een patchfix naar de specificatie gepromoveerd. Promotie verandert het contract, en een veranderd contract vereist een nieuwe minorversie.
Zo blijft de gepubliceerde specificatie smal en betrouwbaar: ze zegt waarop conforme producenten en afnemers kunnen vertrouwen, en niets dat alleen handig of gebruikelijk is.
Gepubliceerde versies zijn permanent
Zodra een ESFI-formaatversie is gepubliceerd, blijft haar specificatiepagina gepubliceerd en bereikbaar. Een nieuwere versie vervangt de historische pagina niet ter plaatse.
Zo behouden implementeerders een stabiele referentie voor documenten die een oudere versie blijven declareren, en blijft historische machineleesbare output interpreteerbaar zonder een eerdere specificatie te reconstrueren.
Deprecatie en uitfasering
Een versie kan deprecated worden wanneer ESFI migratie naar een nieuwere versie aanbeveelt. Deprecatie verandert de aanbeveling, niet de historische specificatie: de deprecated versie blijft bereikbaar en haar gedocumenteerde contract wordt niet herschreven om met de opvolger overeen te komen.
Een versie is retired wanneer ESFI haar niet langer als actueel implementatiedoel behandelt. Retirement wordt op de pagina van die versie vastgelegd, samen met de opvolger wanneer die bestaat. Retirement verwijdert de pagina niet.
Afnemers moeten de versie lezen die wordt gedeclareerd door het document dat ze verwerken. Producenten moeten de versie emitteren waarvan zij het gepubliceerde contract implementeren.
Huidige en vorige MPF-versies
MPF-documenten declareren momenteel mpf: '0.7'. Het geïmplementeerde gedrag is gedocumenteerd in Specificatie 0.7.
MPF 0.6 is de vorige gepubliceerde versie. Specificatie 0.6 blijft beschikbaar voor documenten die nog mpf: '0.6' declareren.
Posities worden anders geversioneerd
De themapagina’s op deze site zijn posities, geen formaatcontracten. Ze dragen geen versienummers. Wanneer een positie materieel verandert, wordt de wijziging onderaan de themapagina met datum vastgelegd. Zie Hoe u onze claims leest.
Gerelateerd: Overzicht · Implementatieregister · Publicatie en discovery