Antora Build workflow

Beschreibung

Um TechDivision Asciidoc Dokumentationen zu publizieren, wird ein Antora Build Prozess bereitgestellt, der während des Pipeline Builds die komplette Antora Umgebung aufbaut und sich im Anschluss alle Modul Repositories zieht.

Die Erstellung eines neuen Tags ist nur bei folgenden Punkten erforderlich:

Add/Update UI Theme Attributes im Playbook asciidoc/attributes
Update Antora Playbook/s (test|prod|pacemaker/test)
Hinzufügen eines neuen Modul Dokumentation Repositories met-doc-playbook-<environment>.yml unter content/sources
Update des PDF Themes pdf-theme (tag-theme-listing)
Update des PDF Erstellung scripts src/prepare.php (Aufruf in .gitlab-ci.yml)

Um einen Build auf verschiedene derzeit vorhandene Antora Umgebungen auszurollen, werden Git Tags benutzt.

Der Build Workflow bezieht siche nur auf den Antora Build

Antora Build Git Tag Struktur:

Module Production Umgebung	`met/prod/<fortlaufende tag nummer>`
Module Test Umgebung	`met/test/<fortlaufende tag nummer>`
Pacemaker (2.x) Test Umgebung	`pacemaker/test/<fortlaufende tag nummer>`

Was passiert beim Antora Build

Mit der Datei .gitlab-ci.yml werden alle Tasks zum erstellen von Antora und dem bereitstellen aller Module, Schritt für Schritt in Gitlab mittels Pipeline abgearbeitet.

Erstellung der Antora Umgebung
Aufbau der unterschiedlichen Umgebungen (test|prod|pacemaker/test)
Ziehen aller Modul Asciidoc Repositories
Generierung der HTML Dateien für die unterschiedlichen Modul Dokumentation Versionen, anhand der vorhandenen adoc Dateien aus den Repositories, gelistet im Playbook der jeweiligen Antora Umgebung (test|prod|pacemaker/test)
Generierung der Modul PDFs und Leistungsbeschreibung PDFs in allen vorhandenen Versionen

Aufbau

Aufpassen: Die Tags für den Antora Build haben nichts mit den Modulen zu tun
Die Tags beziehen sich nur auf die Antora Umgebungen (test|prod|pacemaker/test), nicht aber auf die Module
Bei den Modulen wird bei allen Antora Builds (test|prod|pacemaker/test), immer auf alle im Antora Playbook gelisteten Modul Versionen verwiesen, da die Module nicht mit Tags arbeiten
Bei test|prod|pacemaker/test, wird immer die orginal Modul Dokumentationen verlinkt

Derzeit vorhandene Antora Build Tags
- met/prod/<fortlaufende tag nummer>
- met/test/<fortlaufende tag nummer>
- pacemaker/test/<fortlaufende tag nummer>

Workflow

Nach vorgenommenen Updates des Antora Builds sind folgende Schritte abzuarbeiten

Bitte ins locale Build Verzeichnis wechseln

Auflistung aller existierenden remote Tags

git ls-remote --tags origin

Bereinigung aller local/remote Tags bzw. Abgleich der lokalen Tags mit remote

git tag -l | xargs git tag -d && git fetch --tags

Tag Handling

Hinzufügen der Build Updates zum Repository

git add .

Commit erstellen

git commit -m "[TASK] <push description>"

Erstellung des jeweiligen benötigten Tags

# e.g. git tag met/test/109
git tag met/<test|prod|pacemaker/test>/<increment tag number>

Push des erstellten neuen Build Tags

# e.g. git push origin met/test/109
git push origin met/<test|prod|pacemaker/test>/<increment tag number>

Gitlab Pipeline

Um die Updates im Anschluss zu finalisieren sind folgende Schritte notwendig:

Öffnen des Build Repositories
Navigiere zu den CI/CD ⇒ Pipelines
Klick auf den Button Run Pipeline

Navigiere zu den CI/CD ⇒ Pipelines
Auswahl des bevorzugten Tags

Starte Deployment mit Run Pipeline

Pipeline Status Check

Wenn die Pipeline erfolgreich gelaufen ist, die Dokumetation aktualisieren