Seminar Antora – Content-Repositories, Versionierung und Multi-Repository-Strategien

Beschreibung

Das Seminar behandelt die Planung und Konfiguration verteilter Inhaltsquellen für Antora. Repository-Zuschnitt, Branch- und Tag-Strategien, Startpfade, Worktrees, private Quellen und reproduzierbare Release-Zuordnungen werden anhand mehrerer Organisationsmodelle erarbeitet. Der Schwerpunkt liegt auf belastbaren Regeln für Teams, die Dokumentation aus vielen Git-Repositories aggregieren.

Inhaltsübersicht

1. Repository-Modelle und Verantwortungsgrenzen
2. Branches, Tags und Versionsidentität
3. Startpfade und mehrere Komponenten pro Repository
4. Multi-Repository-Playbook
5. Private Repositories und Zugriffskontrolle
6. Release- und Änderungsprozess

Lernziele

• Repository-Zuschnitte nach Team-, Produkt- und Releasegrenzen bewerten.
• Branches, Tags, Startpfade und Worktrees korrekt als Inhaltsquellen konfigurieren.
• Mehrere öffentliche und private Quellen reproduzierbar aggregieren.
• Release- und Governance-Regeln für verteilte Dokumentationsbestände etablieren.

1. Repository-Modelle und Verantwortungsgrenzen

Die Wahl zwischen Mono-Repository, produktbezogenen Repositories und verteilten Inhaltsquellen beeinflusst Eigentum, Release und Wartung.

Schritt-für-Schritt: Ein passendes Repository-Modell auswählen

1. Teams, Produkte, Releasezyklen und gemeinsame Inhalte als Einflussfaktoren erfassen.
2. Mono-Repository, Multi-Repository und hybride Modelle anhand definierter Kriterien vergleichen.
3. Eigentums-, Freigabe- und Eskalationsgrenzen für jedes Repository festlegen.
4. Abhängigkeiten zu Quellcode, UI, Playbook und gemeinsamen Inhalten dokumentieren.
5. Das bevorzugte Modell mit Risiken, Ausnahmen und Migrationsaufwand begründen.

Praxisaufgabe

Für drei Organisationsszenarien wird jeweils ein Repository-Modell ausgewählt und in einer Entscheidungsmatrix dokumentiert.

2. Branches, Tags und Versionsidentität

Git-Referenzen und Antora-Versionen müssen bewusst gekoppelt werden, damit Releases nachvollziehbar bleiben.

Schritt-für-Schritt: Git-Referenzen auf Dokumentationsversionen abbilden

1. Bestehende Release-Branches, Wartungsbranches und Tags inventarisieren.
2. Regeln für veröffentlichte, unveröffentlichte und archivierte Dokumentationsstände festlegen.
3. Branch- und Tag-Muster im Playbook so einschränken, dass keine unbeabsichtigten Versionen einfließen.
4. Komponenten-Deskriptoren auf konsistente Versionswerte und Anzeigenamen prüfen.
5. Mehrere Referenzen bauen und die resultierenden Komponenten-Versionen kontrollieren.
6. Abweichungen zwischen Software- und Dokumentationsrelease als explizite Ausnahme dokumentieren.

Praxisaufgabe

Eine inkonsistente Branch- und Tag-Struktur wird in ein nachvollziehbares Versionsmodell überführt.

3. Startpfade und mehrere Komponenten pro Repository

Startpfade ermöglichen mehrere unabhängige Dokumentationskomponenten in einem Repository.

Schritt-für-Schritt: Startpfade für komplexe Repositories konfigurieren

1. Repository-Verzeichnisse mit eigenständigen Komponenten-Deskriptoren identifizieren.
2. Statische und musterbasierte Startpfade gegeneinander abwägen.
3. Startpfade im Playbook deklarieren und Überschneidungen ausschließen.
4. Jeden Startpfad auf vollständige Modulstruktur und eindeutige Komponentenidentität prüfen.
5. Den Build ausführen und die erwartete Anzahl von Komponenten-Versionen kontrollieren.
6. Neue Startpfade über einen standardisierten Review- und Freigabeprozess aufnehmen.

