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 haben eine definierte Version. Dieser Guide beschreibt, auf welche Art die Version einer Komponente festgelegt werden kann.

Für diesen Guide ist ein grundlegendes Verständnis der Antora-Komponenten-Konfigurationsdatei und der Antora-Playbook-Konfiguration 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 folgende 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.

  • Zur Weiterentwicklung der Online-Dokumentation und Integration von Änderungen werden für die Entwicklung auch Feature-Branches erstellt.

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

  • version: (optional) Festlegen der Version der Antora-Komponente,

  • prerelease: (optional) Kennzeichnung der Version als Entwicklungsstand.

Wie die Parameter zu setzen sind, erklären die Abschnitte "Konfiguration der Version" und "Auszeichnung von Entwicklungsständen".

1.2. Ausnehmen von der Versionierung

Wenn die Inhalte der Antora-Komponente keine Versionierung benötigen, weil sie stets widerspiegeln, was zum aktuellen Zeitpunkt gilt, werden für diese Komponenten keine Releases erstellt und stattdessen der jeweilige Stand der Online-Dokumentation erstellt.. Beispiele hierfür sind dieser Leitfaden sowie das Glossar.

Wenn Inhalte lediglich der Strukturierung der Inhalte dienen und selbst nicht aktualisiert werden, können diese von der Versionierung ausgenommen werden. Wie eine Antora-Komponente von der Versionierung ausgenommen werden kann erklärt der Abschnitt Explizites Ausnehmen von der Versionierung.

2. Konfiguration der Version

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

2.1. Explizites Ausnehmen von der Versionierung

Für Antora-Komponente die keine Versionierung benötigen, sieht Antora das Konzept einer Komponente ohne Version vor.

Die Konfiguration einer solchen Antora-Komponente ist denkbar einfach.

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

2.2. Explizites Setzen der Version

Die Version einer Komponente kann explizit in der Komponenten-Konfigurationsdatei gesetzt werden.

Listing 2. Explizites Setzen der Version (antora.yml)
version: '4.0.3'

2.3. 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.

2.3.1. Einfache Versionierung

Listing 3. Verwendung des Referenznamens als Version (antora.yml)
version: true

Der Wert true weist Antora an, den Referenznamen als Wert für die Komponenten-Version zu verwenden.

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.

2.3.2. Komplexere Versionierung

Die Referenznamen-Projektion ermöglicht es, den Referenznamen mit einem Muster abzugleichen und dann eine Version auf der Grundlage dieser Übereinstimmung zu erstellen.

Listing 4. Ableitung der Version durch Projektion des Referenznamens
version:
  (main|master|develop): 'NEXT'
  release/(*): $1
  (*): $1

In obigen Beispiel wird die Version wie folgt gebildet:

  • (main|master|develop): Entwicklungsbranches wird die Version NEXT zugewiesen.

  • release/(*): Releasebranches (beispielsweise release/3.x) werden mit der Versionsnummer des Releases versehen.

  • (*): Für alle anderen Branches, wie beispielsweise Feature-Branches wird der Branchname als Version verwendet.

Das Mapping von Referenznamen auf Versionen kann sinnvollerweise im Antora Playbook für eine Content-Source definiert werden, da diese auf mehrere Komponenten-Versionen angewandt wird, während die Antora-Komponentenkonfiguration dem jeweiligen Stand einer Komponenten-Version entspricht.
Eine explizit gesetzte Version hat Vorrang zu einer Ableitung der Version auf den Branchnamen.

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.

3. Auszeichnung von Entwicklungsständen

Entwicklungsstände können als solche ausgezeichnet werden, um diese in der Sortierung der Versionen und der Anzeige der Komponentenversionen anzupassen.

Listing 5. Auszeichnung von Entwicklungsständen (antora.yml)
version: '4.0.3'
prerelease: '(DEV)'

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

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