Prozess der Veröffentlichung

Diese Seite beschreibt den vollständigen Pipeline-Ablauf der AUTOSAR Adaptive Platform API-Referenz: von den führenden Spezifikations-Records über Übersetzung und Diagramme bis zu HTML-Ausgabe, Validierung, Berichten und Traceability. Sie richtet sich an Kurator:innen, Maintainer und AI-Agenten gleichermaßen. Operative Agent-Instruktionen (wie AGENTS.md) sind selbst als eigenständige Pipeline-Artefakte mit eigenem Kurations- und Review-Lebenszyklus geführt und werden hier referenziert.

1. Überblick

Die Pipeline folgt einem deterministischen Schichtenmodell: Spezifikations-DB → Kuratierung & Review → i18n-Segmentierung → Diagrammübersetzung → HTML-Generierung → Validierung → Berichte & Traceability. Jede Veröffentlichung entsteht reproduzierbar aus den definierten Quellen unter _src/.

2. Source of Truth & Artefakt-Kategorien

Die Ablagestruktur unterscheidet strikt zwischen autoritativen Quellen, verwalteten Pipeline-Artefakten und flüchtigen Build-Produkten:

• Source of Truth (maßgeblich): _src/spec/records/**/*.json (Spezifikations-Records) sowie Kataloge wie _src/spec/namespaces.json und _src/spec/projects.json. Alle inhaltlichen Änderungen müssen hier erfolgen.
• Pipeline-Artefakte (versioniert/kuratiert): Seitenmodelle unter _src/sources/pages/, Review- und Curation-Queues, i18n-Register (_src/i18n/), Diagramm-Quellen (.dot, .seq.json) sowie Agent-Instruktionen (z. B. AGENTS.md).
• Generierte Build-Artefakte (disposable): Der gesamte HTML-Baum (index.html, classes/, namespaces/, modules/, services/) und alle lokalisierten Sprachbäume (en/, es/, pt/, fr/, ru/, ar/, hi/, ko/, zh/, nl/).
• Arbeits- und Cache-Produkte: PDF-Cache (_src/spec/pdf-cache/), output/ sowie Ausführungs- und Protokollarchive unter output/run-archive/.

3. Pipeline-Artefaktklassen

Folgende Einheiten fließen durch die Verarbeitungsstufen der Pipeline:

