Versionierung von Inhalten

IFS-Logo 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.

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

Jeder Inhalt der Online-Dokumentation ist Teil genau einer Antora-Komponente. Antora-Komponenten legen ihre Version in ihrer Konfigurationsdatei fest. Dieser Guide beschreibt, auf welche Art dies geschieht.

Für diesen Guide ist ein grundlegendes Verständnis der Konfigurationsdatei antora.yml nützlich.

1. Vorgehensweise

Die Online-Dokumentation der IsyFact verwendet zwei Arten der Versionierung: Spiegeln der Software-Version und das explizite Ausnehmen von der Versionierung.

1.1. Spiegeln der Software-Version

Wenn Antora-Komponenten zusammen mit Software-Komponenten veröffentlicht werden, spiegeln sie deren Version. Beispiele hierfür sind der Baustein Angular und die IsyFact-Standards.

Aktuell gibt es zwei Vorgehensweisen:

  • Bei kurzen Release-Zyklen enthält die Online-Dokumentation ausschließlich offizielle Releases einer Antora-Komponente.

  • Bei längeren Release-Zyklen beinhaltet die Online-Dokumentation auch einen Entwicklungsstand, damit sich die Nutzer der IsyFact auf die Änderungen des nächsten Releases vorbereiten können.

Unabhängig von der Vorgehensweise müssen zur Versionierung mehrere Parameter in der Konfigurationsdatei antora.yml gesetzt werden:

Ob und wie die Parameter zu setzen sind, erklärt der Abschnitt "Konfiguration der Version".

1.2. Explizites Ausnehmen von der Versionierung

Wenn die Inhalte der Antora-Komponente keine Versionierung benötigen, weil sie stets widerspiegeln, was zum aktuellen Zeitpunkt gilt, werden sie explizit von der Versionierung ausgenommen. Beispiele hierfür sind dieser Leitfaden sowie das Glossar.

Für solche Inhalte sieht Antora das Konzept einer Komponente ohne Version vor.

Die Konfiguration einer solchen Antora-Komponente ist denkbar einfach.

Listing 1. Antora-Komponente ohne Version
version: ~
Antora-Komponenten ohne Version durchlaufen keine Releases und sollten daher nicht in einem Git-Repository liegen, für das Releases erstellt werden.

2. Konfiguration der Version

Antora ermöglicht es, Versionsnummern explizit festzulegen, oder die Version anhand der konfigurierten Git-Referenz (Branch oder Tag) zu setzen.

2.1. Versionierung mittels Git-Referenz

Die Versionierung mithilfe der Git-Referenz ist dann sinnvoll, wenn eine Antora-Komponente über Tags versioniert wird oder die Branch-Namen eine gute Vorlage für die Version bieten.

Listing 2. Versionierung mittels Git-Referenz
version: true

Antora kürzt die Git-Referenz folgendermaßen ab:

  • aus refs/heads/main wird main,

  • aus refs/tags/v1.0rc4 wird v1.0rc4.

Reicht dieses einfache Mapping nicht aus, kann Antora auch komplexere Ersetzungen auf der Git-Referenz vornehmen.

Falls mehrere Versionen innerhalb einer antora.yml erfasst werden sollen (zum Beispiel für unterschiedliche Entwicklungsstände), wird die Datei folgendermaßen strukturiert:

Listing 3. Versionierung mittels Git-Referenz mit mehreren Versionen
version:
  (main|master|develop): 'NEXT'
  release/(*): $1
  (*): $1

Die Propertys werden wie folgt interpretiert:

  • (main|master|develop): Entwicklungsbranches für Major-Releases (main, master oder develop) werden mit einem expliziten Wert angegeben. Hierfür wird der Beispielwert NEXT durch einen gewünschten Wert (zum Beispiel '4 (DEV)' oder '4.0') ersetzt.

  • release/(*): Entwicklungsbranches für Minor-Releases (beispielsweise release/3.x) werden über Git mit der Versionsnummer des aktuellen Major-Releases versehen.

  • (*): Release-Branches werden immer mit Tags (beispielsweise 3.1.0), die die Versionsnummern abbilden, versehen.

Diese Lösung ist für viele Anwendungsfälle geeignet. Bei schnellen Release-Zyklen können ausschließlich Releases über Tags in die Online-Dokumentation aufgenommen werden. Bei langsameren Release-Zyklen können Entwicklungsversionen auf Major- und Minor-Ebene explizit berücksichtigt werden.

Da Releases durch diese Versionierungsart nachträglich nicht verändert werden können, ist eine Auszeichnung von Release-Versionen wie CURRENT nicht möglich. Allerdings können CURRENT-Versionen in der Online-Dokumentation im Selektor gelb statt grau dargestellt werden, was ohne Auszeichnung erkennbar ist (siehe <<>>.

selectors online docs
Abbildung 1. Darstellung der Selektoren in der Online-Dokumentation
Bei diesem Vorgehen ist es nicht sinnvoll, eine abweichende display_version zu setzen, da sich diese nicht im Einklang mit dem Wert von version ändert.

2.2. Explizite Versionierung

Deprecation

Dieser Teil der Dokumentation ist veraltet und wird in einem zukünftigen Release entfernt. Die Inhalte sollten zur Entwicklung neuer Anwendungen nicht mehr berücksichtigt werden. Stattdessen wird empfohlen, Versionierung mittels Git-Referenz zu verwenden.

Ist eine Versionierung über die Git-Referenz nicht sinnvoll, muss die Version explizit festgelegt werden. Die Version entspricht, wie in der IsyFact vorgeschrieben, dem Format nach Semantic Versioning.

Listing 4. Explizite Versionierung
version: '4.0.3'

Sollen Bugfix-Releases nicht zu einer Versionsänderung in der Dokumentation führen, kann diese davon abstrahieren.

Listing 5. Explizite Versionierung ohne Bugfix-Release
version: '4.0.x'

2.3. Auszeichnung spezieller Versionen

Deprecation

Dieser Teil der Dokumentation ist veraltet und wird in einem zukünftigen Release entfernt. Die Inhalte sollten zur Entwicklung neuer Anwendungen nicht mehr berücksichtigt werden. Stattdessen wird empfohlen, Versionierung mittels Git-Referenz zu verwenden.

Versionen mit spezieller Bedeutung sind mit einem Suffix zu kennzeichnen.

Tabelle 1. Auszeichnung spezieller Versionen
Art der Version Suffix

Aktuelle Version

CURRENT

LTS-Version

LTS

Entwicklungsstand

DEV

Für aktuelle Versionen und LTS-Versionen geschieht die Kennzeichnung über die display_version. Der Wert von version ist Bestandteil von Verweisen und sollte deswegen möglichst stabil bleiben.

Listing 6. Explizite Versionierung mit spezieller Auszeichnung
version: '4.0.3'
display_version: '4.0.3 (LTS)'
Diese Konfiguration funktioniert aufgrund der Dopplung der Versionsnummer nicht gut für die Versionierung über Git-Referenzen.

2.3.1. Auszeichnung von Entwicklungsständen

Für Entwicklungsstände gibt es eine weitere Möglichkeit der Konfiguration, bei dem die Version nicht, wie im vorigen Beispiel, in der Konfiguration dupliziert werden muss.

Listing 7. Konfiguration einer Entwicklungsversion (explizit)
version: '4.0.3'
prerelease: '(DEV)'

Aus dieser Konfiguration heraus setzt Antora die display_version auf den Wert 4.0.3 (DEV).

Entwicklungsstände können so auch ausgezeichnet werden, wenn die Versionierung über Git-Referenzen erfolgt.