165 lines
4.7 KiB
Markdown
165 lines
4.7 KiB
Markdown
# CI-Policy v0.1 – Definition und Evaluierung für PASS/WARN/FAIL Entscheidungen
|
||
|
||
## Purpose
|
||
|
||
Formale Definition einer Continuous-Integration-Policy, die Gate-Entscheidungen aus Debug-Daten automatisiert und nachvollziehbar trifft.
|
||
|
||
**Problemstellung:** Bisherige Entscheidungslogik in CI-Gates war inkonsistent und interpretierbar. Ziel ist eine deterministische, testbare Policy, die WARN- und FAIL-Bereiche formal abgrenzt.
|
||
|
||
**Ziele:**
|
||
- Reduktion subjektiver Entscheidungen in CI-Ergebnissen
|
||
- Standardisierung der Kategorien PASS, WARN und FAIL
|
||
- Einführung maschinenlesbarer Regeldefinition für Gate-Entscheidungen
|
||
|
||
## Kontext & Hintergrund
|
||
|
||
Backtest-CSV-Daten (#20–#29) mit Debug-JSON-Ausgaben je Run
|
||
|
||
**Gruppierung:**
|
||
- pinned
|
||
- unpinned
|
||
|
||
**Trace-Metadaten / zusätzliche Tags:**
|
||
- margin
|
||
- decision
|
||
- flaky_flag
|
||
- subset_flipcount
|
||
- mischfenster_p95
|
||
|
||
**Domänenkontext:**
|
||
- Continuous Integration
|
||
- Automatisiertes Testen
|
||
- Qualitätssicherung von CI-Gates
|
||
|
||
**Motivation:**
|
||
- Formalisierung bisher intuitiver Gate-Entscheidungen
|
||
- Stabilisierung der Bewertung von knappen Testergebnissen (Margin-Zone)
|
||
- Reduzierung von Flip-Flops zwischen Runs durch konsistente Regeln
|
||
|
||
## Methode / Spezifikation
|
||
|
||
**Übersicht:**
|
||
- Die Policy nutzt Metriken aus Debug-JSON zur Festlegung deterministischer Entscheidungen in CI-Läufen.
|
||
- Regeln sind in YAML definiert, maschinenlesbar und unit-testbar.
|
||
|
||
**Algorithmen / Verfahren:**
|
||
- PASS → allow
|
||
- WARN → allow + label + Auto-Rerun
|
||
- FAIL → block
|
||
- WARN wird getriggert, wenn Margin-Zone oder flaky_flag zutrifft
|
||
|
||
### Bootstrap-Übersicht
|
||
|
||
Nicht anwendbar – deterministische Regelbewertung, kein Resampling.
|
||
|
||
**Zielgrößen:**
|
||
## Input / Output
|
||
|
||
### Input-Anforderungen
|
||
|
||
**Hardware:**
|
||
**Software:**
|
||
- Python >=3.8
|
||
- YAML Parser
|
||
- CI-System (z. B. GitHub Actions, Jenkins)
|
||
|
||
**Konfiguration:**
|
||
- Integration der YAML-Policy in CI-Pipeline als Validierungsstufe
|
||
|
||
### Erwartete Rohdaten
|
||
|
||
**Felder pro Run:**
|
||
- timestamp
|
||
- run_id
|
||
- decision
|
||
- margin
|
||
- flaky_flag
|
||
- subset_flipcount
|
||
- mischfenster_p95
|
||
|
||
**Formatbeispiele:**
|
||
- 2024-02-10T08:33:20Z, run_020, WARN, 0.04, true, 1, 0.87
|
||
|
||
**Trace-Daten:**
|
||
- Format: JSON
|
||
- Hinweis: Debug-JSON pro Run liefert Basisdaten für Policy-Entscheidung
|
||
|
||
### Analyse-Ausgaben
|
||
|
||
**Pro Gruppe / pro Governor:**
|
||
**Vergleichsausgaben:**
|
||
|
||
- Trace-Muster: Analyse von WARN-Raten im Zeitverlauf als Indikator für Policy-Drift
|
||
|
||
## Workflow / Nutzung
|
||
|
||
**Analyse-Workflow:**
|
||
- Debug-JSONs aus CI-Runs sammeln.
|
||
- Policy auf Debug-JSON anwenden, Entscheidung ableiten.
|
||
- Per Run eine Zeile als Report-Artefakt schreiben.
|
||
- Mittlere WARN-Rate überwachen, Threshold-basierte Alarme setzen (z. B. >30% über 20 Runs).
|
||
|
||
### Trace-Template-Anforderungen
|
||
|
||
**Ziel:** Einheitliche Auswertungskriterien für alle CI-Runs.
|
||
|
||
**Erforderliche Tags & Metadaten:**
|
||
- margin
|
||
- flaky_flag
|
||
- decision
|
||
|
||
**trace-cmd-Setup:**
|
||
- Policy automatisch im Post-Test-Step ausführen
|
||
- Ergebnis als CSV-Zeile im Artefaktordner speichern
|
||
|
||
**Run-Design für Contributors:**
|
||
- Jeder Commit löst einen CI-Run aus
|
||
- Policy bewertet Run-Ergebnisse deterministisch
|
||
- WARN-Runs werden automatisch rerunnt
|
||
|
||
## Interpretation & erwartete Ergebnisse
|
||
|
||
**Kernbefunde:**
|
||
- pinned-Runs bleiben stabil im PASS/WARN-Bereich
|
||
- unpinned-Runs tragen Hauptanteil der WARN-Entscheidungen
|
||
- keine Fehlklassifikation durch Margin-Anpassung
|
||
- kritische Flip-Flops werden formal eliminiert
|
||
|
||
**Implikationen für Experimente:**
|
||
- Policy-Design verbessert Konsistenz und Nachvollziehbarkeit von Gate-Entscheidungen
|
||
- Automatische Reruns reduzieren unnötige FAIL-Blöcke
|
||
- Drift-Monitoring erlaubt langfristige Quantifizierung der Policy-Stabilität
|
||
|
||
**Planungsziel:**
|
||
- Ziel: Evaluiere Stabilität und Drift der Policy durch fortlaufende CI-Metrikerfassung.
|
||
- Vorgehen:
|
||
- Messung der WARN-Rate über sequenzielle Runs
|
||
- Schwellwert-Alarmierung bei Policy-Drift
|
||
|
||
## Limitationen & Fallstricke
|
||
|
||
**Datenbezogene Limitationen:**
|
||
- Backtest-Datensatz ist statisch; neue Laufdaten können abweichende WARN-Verteilungen zeigen
|
||
|
||
**Kausalität & Generalisierbarkeit:**
|
||
- Policy-Validität hängt von Stabilität der zugrundeliegenden Metriken ab
|
||
|
||
**Praktische Fallstricke:**
|
||
- Zu enge Margins können unnötige WARNs erzeugen
|
||
- Fehlerhafte flaky_flag-Erkennung beeinflusst Ergebnisqualität
|
||
|
||
## Nächste Schritte & Erweiterungen
|
||
|
||
**Geplante Experimente:**
|
||
- Implementierung eines Policy-Drift-Monitors zur Überwachung von WARN-Raten
|
||
|
||
**Analyseziele:**
|
||
- Langzeitstatistik von PASS/WARN/FAIL
|
||
- Analyse saisonaler Schwankungen in flaky_flag-Raten
|
||
|
||
**Regression & Modellierung:**
|
||
- Evaluierung einer adaptiven Margin-Zone basierend auf historischen Stable-Runs
|
||
|
||
**Community-Beiträge:**
|
||
- Open-Source-Veröffentlichung der YAML-Policy und CI-Runner-Integration
|
||
- Feedback-Sammlung zu WARN-Interpretation (soft fail vs. block with rerun)
|