• Spec-Records: Strukturierte Datensätze der normativen Anforderungen und Typen mit stabiler kanonischer Identität (AUTOSAR/AP/record/SWS_... bzw. ECLIPSE/S-CORE/...).
• Review- & Kurations-Objekte: Diskrete Flags und Vorschläge (curation-item@v1) für menschliche Prüfungen und Korrekturen.
• Agent-Instruktionen: Formale Vorgaben für KI-Werkzeuge, die dem gleichen Revisions- und Kurationsprozess unterliegen wie Spezifikationsinhalte.
• i18n-Segmente & Batches: Extrahierte Textblöcke und Übersetzungseinheiten für die 10 Zielsprachen.
• Diagramme: Grafische Modelle (Graphviz DOT und Sequenzdiagramme) mit automatischer sprachspezifischer Textanpassung.
• Seitenmodelle: Kompositionsvorlagen unter _src/sources/pages/*.json zur Strukturierung der HTML-Ausgabe.
• Berichte: Statische und maschinenlesbare Protokolle zu Extraktion, Traceability, Validierungsbefunden und Qualitätskennzahlen.
• Runner-Laufpaare: Archivierte run.sh-Skripte und .log-Dateien zur exakten Rekonstruktion jedes Build-Laufs. Die Backlog-Buchführungs- und Commit-Evidenz bewahrt die zugehörigen Status-, Diff-, Commit- und REF-Nachweise in aufgabenspezifischen Laufverzeichnissen.

3.1 Review- und Feedback-Prozesse

Die Plattform bietet zwei getrennte, klar abgegrenzte Interaktionswege für Qualitätssicherung und Korrekturen:

Speicherung, Identität und Datenschutz

Beide Prozesse laufen datensparsam und isoliert im Browser (localStorage):

• ara-review-package-v1: Zwischenspeicher für gesammelte Freigaben des Curator-Panels.
• ara-review-github-token-v1: Optionaler GitHub-Token für authentifizierte Einreichungen (wiederverwendet zwischen beiden Dialogen).
• ara-review-identity: Selbstgewählter Name bei nicht-authentifizierten Einreichungen.
• Keine Cookies, kein Tracking und keine serverseitige Speicherung unvollständiger Formulardaten.

4. Mehrsprachigkeit (i18n): Extraktion, Übersetzung & Merge

Die Internationalisierung erfolgt über eine deterministische JSONL-Pipeline:

1. Extraktion: python3 _src/i18n_extract.py extrahiert alle neuen und geänderten Textsegmente aus den kanonischen deutschen Quellen und weist ihnen stabile IDs zu.
2. Übersetzung: Übersetzung der Segmente in die 10 Zielsprachen (en, es, pt, fr, ru, ar, hi, ko, zh, nl). Code-Fragmente, Bezeichner und Platzhalter-Token bleiben dabei geschützt und unverändert.
3. Merge: _src/i18n_translate.py merge führt die übersetzten Segmente mit dem Quellbestand zusammen und meldet fehlende oder unvollständige Übersetzungen.

Nicht übersetzte Segmente fallen im generierten Sprachbaum automatisch auf die deutsche Originalfassung zurück.

5. Diagrammübersetzung

Diagramme werden aus .dot- und .seq.json-Quellen erzeugt. Die darin enthaltenen Beschriftungen werden wie normaler Text extrahiert, übersetzt und beim Build sprachspezifisch in die generierten Diagramme eingesetzt. Dadurch liegen alle Diagramme in allen 10 Sprachen konsistent vor.

6. HTML-Generierung

Der Generator _src/generate.py transformiert die Seitenmodelle (_src/sources/pages/*.json) und Spezifikations-Records in statische HTML-Seiten. Für jede Sprache wird ein vollständiger, in sich geschlossener HTML-Baum erzeugt. Der Aufruf erfolgt über:

python3 _src/generate.py --lang=all

7. Validierung & Qualitätsprüfung

Vor einer Veröffentlichung prüft _src/validate.py das Gesamtergebnis auf Konsistenz:

• Prüfung aller internen und externen Links sowie Anker.
• Prüfung auf verwaiste Seiten oder fehlende Referenzen.
• Überprüfung der Namespace-Zugehörigkeiten und Signaturkonsistenz.
• Kontrolle der i18n-Vollständigkeit und Erkennung unbeabsichtigter Sprachmischungen.

Ein Exit-Code ungleich 0 blockiert den Release-Schritt und erzwingt die Korrektur der zugrundeliegenden Quellen.

8. Berichte, Traceability & Ausführungs-Archive

Die Dokumentation stellt dedizierte Auswertungsseiten bereit, um den Zustand der Datenbasis transparent zu machen:

• Build- & Publikations-Bericht: Aggregierte Kennzahlen, Validierungs-Befunde und Traceability-Metadaten des letzten Veröffentlichungslaufs.
• Zentraler Kurations-Bericht: Status aller offenen und entschiedenen Review- und Kurationsentscheidungen über alle Warteschlangen.
• Extraktions-Berichte: Status und Abweichungsanalysen aus der Extraktion der normativen PDFs.
• Traceability-Bericht: Vollständige Rückverfolgbarkeit von Anforderungen über Review-Status bis zu den publizierten Elementen.
• Offene Reviews: Übersicht aller zur Kuration oder Prüfung anstehenden Punkte.
• Ausführungs-Archive: Über output/run-archive/run-<timestamp>-n<seq>.log und .sh lässt sich jedes generierte Artefakt auf den exakten Erzeugungslauf und dessen Konsolenausgabe zurückführen. Die Backlog-Buchführungs- und Commit-Evidenz ergänzt diese Laufarchive um direkte Status-, Diff-, Commit- und REF-Nachweise.

9. Fehlerbehandlung & Richtlinien

Abweichungen, Validierungsfehler oder Übersetzungslücken dürfen niemals direkt im generierten HTML gepatcht werden. Fehlerbehebungen erfolgen immer auf Ebene der autoritativen Quellen (_src/spec/ oder _src/sources/pages/), gefolgt von einer vollständigen Neugenerierung und Validierung. Ablehnungen (Rejects) in Übersetzungs-Batches müssen im Kurationsteam geprüft und neu zugeführt werden.

10. Weiterführende Dokumentation

Vertiefende technische Details zur Pipeline und den Werkzeugen befinden sich in den internen Projekthandbüchern:

• _src/WARTUNG.md — Wartungsanleitung und Standard-Befehle für Maintainer.
• _src/ARCHITEKTUR.md — Schichtenmodell, Erweiterungskonzepte und Komponentenarchitektur.
• _src/KONVENTIONEN.md — Gestalterische und sprachliche Richtlinien.
• docs/pipeline/*.md — Verbindliche Spezifikationen der Pipeline-Abläufe und Datenmodelle.