II) Versionierungskonzept FINE-SSTs
1. Präambel
Jede FINE-Schnittstelle unterliegt einem Versionierungskonzept und unterscheidet dabei zwischen Major und Minor Upgrades. Minor Upgrades sind immer rückwärtskompatibel - Major Upgrades nicht. Dementsprechend gibt es unterschiedliche Regelungen zu beachten, die im folgenden beschrieben sind.
2. Minor Upgrades
Minor Upgrades sind immer rückwärtskompatibel, ohne dass alle SST-Partner ihre Artefakte neu generieren müssen. Ihr Sinn liegt darin, eine leichte Erweiterbarkeit zu gewährleisten ohne aufwändige Abstimmungen mit allen SST-Partnern im Netzwerk durchführen zu müssen. Gleichzeitig müssen unnötige Störungen vermieden werden. Nachrichten mit einer neuen Minor Version können in den vorhandenen Queues/Endpunkten versendet werden, ohne dass ein Empfänger Probleme bekommt (bzw. bekommen darf). Es bewahrt aber niemanden davor, Minor Upgrades gut zu durchdenken und eventuelle Auswirkungen mit anderen SST-Partnern abzusprechen.
Beispiele: optionales Feld hinzufügen, ENUM erweitern
- Technische Aspekte
-
Geschäftsobjekte neuerer Minor Versionen werden in den gleichen Topics bzw. gleichen REST-Endpunkten verteilt wie die vorige Version. Ein Minor Upgrade darf dennoch nicht zu einem Validierungsfehler führen.
Ein SST-Anbieter muss sich für eine Version der Verteilung der JSON-Schema-Versionen entscheiden und diese umsetzen: 1. Kafka: Schema-Registry ist bei Kafka inklusive muss auf “rückwärtskompatibel” gesetzt werden Eine Version ist eine bei 1 beginnende Zahl, die hochgezählt wird Jeder Empfänger benötigt einen API-Key für den Abruf des Schemas Die Info über die Minor-Version steht pro Message im Kafka-Header 2. REST: spezielle URL bietet Abruf des Schemas muss durch Sender bereitgestellt werden
- Fachliche Aspekte/Anwendungs-Logik
-
Grund-Philosophie: “Wer nicht betroffen ist, den darf ein Minor Upgrade nicht stören”. Wenn ein bisher unerwarteter Wert übertragen wird, hat ein empfangendes System folgende Möglichkeiten:
-
Bei “Durchreichungs-Logik”: einfach weiterleiten
-
Bei Logik, die Entscheidungen trifft: Fehler in SST zurückmelden (out of scope im Versionierungskonzept, noch nicht geklärt)
-
- Perspektiven Sender vs. Empfänger
-
-
Sender bzw. Owner: kann ein Upgrade selbständig planen informiert die Empfänger (s.u. Organisation) muss keine alten Versionen unterstützen
-
Empfänger bzw. Nicht-Owner: muss mit unerwarteten Minor-Upgrades rechnen muss damit rechnen, dass es nicht jeder Sender zeitgleich das Upgrade durchführt. Das bedeutet, dass es mehrere Minor Versionen des gleichen Geschäftsobjekt im Netzwerk geben kann.
-
- Organisatorische Regelungen/Spielregeln
-
Der Verursacher eines Minor-Upgrades muss die Information darüber verteilen.
-
mindestens 1 Tag bei trivialen Änderungen (Voraussetzung: die automatische Verteilung der Versionen ist gelöst, s.o.)
-
ansonsten Projektkontext beachten
-
grundsätzlich immer “Flash” beachten!
-
ein Upgrade anderer Sender wird innerhalb von 3 Monaten erwartet
-
Problematik: Sender, welche nicht schritthalten senden veraltete Minor-Versionen, ohne dass es auffällt. Maßnahme: zunächst nur organisatorisch regelmäßig prüfen und Sender zu Upgrade “anregen”. Trägt dies langfristig nicht, ist eine andere organisatorische Maßnahme zu verabschieden - z.B. jährliche zwangsweise “Patch-Days” für alle Teilnehmer.
3. Major Upgrades
Major upgrades sind nicht rückwärtskompatible, strukturelle Änderungen, die mindestens eine technische Änderung benötigen. Diese müssen in separaten Queues/Endpunkten bereit gestellt werden.
Beispiele: Feld entfernen, Feld ändert Bedeutung, Feld wird zu Pflichtfeld, Umstrukturierung im JSON-Schema, ENUM verkleinern
- Technische Aspekte
-
Für neue Versionen von Geschäftsobjekten werden vom Sender unterschiedliche Topics bzw. REST-Endpunkten verwendet. Damit ist sowohl die Bereitstellung der vorigen Versionen gewährleistet als auch ein stufenweises Upgrade ermöglicht.
-
Kafka: Separate Topics pro Major-Version - Name des Topics enthält Major-Version (Übergangsregelung: Topic ohne Nummer entspricht Major-Version 1)
-
REST: Mit unterschiedlichen URLs arbeiten oder mit HTTP-Header -→ muss mit besprochen werden, da nur LP + LSAS REST-SST anbieten
-
- Fachliche Aspekte
-
Eine Änderung von Fachlichkeit bzw. Anwendungs-Logik muss vorher vom Anforderer bzw. Upgrade-Verursacher kommuniziert worden sein. Ansonsten darf ein Upgrade nicht durchgeführt werden.
- Perspektive Sender vs. Empfänger
-
-
Sender bzw. Owner: muss das OK aller Empfänger abholen muss sich auch mit allen andern Sendern des gleichen Objekttyps abstimmen und einen Upgrade-Plan besprechen, damit alte Major-Versionen zeitnah aus dem Netzwerk verschwinden
-
Empfänger bzw. Nicht-Owner: Muss sich darauf einstellen, anhand des Senders zu unterscheiden, ob jeweils die neue oder alte Version zu verarbeiten ist (“Demultiplexing”)
-
- Organisatorische Regelungen/Spielregeln
-
Die vorige Version ist weiterhin bereitzustellen und ein Ablösungsverfahren (im Projektkontext) abzustimmen, welches auf eine möglichst schnelle Ablösung zielen muss.