From d72dcbacfbf454e147d1fad5ac06ffeabf2dbd29 Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Sat, 27 Jun 2026 06:51:00 +0200 Subject: [PATCH] docs(adr): ADR-001 Runtime Deploy Policy A dev deploy must always have a verifiable runtime effect. Deploy only on runtime/API/data-model/reasoning/security changes; docs, reference suites, ADRs, board and ownership texts are merged to origin/main but NOT pushed to dev (no Orca build). Keeps the CI/CD history meaningful: every build == a runtime change. Architecture/release decision (not a developer convention) -> own folder docs-src/architecture/adr/. Non-runtime: this commit triggers no deploy, per its own policy. Co-Authored-By: Claude Opus 4.7 --- .../adr/ADR-001-runtime-deploy-policy.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs-src/architecture/adr/ADR-001-runtime-deploy-policy.md diff --git a/docs-src/architecture/adr/ADR-001-runtime-deploy-policy.md b/docs-src/architecture/adr/ADR-001-runtime-deploy-policy.md new file mode 100644 index 00000000..f5204bb0 --- /dev/null +++ b/docs-src/architecture/adr/ADR-001-runtime-deploy-policy.md @@ -0,0 +1,63 @@ +# ADR-001: Runtime Deploy Policy + +- **Status:** Accepted +- **Datum:** 2026-06-27 +- **Typ:** Architektur-/Release-Entscheidung (keine Entwicklerkonvention) + +## Kernsatz + +> Ein dev-Deploy muss immer einen verifizierbaren Runtime-Effekt haben. +> +> Auf die Frage „warum wurde dieser Build ausgelöst?" muss die Antwort immer lauten können: „weil sich das Laufzeitverhalten geändert hat." + +## Kontext + +Der dev-Deploy (Orca) wird durch einen Push auf den `gitea`-Remote (`gitea.meghsakha.com`) +ausgelöst und baut das Backend als amd64-Image (~5–15 min). In der Praxis entstehen regelmäßig +Änderungen **ohne** Laufzeit-Effekt: Dokumentation, Architekturtexte, Ownership-Modelle, +Koordinations-/Board-Dateien und Referenzartefakte (z. B. die Reference Scenario Suite unter +`backend-compliance/reference_scenarios/`, die vom Backend nicht importiert wird). + +Würde jeder solche Commit deployt, verliert die CI/CD-Historie ihre Aussagekraft: Ein Build +entspräche dann nicht mehr eindeutig einer Laufzeit-Änderung, und die Frage „warum wurde dieser +Build ausgelöst?" ließe sich nicht mehr verlässlich beantworten. + +## Entscheidung + +**Ein dev-Deploy (Orca-Build) wird nur ausgelöst, wenn die Änderung einen verifizierbaren +Laufzeit-Effekt hat.** + +Deployen, wenn **mindestens eines** zutrifft: + +- Runtime-Code geändert +- öffentliche API geändert (Pfad/Methode/Status/Request-/Response-Schema) +- Datenmodell geändert +- Reasoning-Verhalten geändert +- Sicherheitsfix + +**Nicht** deployen bei (nicht abschließend): + +- Dokumentation +- Reference Suites (z. B. `backend-compliance/reference_scenarios/`) +- ADRs (inkl. dieser) +- Board-/Koordinationsdateien +- Ownership-/Architektur-Texte + +Solche Änderungen werden auf `origin/main` gemergt (via PR, **kein** direkter Push), aber **nicht** +auf den `gitea`-Remote gepusht. `origin/main` darf dem dev-Stand damit vorauslaufen; die Parität +wird beim nächsten echten Runtime-Schnitt mitgezogen. + +## Konsequenzen + +- Die CI/CD-Historie bleibt aussagekräftig: jeder Build entspricht einer Laufzeit-Änderung. +- Build-Zeit und Ressourcen werden gespart. +- `origin/main` (Source of Truth) und dev (Laufzeit) dürfen temporär divergieren — das ist + **beabsichtigt und kein Defekt**. Der `last-build/main`-Tag auf dem `gitea`-Remote bezeichnet den + zuletzt deployten Runtime-Stand. +- Vor jedem Push auf `gitea` ist zu prüfen, ob der Diff einen Laufzeit-Effekt hat. + +## Beispiel + +Die Reference Scenario Suite v1 (`8a51db92`) und das Ownership-Dokument +`session_ownership_model_v1.md` (`c7339e68`) wurden auf `origin/main` gemergt, aber bewusst **nicht** +auf dev deployt — beide ohne Laufzeit-Effekt. Diese ADR selbst fällt unter dieselbe Regel.