Versionierung von Inhalten

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.

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. 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. 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.2.1. Projektion des Referenznamens

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

Listing 3. Ableitung der Version durch Projektion des Referenznamens (Playbook)
version:
  (main|master|develop): 'NEXT'
  release/(*): $1
  feature/(*): $1 (1)
  (*): $1
1 Nur für die lokale Entwicklung!

In obigen Beispiel wird die Version wie folgt gebildet:

  • (main|master|develop): Entwicklungsbranches wird die nächste Hauptversion (hier: NEXT) zugewiesen.

  • release/(*) und feature/(*): Release- und Featurebranches (beispielsweise release/3.x) werden mit der Versionsnummer des Releases versehen.

  • (*): Für alle anderen Branches und Tags wird der Name 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 4. Auszeichnung von Entwicklungsständen (antora.yml)
prerelease: '(DEV)'

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