158 lines
4.9 KiB
Markdown
158 lines
4.9 KiB
Markdown
# Rollout-Kriterien für Gate‑V1 im CI‑System
|
||
|
||
## Purpose
|
||
|
||
Festlegung der Rollout-Kriterien und Entscheidungslogik für den Gate‑V1‑Step im Continuous Integration (CI).
|
||
|
||
**Problemstellung:** Fehlende standardisierte Entscheidungskriterien bei der Integration von Gate‑V1 in automatisierte CI‑Pipelines.
|
||
|
||
**Ziele:**
|
||
- Operationelle Einführung von Gate‑V1 als CI‑Step
|
||
- Definition von Bewertungs- und Eskalationslogik (PASS, WARN, REVIEW)
|
||
- Dokumentation der stabilen Rollout-Phasen und Schwellenwerte
|
||
|
||
## Kontext & Hintergrund
|
||
|
||
Die Gate‑V1‑Komponente wertet Metriken aus den Policy-Berechnungen aus und erzeugt daraus ein `gate_result.json`.
|
||
|
||
**Gruppierung:**
|
||
- pro CI‑Run
|
||
- pro Policy‑Set
|
||
|
||
**Trace-Metadaten / zusätzliche Tags:**
|
||
- policy_hash zur Nachverfolgbarkeit der Policy-Konfiguration
|
||
|
||
**Domänenkontext:**
|
||
- CI‑Workflows
|
||
- kontinuierliche Qualitätssicherung
|
||
- automatisierte Policy‑Validierung
|
||
|
||
**Outlier-Definition:**
|
||
- Methode: Schwellenwertbasiert
|
||
- Beschreibung: Runs mit Unknown‑Rate > 1 % werden als Ausreißer und REVIEW‑Fälle markiert.
|
||
- Metrik: Unknown‑Rate
|
||
|
||
**Motivation:**
|
||
- Transparente, nachvollziehbare Entscheidungen in CI‑Pipelines
|
||
- Konsistentes Evaluationsverhalten über mehrere Runs hinweg
|
||
- Reduktion des log‑basierten manuellen Prüfaufwands
|
||
|
||
## Methode / Spezifikation
|
||
|
||
**Übersicht:**
|
||
- Der Gate‑V1‑Step erhält `policy_constants.json` und den daraus berechneten `policy_hash`.
|
||
- Er erzeugt ein `gate_result.json` mit Outcome, Hash, Count‑Metriken und Top‑Reasons.
|
||
- Er ergänzt den CI‑Lauf um einen kompakten PR‑Kommentar mit diesen Daten.
|
||
|
||
**Algorithmen / Verfahren:**
|
||
- Ermitteln der Unknown‑, WARN‑ und Sichtbarkeitsraten aus Policy‑Ergebnissen.
|
||
- Zuweisung eines Outcomes (PASS, WARN, REVIEW) anhand fester Schwellen.
|
||
- Speichern der Resultate in `gate_result.json`.
|
||
- Posten eines standardisierten CI‑Kommentars mit Hash, Outcome und Begründung.
|
||
|
||
## Input / Output
|
||
|
||
### Input-Anforderungen
|
||
|
||
**Hardware:**
|
||
**Software:**
|
||
- CI‑Umgebung mit JSON‑Support
|
||
- Zugriff auf Policy‑Auswertungsartefakte
|
||
|
||
**Konfiguration:**
|
||
- Bereitstellung von `policy_constants.json`
|
||
- Berechnung eines stabilen `policy_hash`
|
||
|
||
### Erwartete Rohdaten
|
||
|
||
**Felder pro Run:**
|
||
- policy_hash
|
||
- outcome
|
||
- unknown_rate
|
||
- visibility
|
||
- top_reasons
|
||
|
||
**Formatbeispiele:**
|
||
- {"policy_hash": "abcd1234", "outcome": "PASS", "unknown_rate": 0.009, "visibility": 0.995, "top_reasons": ["Sichtbarkeit ≥99%", "Unknown ≤1%"]}
|
||
|
||
**Trace-Daten:**
|
||
- Format: JSON
|
||
- Hinweis: Keine Zusatzfelder oder Telemetrie; minimalistische Struktur für diff‑basierte Vergleiche.
|
||
|
||
### Analyse-Ausgaben
|
||
|
||
**Pro Gruppe / pro Governor:**
|
||
- Unknown‑Rate
|
||
- Visibility‑Wert
|
||
- Warn‑Rate
|
||
|
||
- Trace-Muster: Stabilität des `policy_hash` über wiederholte Runs prüfen.
|
||
|
||
## Workflow / Nutzung
|
||
|
||
**Analyse-Workflow:**
|
||
- Ausführen des Gate‑V1‑Steps in der CI‑Pipeline.
|
||
- Erzeugen des `gate_result.json`.
|
||
- Kommentieren des PRs mit kompaktem Ergebnisblock.
|
||
- Bewerten der Resultate über mehrere Runs.
|
||
|
||
### Trace-Template-Anforderungen
|
||
|
||
**Ziel:** Stabilität und Nachvollziehbarkeit der CI‑Ergebnisse.
|
||
|
||
**Erforderliche Tags & Metadaten:**
|
||
- policy_hash
|
||
- outcome
|
||
- Counts‑Metriken (Unknown, Visibility, etc.)
|
||
|
||
**trace-cmd-Setup:**
|
||
- Keine zusätzlichen Tracepunkte im comment‑only‑Modus.
|
||
|
||
**Run-Design für Contributors:**
|
||
- Mindestens zwei Run‑Kategorien (Baseline, Degradiert).
|
||
- Kein Parameter‑Tuning während der Validierung.
|
||
|
||
## Interpretation & erwartete Ergebnisse
|
||
|
||
**Kernbefunde:**
|
||
- PASS bei stabiler Unknown‑Rate ≤1 % und Sichtbarkeit ≥99 %.
|
||
- REVIEW bei erhöhter Unknown‑Rate.
|
||
- Byte‑stabile Resultate zwischen Runs sind Indikator funktionaler Stabilität.
|
||
|
||
**Implikationen für Experimente:**
|
||
- Gate‑V1 kann reproduzierbare und erklärbare CI‑Entscheidungen liefern.
|
||
- Die Unknown‑Kategorie dient als Trigger für manuelle Prüfung.
|
||
|
||
**Planungsziel:**
|
||
- Ziel: Schrittweiser Rollout des Gate‑Mechanismus mit sicherer Eskalationslogik.
|
||
- Vorgehen:
|
||
- Phase 1: comment‑only
|
||
- Phase 2: WARN‑Gate bei definierten Kriterien
|
||
- Option 3: blockend mit harten Bedingungen
|
||
|
||
## Limitationen & Fallstricke
|
||
|
||
**Datenbezogene Limitationen:**
|
||
- Abhängigkeit von Genauigkeit der Policy‑Metriken.
|
||
- Keine Datenvalidierung außerhalb der definierten Counts.
|
||
|
||
**Kausalität & Generalisierbarkeit:**
|
||
- Bewertungen gelten nur für getestete Policy‑Konfigurationen.
|
||
|
||
**Praktische Fallstricke:**
|
||
- Falsche Unknown‑Klassifizierung kann zu unnötigen REVIEWs führen.
|
||
- Hash‑Änderungen ohne sichtbare Policy‑Differenz erschweren Vergleichbarkeit.
|
||
|
||
## Nächste Schritte & Erweiterungen
|
||
|
||
**Geplante Experimente:**
|
||
- Einführung des WARN‑Gates nach stabilen 40 Runs.
|
||
|
||
**Analyseziele:**
|
||
- Quantifizierung der Unknown‑Rate‑Verteilung über längere Zeiträume.
|
||
|
||
**Regression & Modellierung:**
|
||
- Beobachtung der Outcome‑Verteilung über Policy‑Versionen hinweg.
|
||
|
||
**Community-Beiträge:**
|
||
- Best Practices für comment‑only Gates in CI‑Umgebungen dokumentieren.
|