Seminar PlantUML CI/CD, Automatisierung und Diagrammtests

Diagramme werden erst dann verlässlich, wenn ihre Erzeugung reproduzierbar ist und Fehler automatisiert auffallen. Das Seminar etabliert eine Pipeline vom Quelltext über Syntax- und Qualitätsprüfungen bis zu versionierten Artefakten für Dokumentation, Releases und Reviews.

Inhaltsverzeichnis

• Zielgruppe
• Voraussetzungen
• Lernziele
• Kapitel 1: Reproduzierbarer Build
• Kapitel 2: Syntaxprüfung und Fehlerbehandlung
• Kapitel 3: Artefakte, Caching und Änderungsprüfung
• Kapitel 4: Qualitätsregeln und Diagrammtests
• Kapitel 5: Pipeline-Integration und Betriebsmodell
• Durchgängiges Praxisprojekt
• Methodik

Zielgruppe

DevOps Engineers, Build Engineers, Softwareentwickelnde, technische Redaktionen, Plattformteams und Architekturverantwortliche mit automatisierten Dokumentationsprozessen.

Voraussetzungen

Grundlagen der Versionsverwaltung und eines CI/CD-Systems. PlantUML-Quelltexte sollten gelesen und einfach angepasst werden können.

Lernziele

• PlantUML reproduzierbar über Kommandozeile oder Container ausführen
• Syntaxfehler, fehlende Includes und unerwünschte Änderungen automatisiert erkennen
• PNG-, SVG- und weitere Artefakte kontrolliert erzeugen und ablegen
• Caching, inkrementelle Builds und parallele Verarbeitung sinnvoll konfigurieren
• Diagrammprüfungen in Merge Requests, Releases und Dokumentations-Builds integrieren

Kapitel 1: Reproduzierbarer Build

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: PlantUML-Version und Laufzeitumgebung festschreiben, Quell- und Ausgabeverzeichnisse eindeutig strukturieren, Kommandozeilenparameter für Format und Zielpfad definieren sowie lokalen Build und Pipeline-Build identisch ausführbar machen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: PlantUML-Version und Laufzeitumgebung festschreiben.
2. Schritt 2 – Modellieren: Quell- und Ausgabeverzeichnisse eindeutig strukturieren.
3. Schritt 3 – Erweitern: Kommandozeilenparameter für Format und Zielpfad definieren.
4. Schritt 4 – Prüfen: lokalen Build und Pipeline-Build identisch ausführbar machen.

Praxisübung

Für den Schwerpunkt „Reproduzierbarer Build“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 2: Syntaxprüfung und Fehlerbehandlung

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: fehlerhafte Diagramme mit geeigneten Exit-Codes erkennen, Fail-Fast-Strategien für kleine und große Repositories wählen, Include-Pfade und Konfigurationsdateien kontrollieren sowie Fehlerausgaben für Pipeline-Logs und Entwicklerfeedback aufbereiten. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: fehlerhafte Diagramme mit geeigneten Exit-Codes erkennen.
2. Schritt 2 – Modellieren: Fail-Fast-Strategien für kleine und große Repositories wählen.
3. Schritt 3 – Erweitern: Include-Pfade und Konfigurationsdateien kontrollieren.
4. Schritt 4 – Prüfen: Fehlerausgaben für Pipeline-Logs und Entwicklerfeedback aufbereiten.

Praxisübung

Für den Schwerpunkt „Syntaxprüfung und Fehlerbehandlung“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 3: Artefakte, Caching und Änderungsprüfung

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Ausgabeformate nach Verwendungszweck auswählen, Metadaten und Änderungsstände gezielt berücksichtigen, nur betroffene Diagramme neu erzeugen sowie Build-Artefakte versionieren, veröffentlichen oder verwerfen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Ausgabeformate nach Verwendungszweck auswählen.
2. Schritt 2 – Modellieren: Metadaten und Änderungsstände gezielt berücksichtigen.
3. Schritt 3 – Erweitern: nur betroffene Diagramme neu erzeugen.
4. Schritt 4 – Prüfen: Build-Artefakte versionieren, veröffentlichen oder verwerfen.

Praxisübung

Für den Schwerpunkt „Artefakte, Caching und Änderungsprüfung“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 4: Qualitätsregeln und Diagrammtests

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Datei- und Namenskonventionen automatisiert prüfen, verbotene Direktiven und externe Includes erkennen, Referenzdiagramme oder strukturelle Prüfungen einführen sowie Fehlschlagskriterien für Warnung und harte Sperre festlegen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Datei- und Namenskonventionen automatisiert prüfen.
2. Schritt 2 – Modellieren: verbotene Direktiven und externe Includes erkennen.
3. Schritt 3 – Erweitern: Referenzdiagramme oder strukturelle Prüfungen einführen.
4. Schritt 4 – Prüfen: Fehlschlagskriterien für Warnung und harte Sperre festlegen.

Praxisübung

Für den Schwerpunkt „Qualitätsregeln und Diagrammtests“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 5: Pipeline-Integration und Betriebsmodell

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Jobs für Pull Requests, Hauptzweig und Release trennen, Container-Images und Abhängigkeiten aktualisierbar verwalten, Ergebnisse als Review-Artefakt bereitstellen sowie Verantwortung, Monitoring und Fehlerbehebung dokumentieren. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Jobs für Pull Requests, Hauptzweig und Release trennen.
2. Schritt 2 – Modellieren: Container-Images und Abhängigkeiten aktualisierbar verwalten.
3. Schritt 3 – Erweitern: Ergebnisse als Review-Artefakt bereitstellen.
4. Schritt 4 – Prüfen: Verantwortung, Monitoring und Fehlerbehebung dokumentieren.

Praxisübung

Für den Schwerpunkt „Pipeline-Integration und Betriebsmodell“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Durchgängiges Praxisprojekt

Ein Beispiel-Repository erhält einen lokalen Build und eine CI-Pipeline mit Syntaxprüfung, mehreren Ausgabeformaten, inkrementeller Verarbeitung, Artefaktablage und definierten Qualitätsregeln.

Methodik

Fachimpulse, Live-Coding, kommentierte Demonstrationen und schrittweise Übungen wechseln sich ab. Jede neue Technik wird zunächst an einem Minimalbeispiel geprüft, danach in das Gesamtprojekt übernommen und abschließend in einem strukturierten Review bewertet. Alle Übungen verwenden versionierbare Textquellen und reproduzierbare Render-Schritte.