Versionierung
Diese Seite ist ein Teil der IsyFact-Standards.
Alle Inhalte der Seite, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt.
Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.
Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.
1. Einleitung
Versionen von Bibliotheken, Schnittstellen und Anwendungen dienen zur eindeutigen Identifizierung von Software-Artefakten mit einem bestimmten Inhalt. Dieses Konzept trifft Vorgaben und Empfehlungen zum Aufbau der Versionsnummern, um eine bessere Einheitlichkeit und Vergleichbarkeit zu gewährleisten.
Die Isyfact bietet mit dem Maven-Plugin zur Versionierungskontrolle ein Werkzeug, um die Versionierung automatisch zu überprüfen. Eine Anleitung zur Einbindung und Nutzung des Maven-Plugins findet sich in Maven-Plugin zur Versionierungskontrolle.
2. Allgemeine Nomenklatur und Vorgaben
Versionen müssen nach dem folgenden Format aufgebaut sein. Inhalte in eckigen Klammern sind optional.
|
Die meisten der hier genannten Vorgaben sind unverändert aus „Semantic Versioning 2.0“ übernommen, einige wurden leicht verändert.
Die Terme "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" und "OPTIONAL" in diesem Dokument sind, wie in RFC 2119 beschrieben, zu interpretieren.
Unter einer API werden hier alle zur öffentlichen Schnittstelle einer Bibliothek gehörenden Klassen und Konfigurationsparameter verstanden.
Bei einem finalen Tag (Veröffentlichung) besteht die Versionsnummer nur aus MAJOR.MINOR.PATCH.
-
Eine Versionsnummer einer Veröffentlichung muss (MUST) dem Format X.Y.Z entsprechen, wobei X, Y und Z Ganzzahlen größer oder gleich null sind und eine Zahl größer als null keine führenden Nullen enthalten darf. X ist die Major-Version, Y ist die Minor-Version und Z ist die Patch-Version. Jedes Element muss (MUST) auf numerische Art und Weise erhöht werden.
Beispiele: 1.9.0, 1.10.0, 1.11.0. -
Sobald eine Version eines Projektes veröffentlicht wurde, darf (MUST NOT) der Inhalt dieser Version nicht mehr verändert werden. Eine Änderung am Inhalt muss (MUST) als eine neue Version veröffentlicht werden.
-
Versionsnummern mit einer Major-Version von 0 (0.y.z) sind für die initiale Development Phase gedacht. Änderungen können in jeder denkbaren Form und zu jeder Zeit auftreten. Eine eventuell vorhandene öffentliche API sollte nicht als stabil betrachtet werden.
-
Die Version 1.0.0 definiert die erste Veröffentlichung. Ab dieser Veröffentlichung hängt die Art und Weise, wie die Versionsnummer erhöht und verändert wird, von den Änderungen ab, die an der öffentlichen API einer Bibliothek vollzogen werden.
-
Eine Vorveröffentlichung kann (MAY) durch ein LABEL gekennzeichnet werden, indem ein Bindestrich, gefolgt von dem Vorveröffentlichungsbezeichner, dessen Elemente durch Punkte voneinander getrennt werden, an die Patch Version angehängt wird. Die Elemente des Bezeichners dürfen (MUST) nur aus alphanumerischen ASCII-Zeichen und dem Bindestrich ([0-9A-Za-z-]) bestehen. Sie dürfen (MUST NOT) außerdem nicht leer sein. Wenn ein Element ausschließlich aus Ziffern besteht, darf (MUST NOT) es keine führenden Nullen enthalten. Eine Vorveröffentlichungsversion hat einen niedrigeren Rang als die entsprechende reguläre Version. Ein Vorveröffentlichungsbezeichner kennzeichnet, dass die Version als unstable zu betrachten ist und dass sie unter Umständen nicht den Kompatibilitätsanforderungen, die für die entsprechende reguläre Version bestimmt wurden, entspricht.
Beispiele: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92. -
Build-Metadaten können (MAY) ausgezeichnet werden, indem ein Plus Symbol, gefolgt von den Metadaten, deren Elemente durch Punkte voneinander getrennt werden, an die Patch Version oder den Vorveröffentlichungsbezeichner angehängt wird. Die Elemente der Metadaten dürfen (MUST) nur aus alphanumerischen ASCII-Zeichen und dem Bindestrich ([0-9A-Za-z-]) bestehen. Sie dürfen (MUST NOT) außerdem nicht leer sein. Die Build-Metadaten haben keinerlei Einfluss auf den Rang einer Version, sodass zwei Versionen, deren Versionsnummern sich nur in den Build-Metadaten unterscheiden, denselben Rang einnehmen. Wenn eine Buildnummer angegeben wird, muss ein Verweis auf den Build-Server mitangegeben werden.
Beispiele: 1.0.0-alpha+CG.001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
Die genaue Semantik der Elemente und die Bedeutung der Erhöhung einer Stelle unterscheiden sich aber bei Bibliotheken, Anwendungen und Schnittstellen voneinander. Daher zeigen die kommenden Abschnitte die genauen Vorgaben pro Typ auf und liefern Beispiele.
|
Eine Aktualisierung auf eine MAJOR-Version führt mit sehr hoher Wahrscheinlichkeit zu inkompatiblen Schnittstellen-Versionen. Wie zum Beispiel von IsyFact 1.x auf IsyFact 2.0. |
3. Versionierung von IT-Systemen
Versionen von IT-Systemen folgen dem folgenden Muster:
|
Zusätzlich zu den im Kapitel Allgemeine Nomenklatur und Vorgaben getätigten Vorgaben und Empfehlungen gelten hier die folgenden Konkretisierungen:
Auf Grundlage einer Versionsnummer von MAJOR.MINOR.PATCH werden bei IT-Systemen nach IsyFact die einzelnen Elemente folgendermaßen erhöht:
-
MAJOR wird nach Absprache erhöht, wenn signifikante Änderungen am IT-System veröffentlicht werden,
-
MINOR wird erhöht, wenn neue Funktionalitäten veröffentlicht werden, und
-
PATCH wird erhöht, wenn es sich um reine Bugfixes handelt oder eine irreguläre Auslieferung (beispielsweise zur Fehlerbehebung) ist.
Beispiele: 1.0.2, 2.5.1, 1.2.1, 0.10.0-alpha1
|
Die Vorgaben zu Semantic Versioning (vgl. Allgemeine Nomenklatur und Vorgaben, Punkt 2) gelten auch für alle Ressourcen, wie beispielsweise Datenbank-Skripte. Das heißt, Fixes an Skripten sowie die Nachlieferungen fehlender Skripte müssen in einem gesonderten Release (z.B. Bugfix-Release) veröffentlicht werden. |
3.1. Versionierung im SCM
Die Benennung von Branches in einem SCM wie SVN oder Git hängt im Wesentlichen vom gewählten Workflow ab. Die Version eines finalen Tags eines IT-Systems muss dem oben genannten Format folgen. Finale Versionen dürfen kein Label enthalten.
Wenn für ein IT-System Entwicklungs- oder Integrationstags erstellt werden, beispielsweise für Continuous Delivery, müssen diese zusätzlich mit Build-Metadaten versehen werden, um möglichst genau feststellen zu können, welches Binärartefakt dem Tag zuzuordnen ist. Sie enthalten immer (MUST) einen alphanumerischen Identifier für den Build-Server und die Buildnummer.
Diese sollten daher dem folgenden Schema folgen:
|
Beispiele: 1.0.2+CG.101, 2.5.1+BSERV.277, 1.2.1+CG.54
4. Versionierung von Bibliotheken
Versionsangaben von Bibliotheken folgen dem folgenden Muster:
|
Zusätzlich zu den im Kapitel Allgemeine Nomenklatur und Vorgaben getätigten Vorgaben und Empfehlungen gelten hier die folgenden Konkretisierungen.
Wenn von kompatibel gesprochen wird, ist damit gemeint, dass ein Wechsel auf die kompatible Version der Bibliothek keine Anpassungen an dem Code der nutzenden Anwendung/Bibliothek erfordert, und die bisherige Funktionalität uneingeschränkt erhalten bleibt.
Auf Grundlage einer Versionsnummer von MAJOR.MINOR.PATCH werden die einzelnen Elemente folgendermaßen erhöht:
-
MAJOR wird erhöht, wenn API-inkompatible Änderungen veröffentlicht werden,
-
MINOR wird erhöht, wenn neue Funktionalitäten, welche kompatibel zur bisherigen API sind, veröffentlicht werden, und
-
PATCH wird erhöht, wenn die Änderungen ausschließlich API-kompatible Bugfixes umfassen.
Das bedeutet, dass die Regeln des Semantic Versioning 2.0 anzuwenden sind.
Zusätzlich gilt:
-
Instabile Entwicklungsversionen müssen (MUST) mit dem Label -SNAPSHOT oder einem anderen Label gekennzeichnet werden. Instabile Entwicklungsversionen sollten nicht über einen längeren Zeitraum in einer Anwendung eingebunden sein, da die Gefahr besteht, dass der Build instabil wird.
Beispiele: 1.0.0, 2.3.5-SNAPSHOT, 1.3.2-alpha
5. Versionierung von Schnittstellen
Versionsangaben von Schnittstellen folgen dem folgenden Muster:
|
Zusätzlich zu den im Kapitel Allgemeine Nomenklatur und Vorgaben getätigten Vorgaben und Empfehlungen gelten hier die folgenden Konkretisierungen und Abweichungen.
Bei Schnittstellen wird auf den Bugfix-Teil der Version verzichtet, da Schnittstellen keine Bugfixes im generellen Sinne enthalten können. Änderungen in einer Schnittstelle sind immer entweder API-kompatibel oder API-inkompatibel. Daher werden bei Schnittstellen nur die MAJOR- und MINOR-Elemente der Version genutzt.
Auf Grundlage einer Versionsnummer von MAJOR.MINOR werden die einzelnen Elemente folgendermaßen erhöht:
5.1. Lokale Schnittstellen und Remote-Schnittstellen (REST)
-
MAJOR wird erhöht, wenn API-inkompatible Änderungen veröffentlicht werden oder eine Schnittstelle parallel zu einer alten Schnittstellenversion angeboten werden soll,
-
MINOR wird erhöht, wenn ausschließlich API-kompatible Änderungen veröffentlicht werden.
Zusätzlich gilt:
-
Instabile Entwicklungsversionen müssen (MUST) mit dem Label -SNAPSHOT oder einem anderen Label gekennzeichnet werden. Instabile Entwicklungsversionen sollten nicht über einen längeren Zeitraum in einer Anwendung eingebunden sein, da die Gefahr besteht, dass der Build instabil wird.
-
Die MAJOR-Version muss (MUST) Teil der Artefakt-ID sein. Die MAJOR-Version darf nicht (MUST NOT) Teil der Maven-Versionsnummer sein. Zusätzlich muss die MAJOR-Version Teil der Quellcode-Strukturierung (z.B. im Package oder Namespace enthalten) sein. Dies ermöglicht das parallele Einbinden mehrerer Versionen ein- und derselben Schnittstelle.
Bei lokalen Schnittstellen:
-
kann ein Update auf eine höhere Java-Version zur Inkompatibilität führen. Dies ist zu evaluieren und entsprechend der allgemeinen Vorgaben, wie oben beschrieben, zu handhaben.
Bei Remote-Schnittstellen:
-
muss (MUST) auch die MAJOR-Version in dem URL-Pfad enthalten sein. So können jederzeit parallel unterschiedliche Versionen zur Laufzeit angeboten werden.
-
wird für den Nutzer der Schnittstelle empfohlen die MINOR-Version zu erhöhen, wenn die URL zu der Remote-Schnittstelle im Code geändert werden muss, da bei einem Update der Betriebsumgebung seitens des Schnittstellenanbieters nicht zur Inkompatibilität auf Nutzerseite führen sollte. Sofern die Verbindung zu der Remote-Schnittstelle parametrisiert ist, ist keine Änderung der Version notwendig.
-
als Anbieter dieser Schnittstelle ist bei einem Update der Java-Version (oder auch Betriebsumgebung) zu prüfen, ob eine Inkompatibilität vorliegen wird und entsprechend die Versionierung wie oben beschrieben (Lokale Schnittstellen und Remote-Schnittstellen (REST)) vorzunehmen ist.
Beispiele: 1.0, 2.33-SNAPSHOT, 1.3-alpha
5.2. Best Practices
5.2.1. Versionierung bei Anhebung der Parent-Version
Führt eine Anhebung der Parent-Version zu keiner Änderung an der Schnittstelle selbst oder zu keiner inkompatiblen Änderung, so bedarf es keiner Erhöhung der MINOR- oder MAJOR-Version der Schnittstelle.
Vorher:
<project>
<parent>
<groupId>de.bund.bva.isyfact.beispielanwendung</groupId>
<artifactId>isy-beispielanwendung-parent</artifactId>
<version>1.13.0</version>
</parent>
<artifactId>isy-beispielanwendung-nachrichten-v1</artifactId>
<version>5</version>
</project>Nachher:
Die MINOR-Version des Parents wurde erhöht. Die Version der Schnittstelle selbst bleibt unverändert bei 5.
<project>
<parent>
<groupId>de.bund.bva.isyfact.beispielanwendung</groupId>
<artifactId>isy-beispielanwendung-parent</artifactId>
<version>1.14.0</version>
</parent>
<artifactId>isy-beispielanwendung-nachrichten-v1</artifactId>
<version>5</version>
</project>5.2.2. Versionierung bei Änderungen an Schnittstellen
Sollten sich z.B. bei einer Anhebung der MINOR- oder MAJOR-Version Transportobjekte geändert haben, so ist eine Anhebung der MINOR-Version der Schnittstelle empfehlenswert, da es sich dabei um eine überschaubare Änderung handelt. Sollte eine Anhebung der MAJOR-Version zu Änderungen an mehreren Stellen führen, dann ist eine Erhöhung der MAJOR-Version der Schnittstelle vertretbar.