Seminar Antora – Upgrade, Wartung und Release-Management

Beschreibung

Das Seminar vermittelt einen kontrollierten Wartungs- und Upgrade-Prozess für Antora-Plattformen. Antora-, Node.js-, Asciidoctor-, UI-, Erweiterungs- und Suchabhängigkeiten werden inventarisiert, Kompatibilitätsrisiken bewertet, Testmatrizen aufgebaut und Upgrades über Staging, Freigabe und Rollback umgesetzt. Ergänzend werden Releasebeobachtung, Patchzyklen, technische Schulden und Betriebsdokumentation organisiert.

Inhaltsübersicht

1. Plattforminventar und Abhängigkeitsmatrix
2. Releasebewertung und Upgrade-Entscheidung
3. Regressionstest und Referenzartefakte
4. Staging-Upgrade und Fehleranalyse
5. Produktivsetzung und Rollback
6. Wartungsprozess und technische Schulden

Lernziele

• Alle upgrade-relevanten Komponenten und Kopplungen einer Antora-Plattform inventarisieren.
• Kompatibilitätsrisiken durch reproduzierbare Testmatrizen beherrschen.
• Upgrades gestuft mit Abnahme und belastbarem Rollback durchführen.
• Patch-, Release- und Schuldenmanagement als kontinuierlichen Prozess organisieren.

1. Plattforminventar und Abhängigkeitsmatrix

Ein Upgrade kann nur bewertet werden, wenn alle Laufzeit-, Paket- und Inhaltskopplungen bekannt sind.

Schritt-für-Schritt: Die bestehende Plattform vollständig inventarisieren

1. Antora-, Site-Generator-, Node.js- und Paketmanager-Versionen erfassen.
2. UI-Bundle, Erweiterungen, Suchkomponenten und Assembler-Exporter auflisten.
3. Direkte und transitive Abhängigkeiten sowie gesperrte Versionen dokumentieren.
4. Build-Umgebungen, Container, CI-Runner und Veröffentlichungskomponenten ergänzen.
5. Kompatibilitäts- und Eigentumsbeziehungen in einer Matrix abbilden.
6. Unbekannte, ungewartete oder nicht reproduzierbare Bestandteile als Risiko markieren.

Praxisaufgabe

Für eine Beispielplattform wird eine vollständige Abhängigkeits- und Verantwortungsmatrix erstellt.

2. Releasebewertung und Upgrade-Entscheidung

Neue Versionen werden anhand fachlicher Notwendigkeit, Sicherheitsbedarf und Änderungsrisiko bewertet.

Schritt-für-Schritt: Ein Upgrade fundiert priorisieren

1. Verfügbare Zielstände und unterstützte Laufzeitkombinationen erfassen.
2. Änderungen nach Fehlerbehebung, Sicherheit, Funktion, Verhalten und Inkompatibilität klassifizieren.
3. Betroffene Playbooks, Inhalte, UI-Templates und Erweiterungen zuordnen.
4. Nutzen, Dringlichkeit, Testaufwand und Rückfallrisiko bewerten.
5. Zielversion und Upgrade-Pfad einschließlich notwendiger Zwischenschritte festlegen.
6. Entscheidung, Annahmen und Abbruchkriterien dokumentieren.

Praxisaufgabe

Aus mehreren möglichen Zielständen wird ein begründeter Upgrade-Pfad ausgewählt.

3. Regressionstest und Referenzartefakte

Stabile Referenztests machen unerwartete Änderungen an Struktur, Inhalt und Darstellung sichtbar.

Schritt-für-Schritt: Eine Upgrade-Testmatrix aufbauen

1. Repräsentative Komponenten, Versionen, Seitentypen und Sonderfälle auswählen.
2. Baseline-Build mit Protokoll, Dateiliste, Suchindex und Stichproben-Screenshots sichern.
3. Automatisierte Tests für Build-Erfolg, Xrefs, Assets, Navigation und Erweiterungen definieren.
4. Erwartete, tolerierbare und blockierende Unterschiede festlegen.
5. Testmatrix für unterstützte Node.js- und Paketkombinationen einrichten.
6. Ergebnisse in einem vergleichbaren Upgrade-Bericht zusammenführen.

Praxisaufgabe

Eine Referenzsuite wird gegen den Ausgangsstand ausgeführt und als Upgrade-Baseline freigegeben.

4. Staging-Upgrade und Fehleranalyse

Das Upgrade wird zunächst in einer isolierten Umgebung mit kontrollierten Änderungen durchgeführt.

Schritt-für-Schritt: Den Zielstand in Staging umsetzen

1. Upgrade-Branch und saubere Staging-Umgebung vorbereiten.
2. Abhängigkeiten schrittweise aktualisieren und jede Änderung nachvollziehbar committen.
3. Playbooks, UI und Erweiterungen an geänderte Schnittstellen oder Defaults anpassen.
4. Vollständige Regression und Performance-Baseline ausführen.
5. Fehler nach Laufzeit, Paket, Konfiguration, Inhalt, UI oder Erweiterung isolieren.
6. Restabweichungen mit Risiko, Eigentümer und Entscheidung dokumentieren.

Praxisaufgabe

Ein vorbereiteter Versionssprung wird in Staging durchgeführt und auftretende Inkompatibilitäten werden systematisch behoben.

5. Produktivsetzung und Rollback

Die Freigabe verbindet technische Nachweise, Kommunikationsplan und eine erprobte Rückfallmöglichkeit.

Schritt-für-Schritt: Ein Upgrade kontrolliert ausrollen

1. Freigabekriterien und erforderliche Zustimmungen anhand des Upgrade-Berichts prüfen.
2. Produktionsartefakt und Abhängigkeiten unveränderlich kennzeichnen.
3. Wartungsfenster, Kommunikation und Beobachtungszeitraum festlegen.
4. Upgrade-Pipeline ausführen und Smoke Tests unmittelbar nach Veröffentlichung durchführen.
5. Rollback bei definierten Schwellenwerten auf die vorherige Baseline auslösen.
6. Ergebnis, Abweichungen und endgültige Freigabe dokumentieren.

Praxisaufgabe

Upgrade und Rollback werden in einer Übungsumgebung vollständig durchgespielt.

6. Wartungsprozess und technische Schulden

Regelmäßige kleine Updates reduzieren das Risiko seltener großer Versionssprünge.

Schritt-für-Schritt: Einen nachhaltigen Lebenszyklusprozess etablieren

1. Beobachtung relevanter Releases, Sicherheitsmeldungen und Laufzeitzyklen organisieren.
2. Patch-, Minor- und Major-Updates mit unterschiedlichen Prüftiefen klassifizieren.
3. Regelmäßige Test- und Wartungsfenster im Betriebskalender verankern.
4. Veraltete Erweiterungen, UI-Anpassungen und Workarounds als technischen Schuldenbestand führen.
5. Kennzahlen für Updatealter, Teststatus und offene Inkompatibilitäten definieren.
6. Runbook, Verantwortlichkeiten und Eskalationsweg verbindlich freigeben.

Praxisaufgabe

Als Arbeitsergebnis entsteht ein Wartungs- und Releasekalender mit Prüftiefen, Rollen und Schuldenbacklog.

Zielgruppe und Voraussetzungen

Zielgruppe: Plattformbetrieb, Documentation Engineering, DevOps, technische Architektur, Informationssicherheit, Release Management und Verantwortliche für Wartung und Lebenszyklus.

Voraussetzungen: Praktische Erfahrung mit Antora-Builds, Node.js-Abhängigkeiten, Git und CI/CD sowie Zugang zu einer Test- oder Staging-Umgebung.

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.