Versionierung und Ablösung
Eine Version benennt einen Vertrag, der existiert, nicht einen geplanten.
ESFI-Formatversionen identifizieren einen implementierten Vertrag. Eine Version beschreibt, was eine konforme Implementierung tatsächlich emittiert oder akzeptiert; sie ist kein Roadmap-Label.
Versionsnummern
Veröffentlichte Spezifikationen verwenden eine Minor-Version wie 0.7. Dokument und erzeugte Ausgabe deklarieren diese Minor-Version.
Eine neue Minor-Version ist erforderlich, wenn sich der Formatvertrag ändert: Felder werden hinzugefügt oder entfernt, erforderliches Verhalten ändert sich, Serialisierungs- oder Identitätsregeln ändern sich oder ein bestehender Consumer kann sich nicht mehr auf die vorherige Spezifikation verlassen. Eine Breaking Change ist jede Änderung, die zuvor konforme Producer oder Consumer inkompatibel machen kann, einschließlich der Änderung der Bedeutung eines bestehenden Feldes oder der Verpflichtung eines zuvor optionalen Feldes.
Patch-Fixes ändern die von einem Dokument deklarierte Version nicht. Korrekturen, die den Formatvertrag unverändert lassen, werden als Changelog-Einträge gegen die veröffentlichte Minor-Version dokumentiert. Beispiele sind Textkorrekturen, Klarstellungen bereits implementierter Regeln oder die Behebung eines Implementierungsfehlers, sodass die Ausgabe wieder dem veröffentlichten Vertrag entspricht.
Wenn eine Änderung den Vertrag verändert, statt ihn wiederherzustellen oder klarzustellen, ist sie kein Patch-Fix; sie erfordert eine neue Minor-Version.
Spezifikation, Implementierung und Praxis
Die MPF-Dokumentation markiert jede Regel mit einem von drei Status: Spezifikation 0.7, Referenzimplementierung oder ESFI-Praxis. Siehe Überblick.
Die Marker beschreiben auch, wie eine Regel den Status wechseln kann:
- Verhalten der Referenzimplementierung, das im Spezifikationstext nicht beschrieben ist, wird erst normativ, wenn eine veröffentlichte Spezifikationsversion es beschreibt. Bis dahin können Implementierer sich in der Praxis darauf stützen, aber nicht als Teil des Vertrags.
- Eine ESFI-Praxis, etwa eine Discovery-Konvention auf ESFI-Sites, wird erst durch eine neue Spezifikationsversion Teil des Vertrags. Dokumentation macht sie nicht normativ.
- Eine Regel wird niemals durch einen Patch-Fix in die Spezifikation promoviert. Promotion verändert den Vertrag, und ein veränderter Vertrag erfordert eine neue Minor-Version.
So bleibt die veröffentlichte Spezifikation eng und verlässlich: Sie sagt, worauf konforme Producer und Consumer bauen können, und nichts, was nur bequem oder üblich ist.
Veröffentlichte Versionen sind dauerhaft
Sobald eine ESFI-Formatversion veröffentlicht ist, bleibt ihre Spezifikationsseite veröffentlicht und erreichbar. Eine neuere Version ersetzt die historische Seite nicht an Ort und Stelle.
Damit erhalten Implementierer eine stabile Referenz für Dokumente, die weiterhin eine ältere Version deklarieren, und historische maschinenlesbare Ausgabe bleibt interpretierbar, ohne eine frühere Spezifikation rekonstruieren zu müssen.
Deprecation und Retirement
Eine Version kann deprecated werden, wenn ESFI die Migration auf eine neuere Version empfiehlt. Deprecation ändert die Empfehlung, nicht die historische Spezifikation: Die deprecated Version bleibt erreichbar und ihr dokumentierter Vertrag wird nicht auf den Nachfolger umgeschrieben.
Eine Version ist retired, wenn ESFI sie nicht mehr als aktuelles Implementierungsziel behandelt. Retirement wird auf der Seite dieser Version zusammen mit dem Nachfolger dokumentiert, sofern einer existiert. Retirement entfernt die Seite nicht.
Consumer sollten die Version lesen, die das verarbeitete Dokument deklariert. Producer sollten die Version ausgeben, deren veröffentlichten Vertrag sie implementieren.
Aktuelle und vorherige MPF-Versionen
MPF-Dokumente deklarieren derzeit mpf: '0.7'. Das implementierte Verhalten ist in Spezifikation 0.7 dokumentiert.
MPF 0.6 ist die vorherige veröffentlichte Version. Spezifikation 0.6 bleibt für Dokumente verfügbar, die weiterhin mpf: '0.6' deklarieren.
Positionen werden anders versioniert
Die Themenseiten dieser Site sind Positionen, keine Formatverträge. Sie tragen keine Versionsnummern. Wenn sich eine Position materiell ändert, wird die Änderung am Fuß der Themenseite mit Datum dokumentiert. Siehe Wie Sie unsere Aussagen lesen.
Verwandt: Überblick · Implementierungsregister · Veröffentlichung und Discovery