Files

T

Benjamin Admin d72dcbacfb 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 <noreply@anthropic.com>

2026-06-27 06:51:00 +02:00

2.6 KiB

Raw Blame History

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.

2.6 KiB Raw Blame History Unescape Escape