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).
  • Nach einem Doppelpunkt beginnt ein neuer Hauptsatz mit Grossbuchstaben (z. B. Hinweis: Diese Regel ist verbindlich).
  • 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.

Glossar-Abschnitt auf Fachseiten (verbindlich)​

  • Fachseiten mit ## Glossar-Begriffe nutzen ein einheitliches Listenmuster analog /docs/orchestration-prefect/data-pipeline.
  • Jeder Listenpunkt enthält: Link auf /docs/platform/glossary#<id> + kurzer Kontext nach –.
  • Nur vorhandene Glossar-IDs verwenden (keine toten Anchors wie #hpo, #backtesting oder #label, wenn sie im Glossar nicht existieren).
  • Vollstaendigkeit pro Seite sicherstellen: Mindestens die zentralen Prozessbegriffe, Governance-Begriffe (z. B. DQ, Lineage, Output Contract) und verwendeten Tool-Begriffe (z. B. Prefect, MLflow) aufnehmen.
  • Bei Terminologieaenderungen zuerst site/docs/00-platform/glossary.mdx aktualisieren, danach Fachseiten nachziehen.
  • Vor Commit immer pnpm run link-check ausfuehren und fehlerhafte Glossar-Links beheben.

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.

UI-Token-Guardrails (verbindlich)​

  • Keine freien Pixel-/Rem-Werte für neue UI-Typografie, Spacing-Feinschritte und Motion in CSS-Modulen oder Inline-Styles definieren.
  • Vor neuer UI-Zahl zuerst prüfen, ob ein bestehender Token in site/src/css/custom.css passt; falls nein, Token dort ergänzen und wiederverwenden.
  • Hover/Focus/Press-Transitions für Buttons, Cards, Sidebar-Links und Search-Resultate nur über die Motion-Tokens steuern (--motion-fast, --motion-base, --easing-*, --transition-*).
  • Für breite Markdown-Tabellen (z. B. Traceability Matrix, Glossary) standardmaessig table-pattern--compact verwenden; Ziel: Maximale Sichtbarkeit ohne sofortiges Rechts-Scrollen.

Design-only QA-Checkliste für Theme-Lesbarkeit (verbindlich)​

Diese Checkliste gilt zusätzlich für alle Design-only Änderungen (Styling, Tokens, Komponenten-UI, visuelle Refactors ohne fachliche Inhaltsänderung).

Pflichtbereiche (Light + Dark)​

  • Fliesstext: Primärer Text ist durchgehend gut lesbar, ohne graue „Low-Contrast“-Abschnitte.
  • Sekundärer Text: Meta-/Hilfstexte bleiben klar erkennbar und kippen im Dark Mode nicht zu nahe an den Hintergrund.
  • Links: Standard-, Hover- und besuchter Zustand sind unterscheidbar; Linkfarbe wirkt nicht wie normaler Fliesstext.
  • Callouts: Titel, Body-Text, Border und Hintergrund bleiben pro Variante (Info/Success/Warning) klar differenziert.
  • Tabellen: Kopfzeile, Zelleninhalt und Trennlinien sind im Kontrast stabil; Stripe-Row bleibt lesbar.
  • Hero: Headline, Tagline, Lead und CTA (inkl. Hover/Focus) sind in beiden Themes gut lesbar.
  • Search-Seite: Trefferlisten, Labels, Treffer-Metadaten und Interaktionszustände bleiben kontraststabil.
  • BPMN-Viewer: Overlay, Header, Trennlinien, Buttons, Disabled-States und Zoom-Anzeige sind konsistent lesbar.

Interaktions- und Status-Prüfpunkte​

  • Chips/Badges: Text und Hintergrund je Variante haben ausreichenden Kontrast.
  • Hover/Focus: Interaktive Elemente besitzen sichtbaren Hover- und :focus-visible-State.
  • Statusfarben: Semantische Farben (Info/Success/Warning/Error) bleiben semantisch erkennbar und kontraststabil.

Mindestanforderung für UI-Code​

  • Keine neuen Hardcoded-Farben in UI-Dateien (TSX/CSS-Module/MDX-Styles), ausser es gibt eine begründete Ausnahme im PR mit kurzer Begründung, Scope und Folgetask zur Tokenisierung.

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.