Zum Hauptinhalt springen

Contributor Guide: Link-, Routing- und Quality-Konvention

Ziel​

Diese Seite definiert verbindliche Arbeitsregeln für Content-PRs, damit Navigation, BPMN-Drilldowns, fachliche Nachvollziehbarkeit und CI-Checks dauerhaft stabil bleiben.

Verbindliche Sprachregel​

  • Es darf kein Eszett verwendet werden (immer ss).
  • Gilt für Fliesstext, Tabellen, Callouts, UI-Labels mit redaktionellem Charakter und Review-Anmerkungen.
  • Ausnahmen nur bei explizit gekennzeichneten Originalzitaten/Drittinhalten.

Terminologie-Governance (verbindlich)​

  • Das Glossar ist die einzige verbindliche Referenz für Begriffe in concepts.md, der Traceability-Matrix und den Tool-Kapiteln.
  • Jeder Glossarbegriff besitzt einen klaren fachlichen Scope, einheitliche Schreibweise und bei Bedarf explizite Ausschlussbegriffe („nicht verwenden“).
  • Jede BPMN-Entscheidung und jedes Tool-Artefakt (OpenMetadata, Prefect, MLflow) verwendet dieselben kanonischen Begriffe.
  • Änderungen an Begriffen erfolgen versioniert im Glossar, bevor sie in Prozess- oder Tooldokumentation verwendet werden.
  • Begriffe bei Erstnennung innerhalb einer Seite auf den entsprechenden Glossareintrag verlinken.
  • Keine abweichenden Synonyme in Prozess- oder Toolseiten verwenden, ohne vorheriges Glossar-Update.
  • Tool-spezifische Begriffe nur mit Kontext verwenden (z. B. MLflow Model Version vs. Registry Stage).
  • Bei Review von Doku-PRs ist die Konsistenz zwischen Glossar, concepts.md und traceability-matrix.md Pflichtkriterium.

