Add rollout_criteria/README.md
This commit is contained in:
commit
709f797aa1
1 changed files with 158 additions and 0 deletions
158
rollout_criteria/README.md
Normal file
158
rollout_criteria/README.md
Normal file
|
|
@ -0,0 +1,158 @@
|
||||||
|
# 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.
|
||||||
Loading…
Reference in a new issue