Praxisaufgabe

Ein Monorepo mit drei Produktdokumentationen wird über separate Startpfade eingebunden.

4. Multi-Repository-Playbook

Das Playbook bündelt Quellen aus unterschiedlichen Hosts, Organisationen und Referenzen.

Schritt-für-Schritt: Mehrere Inhaltsquellen reproduzierbar aggregieren

1. Repository-URLs, Referenzmuster und Startpfade in einer Quellenmatrix vorbereiten.
2. Quellenblöcke im Playbook nach Verantwortungsbereich gruppieren und kommentieren.
3. Gemeinsame Standardwerte nur dort verwenden, wo sie für alle Quellen gelten.
4. Lokale Arbeitskopien und entfernte Repositories getrennt testen.
5. Build-Protokolle auf geklonte Referenzen, Überschneidungen und unerwartete Quellen prüfen.
6. Eine revisionssichere Zuordnung zwischen Build, Playbook-Version und Quellständen dokumentieren.

Praxisaufgabe

Eine Site aus vier Repositories und mehreren Release-Linien wird aufgebaut und auf Vollständigkeit geprüft.

5. Private Repositories und Zugriffskontrolle

Geschützte Quellen erfordern kontrollierte Zugangsdaten und eine klare Trennung zwischen Build- und Veröffentlichungsberechtigungen.

Schritt-für-Schritt: Private Inhaltsquellen sicher anbinden

1. Erforderliche Leserechte je Repository und Build-Umgebung erfassen.
2. Kurzlebige Tokens, Deploy Keys oder Plattformidentitäten nach dem Prinzip minimaler Rechte auswählen.
3. Zugangsdaten ausschließlich über geschützte Laufzeitvariablen oder Secret-Stores bereitstellen.
4. Protokolle und Fehlermeldungen auf unbeabsichtigte Offenlegung sensibler Werte prüfen.
5. Entzug, Rotation und Notfallersatz der Zugangsdaten testen.
6. Den Zugriff mit Positiv- und Negativfällen dokumentieren und freigeben.

Praxisaufgabe

Eine private Quelle wird mit einem minimal berechtigten Build-Zugang eingebunden und anschließend kontrolliert gesperrt.

6. Release- und Änderungsprozess

Verteilte Inhalte benötigen einen abgestimmten Prozess, damit Releases vollständig und wiederholbar veröffentlicht werden.

Schritt-für-Schritt: Einen Multi-Repository-Releaseprozess definieren

1. Auslöser für Dokumentationsreleases und erforderliche Quellstände festlegen.
2. Freigaben, Abhängigkeiten und Sperrfristen über alle beteiligten Repositories abbilden.
3. Einen Manifest- oder Referenznachweis für den veröffentlichten Build erzeugen.
4. Fehlende oder verspätete Teilinhalte mit klaren Eskalationsregeln behandeln.
5. Rollback auf einen nachweislich konsistenten Quellstand vorbereiten.
6. Den Gesamtprozess in einem Probelauf mit Abnahmeprotokoll durchspielen.

Praxisaufgabe

Als Ergebnis entsteht ein Release-Runbook mit Quellmatrix, Freigaben, Nachweis und Rollback-Schritten.

Zielgruppe und Voraussetzungen

Zielgruppe: Documentation Engineers, Git- und Plattformadministration, DevOps-Teams, Release Management, technische Redaktionsleitung und Softwarearchitektur.

Voraussetzungen: Sicherer Umgang mit Git-Grundlagen, Branches und Merge Requests sowie ein grundlegendes Antora-Verständnis.

Methodik und Arbeitsweise

Die Inhalte werden durch strukturierte Erläuterungen, Demonstrationen, schrittweise Konfigurations- und Analyseaufgaben sowie kontrollierte Fehlerfälle vertieft. Jede Übung verwendet definierte Ausgangswerte, Prüfpunkte und Dokumentationsanforderungen, damit die erarbeiteten Abläufe im späteren Projekt- und Betriebsalltag reproduzierbar bleiben.