Verbindliche Route-Strategie​

  • Öffentliche Routen sind sprechend und ohne numerische Präfixe: /docs/<domain>/<page>.
  • Numerische Ordnerpräfixe (00- bis 09-) bleiben intern für Strukturierung.
  • Jede Doc-Seite benötigt einen expliziten slug im Frontmatter.
  1. In Navbar/Footer nur feste to: '/docs/<domain>/<page>'-Routen.
  2. In Markdown/MDX dieselbe Kurzroute (/docs/...) statt relativer Dateipfade.
  3. In BPMN-<bpmn:documentation> ausschliesslich /docs/... oder NO_DOC_LINK: <Grund>.
  4. BPMN-Dateien als statische Assets unter /bpmn/*.bpmn referenzieren.

Verbindlicher Autorenworkflow​

  1. Inhaltliche Änderung vornehmen und Pflichtabschnitte vollständig ausfüllen.
  2. Placeholder entfernen (TODO, TBD, Vorlagen-Sätze, Dummy-Listen).
  3. Begriffe und Rollen gegen Glossary prüfen.
  4. BPMN-/Prozessbezug gegen Traceability Matrix prüfen.
  5. pnpm run link-check ausführen und alle Findings beheben.
  6. Optional pnpm run build für zusätzliche Link-/Routing-Validierung.

BPMN-Kontext und Traceability (verbindlich)​

Bei Seiten, die in site/docs/00-platform/traceability-matrix.md als Zielseite geführt werden, gilt zusätzlich:

  1. Abschnitt ## BPMN-Kontext pflegen mit BPMN-IDs sowie Input-/Entscheidungs-/Output-Bezug.
  2. Gate-Logik nicht redundant verteilen; zentrale Entscheidungslogik verlinken (aktuell /docs/research-risk/acceptance-criteria).
  3. Status in der Traceability-Matrix konsistent aktualisieren (Abgedeckt/Gap).
  4. Für Knoten ohne eigene Seite die NO_DOC_LINK-Regel konsequent anwenden.

Review-Checklist für BPMN-bezogene Doku-PRs (Pflicht)​

Jeder Doku-PR, der Prozesslogik, Rollen, Evidenzen oder Eskalationen in der Traceability Matrix verändert, muss vor dem Merge folgende Punkte erfüllen:

  • Alle geänderten BPMN-Knoten sind in der Matrix identifiziert und referenziert.
  • Zielseite verweist auf die fachlich richtige Seite unter site/docs/**.
  • Artefakte/Evidenz ist prüfbar und auditfähig beschrieben.
  • Eskalationspfad ist eindeutig (Owner + nächstes Eskalationslevel).
  • Offene Gap-Punkte sind entweder geschlossen oder im PR explizit als Folgearbeit begründet.
  • Schweizer Rechtschreibung eingehalten (ss, kein Eszett) oder verbleibende Originalzitate explizit markiert.

Workflow für Matrix-Änderungen:

  1. Betroffene BPMN-Knoten in der Matrix identifizieren.
  2. Zielseite, Rolle, Evidenz und Eskalationspfad prüfen/aktualisieren.
  3. Alle Gap-Einträge entweder schliessen oder im PR explizit begründen.

Definition of Done für Content-PRs (verbindlich)​

Ein Content-PR ist nur „Done“, wenn alle folgenden Punkte erfüllt und im PR nachvollziehbar sind:

  1. Template-frei: Keine Platzhalter, keine vorbefüllten Dummy-Abschnitte, keine unkonkreten Aussagen.
  2. BPMN-referenziert: Bei prozessnahen Änderungen sind betroffene BPMN-Knoten genannt und auf Zielseiten/Matrix abgestimmt.
  3. Messbare Akzeptanzkriterien: Aussagen sind prüfbar (Schwellwerte, SLOs, Pass/Fail-Regeln, klare Rollen).
  4. Traceability vollständig: Glossary- und Traceability-Verlinkung vorhanden, Evidenzpfade benannt.
  5. CI-konform: pnpm run link-check erfolgreich.

Messbare Akzeptanzkriterien (Mindestset)​

  • 0 Placeholder-Marker in geänderten Seiten.
  • 0 fehlerhafte /docs/...-Links laut pnpm run link-check.
  • Für jede prozessrelevante Seite: 1 Abschnitt ## BPMN-Kontext mit allen 3 Bezügen (Input/Entscheidung/Output).
  • Für jede Datenseite: Data-Contract-, Versionierungs- und Incident-Abschnitt vorhanden.

CI-Absicherung​

  • onBrokenLinks: 'throw' im Docusaurus-Config bricht Build bei defekten gerenderten Links.
  • pnpm run link-check prüft statisch:
    • Frontmatter + slug je Docs-Seite,
    • Konsistenz fester /docs/...-Links in TS/MD/MDX/JSON,
    • BPMN-Drilldown-Links in site/static/bpmn/*.bpmn,
    • referenzierte BPMN-Assets (/bpmn/...) in Dokumenten.

Siehe auch: BPMN-Linking Richtlinie, Local Setup, Adding Pipeline.

Deploy-Pipeline (Single Source of Truth)​

CI/CD Overview (Source of Truth)​

  • Deploy ist image-basiert: GitHub Actions baut und pusht nach GHCR; die Prod-VM pullt nur Images (kein Build auf der VM).
  • Verbindlicher Workflow: .github/workflows/publish-mlprojektdocs.yml.
  • Image-Pattern (immer lowercase): ghcr.io/<owner>/<repo>, z. B. ghcr.io/optimorum/mlprojektdocs.
  • Erwartete Tags: main und sha-<commit>.
  • Wichtig: GHCR/Docker akzeptiert Image-Namen nur lowercase.

Was triggert Deploy?​

  • Push/Merge auf main.
  • Zusätzlich muss mindestens eine Datei unter site/** oder die Workflow-Datei selbst geändert sein (entsprechend on.push.paths).

Wann muss der Workflow angepasst werden? (Coupling Points)​

  • site/ wurde umbenannt/verschoben: context und file im Build-Step anpassen.
  • Standard-Branch wechselt von main auf einen anderen Branch: Trigger anpassen.
  • Dockerfile-Pfad oder -Name ändert sich.
  • Node- oder Package-Manager-Wechsel beeinflusst den Docker-Build.
  • Registry, Image-Namensschema oder Tagging-Konzept ändert sich.
  • Repo-/Org-Setting Workflow permissions kann GITHUB_TOKEN einschränken (insb. Package write). Referenz: GitHub Actions Workflow Syntax – permissions.

Lokal testen (Developer Loop)​

  • Schnell (Docusaurus dev server):
    • cd site && pnpm install && pnpm start
  • Wie Prod (Container-Build):
    • docker build -t mlprojektdocs:local ./site
    • docker run -p 8085:80 mlprojektdocs:local

Prod-Update-Mechanik​

  • Manuell (kontrolliert):
    • docker compose pull && docker compose up -d
  • Automatisch (Watchtower):
    • Watchtower pollt in Intervallen (typisch 5–15 min) neue Images, pullt Updates und startet betroffene Container neu.