docs: ADR-0024 — the three extended framework files, decided
AGENTS.md requires an ADR for every permanent exception: documenting one instead of deciding it is an error. schema.yaml, validate.py and gen_status.py have diverged from the vendored baseline since the migration on 2026-08-11, described in two places and decided in none. FB-12 named the gap during the v0.3.1 upgrade. A prefix comparison was measured and rejected: unlike AGENTS.md, these extensions are interleaved — component sits between issue and wiki-page, the two rules sit inside apply_rules, and gen_status replaces the issue table rather than appending to it. The honest price is in the consequences: the reconciliation on upgrade has no machine contradictor. Measured on this very case — upstream touched two of the three between v0.1.1 and v0.3.1 and nothing reported it.
This commit is contained in:
Thore Cimbal
@@ -450,8 +450,13 @@ Prüfungen macht.
|
||||
Löschung bleiben gesperrt, nur der Zugang ist erlaubt. Vier Kontrollen belegt. Upstream
|
||||
`check_locked.py` zieht dieselbe Grenze und sichert sie zu — unsere Fassung wusste es
|
||||
nur nicht.
|
||||
- **Punkt 3 ist offen.** Der Abgleich ist gemacht und in `HERKUNFT.md` protokolliert, aber
|
||||
beim nächsten Upgrade erinnert nichts daran.
|
||||
- **Punkt 3 ist entschieden, aber nicht behoben.** Der Abgleich ist gemacht und in
|
||||
`HERKUNFT.md` protokolliert; seit dem 2026-08-21 trägt
|
||||
[ADR-0024](docs/adr/0024-drei-framework-dateien-erklaert-erweitert.md) die Ausnahme als
|
||||
Entscheidung statt nur als Beschreibung und nimmt den Abgleich ausdrücklich in die
|
||||
Upgrade-Pflicht auf. **Der maschinelle Widerspruch fehlt weiterhin** — beim nächsten
|
||||
Upgrade erinnert nur noch diese ADR daran, und das ist genau die Sorte Gedächtnis, der
|
||||
FB-11 nicht traut.
|
||||
|
||||
**Vorschlag für die nächste Iteration.** Zwei Dinge, beide klein:
|
||||
|
||||
|
||||
@@ -91,7 +91,7 @@ Bedeutung der Meilensteine: siehe [roadmap.md](roadmap.md).
|
||||
|
||||
_none active_
|
||||
|
||||
## ADRs (23)
|
||||
## ADRs (24)
|
||||
|
||||
| ADR | Status | Title |
|
||||
|---|---|---|
|
||||
@@ -118,6 +118,7 @@ _none active_
|
||||
| [0021](docs/adr/0021-foederation-geschlossen.md) | accepted | ADR-0021: Föderation wird geschlossen — leere Whitelist statt offener Tür |
|
||||
| [0022](docs/adr/0022-upstream-anschluss-durch-einmaligen-merge.md) | accepted | ADR-0022: Anschluss an Upstream durch einen einmaligen Merge, nicht durch einen geteilten Graft |
|
||||
| [0023](docs/adr/0023-fremdhistorie-von-der-git-hygiene-ausnehmen.md) | accepted | ADR-0023: Fremde Historie von der Git-Hygiene ausnehmen — erklärt, nicht global |
|
||||
| [0024](docs/adr/0024-drei-framework-dateien-erklaert-erweitert.md) | accepted | ADR-0024: Drei Framework-Dateien sind erklärt erweitert — Diff-Referenz statt Byte-Vergleich |
|
||||
|
||||
## Open AARs (6)
|
||||
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
type: adr
|
||||
id: "0024"
|
||||
status: accepted
|
||||
date: 2026-08-21
|
||||
supersedes: null
|
||||
superseded_by: null
|
||||
related:
|
||||
- "docs/design/done/2026-08-11-neckbeard-migration.md"
|
||||
- "docs/sources/upstream/neckbeard-v0.3.1/HERKUNFT.md"
|
||||
- "FRAMEWORK-BEFUNDE.md"
|
||||
---
|
||||
|
||||
# ADR-0024: Drei Framework-Dateien sind erklärt erweitert — Diff-Referenz statt Byte-Vergleich
|
||||
|
||||
## Kontext
|
||||
|
||||
Der Adoptionspfad des Rahmenwerks (`AGENTS.md` §5) verlangt, die
|
||||
übernommenen Framework-Dateien byte-genau gegen eine vendorierte Baseline
|
||||
zu halten. `scripts/pruefe_upstream_drift.py` tut das seit der Migration
|
||||
vom 2026-08-11 — für neun der zwölf vendorierten Artefakte.
|
||||
|
||||
Für drei geht es nicht, weil dieses Projekt Dinge braucht, die das
|
||||
Rahmenwerk nicht kennt. Gemessen gegen die aktuelle Baseline v0.3.1:
|
||||
|
||||
| Datei | Umfang | Was |
|
||||
|---|---|---|
|
||||
| `schema.yaml` | +51 / −9 Zeilen | Typ `component`; am Typ `issue` die Pflichtfelder `milestone` und `priority` sowie `area`, `due`, `gitlab_iid`, `host`, `projekt`, `wartegrund`; Status-Enum um `next`/`waiting` erweitert |
|
||||
| `scripts/validate.py` | +20 / −1 Zeilen | Regeln `waiting_requires_reason` und `slug_matches_filename`, dazu das WIP-Limit von 2 |
|
||||
| `scripts/gen_status.py` | +36 / −6 Zeilen | `STATUS.md` nach Meilenstein und Priorität gegliedert statt als flache Liste |
|
||||
|
||||
Diese Abweichung ist seit dem 2026-08-11 gelebte Praxis und an zwei
|
||||
Stellen beschrieben: in der Herkunftstabelle der Baseline als „erklärt
|
||||
projekterweitert — nur Diff-Referenz", und im Kopf der `schema.yaml`
|
||||
selbst. **Beschrieben, aber nie entschieden.** `AGENTS.md` §1 verlangt für
|
||||
jede dauerhafte Ausnahme von einer Regel eine ADR — *„eine Ausnahme nur zu
|
||||
dokumentieren statt sie zu entscheiden, ist ein Fehler."* Diese fehlte.
|
||||
[FB-12](../../FRAMEWORK-BEFUNDE.md) hat die Lücke beim Upgrade auf v0.3.1
|
||||
benannt.
|
||||
|
||||
## Optionen
|
||||
|
||||
**A: Alles byte-treu halten, Erweiterungen nur upstream einbringen.**
|
||||
Verworfen. Meilensteine und Prioritäten trugen 71 von 71 offenen Issues,
|
||||
bevor das Rahmenwerk das Konzept überhaupt kannte; es steht dort bis heute
|
||||
als offener Vorgang. Diese Option koppelt die Arbeitsfähigkeit dieses
|
||||
Repos an die Freigabekadenz eines anderen Projekts. Das Rahmenwerk selbst
|
||||
sieht das anders: Projektseitige Varianten sind dort ausdrücklich als
|
||||
„gepinnte Basis plus erklärte, diffbare Erweiterungen" vorgesehen.
|
||||
|
||||
**B: Still forken.** Verworfen ohne Diskussion — genau das ist der
|
||||
Zustand, den `pruefe_upstream_drift.py` verhindern soll. Die Frage von
|
||||
sorb, die zur Prüfung führte, lautete *„wird die AGENTS.md ggf. durch
|
||||
Agenten umgeschrieben?"*; eine unerklärte Abweichung beantwortet sie mit
|
||||
Ja.
|
||||
|
||||
**C: Präfix-Vergleich wie bei `AGENTS.md`.** Verworfen, und zwar
|
||||
nachgemessen: Bei `AGENTS.md` trägt der Upstream-Teil vorn und der
|
||||
Projektabschnitt hängt hinten an — ein Präfix-Vergleich greift. Bei diesen
|
||||
drei Dateien sind die Erweiterungen **eingewoben**: `component` steht
|
||||
zwischen `issue` und `wiki-page`, die beiden Regeln stehen *innerhalb* von
|
||||
`apply_rules`, und `gen_status.py` **ersetzt** die Issue-Tabelle, statt
|
||||
etwas anzuhängen. Ein Präfix-Vergleich wäre ab der ersten abweichenden
|
||||
Zeile rot und damit wertlos.
|
||||
|
||||
**D: Erklärte Erweiterung mit Diff-Referenz.** Die Baseline behält die
|
||||
unveränderten Originale, aber nicht als Byte-Maßstab, sondern als
|
||||
Vergleichsstand: Was wir geändert haben, ist jederzeit als Diff sichtbar.
|
||||
Die Herkunftstabelle sagt Datei für Datei, welche Prüfung gilt.
|
||||
|
||||
## Entscheidung
|
||||
|
||||
**Option D** (sorb, 2026-08-21, auf FB-12 hin). Damit ist die seit dem
|
||||
2026-08-11 gelebte Praxis erstmals entschieden statt nur beschrieben.
|
||||
|
||||
Verbindlich ist dabei:
|
||||
|
||||
- Die Ausnahme gilt für **genau diese drei Dateien**. Jede weitere
|
||||
Abweichung von der Baseline ist ein Fehler, bis sie eine eigene ADR hat.
|
||||
- **Maßgeblich ist die Tabelle in `HERKUNFT.md`** der jeweils gültigen
|
||||
Baseline. Sie und die Paarliste in `pruefe_upstream_drift.py` müssen
|
||||
sich decken; weicht eine von der anderen ab, ist die Prüfung falsch
|
||||
konfiguriert und nicht die Datei.
|
||||
- **Jede Erweiterung wird an ihrem eigenen Ort begründet**, nicht nur
|
||||
hier: `schema.yaml` trägt den Erweiterungsblock im Kopf, die beiden
|
||||
Skripte nennen ihre Zusätze im Modulkopf. Eine Erweiterung ohne
|
||||
Begründung gibt es nicht — dasselbe Muster wie bei den Quittungen.
|
||||
- **Ein Framework-Upgrade schließt den Abgleich dieser drei ein.** Was
|
||||
upstream zwischen alter und neuer Baseline an ihnen geändert hat, wird
|
||||
von Hand nachgezogen und in der neuen `HERKUNFT.md` protokolliert.
|
||||
|
||||
## Konsequenzen
|
||||
|
||||
- Das Projekt bleibt arbeitsfähig, ohne auf fremde Freigaben zu warten,
|
||||
und die Abweichung ist an drei Stellen nachlesbar statt an keiner.
|
||||
- **Für die übrigen neun Dateien behält der Byte-Vergleich seine volle
|
||||
Schärfe** — belegt beim Upgrade auf v0.3.1: `pruefe_upstream_drift: 0
|
||||
Fehler`, mit `WORKFLOW.md` byte-genau übernommen und zwei neu
|
||||
hinzugekommenen Vorlagen im Vergleich.
|
||||
- ⚠️ **Der Preis, ehrlich benannt: Der Abgleich beim Upgrade hat keinen
|
||||
maschinellen Widerspruch.** Er hängt daran, dass jemand daran denkt.
|
||||
Nachgemessen an genau diesem Fall: Zwischen v0.1.1 und v0.3.1 hat
|
||||
upstream zwei der drei Dateien angefasst — `validate.py` +29,
|
||||
`schema.yaml` +50 Zeilen, `gen_status.py` gar nicht. **Gemeldet hat das
|
||||
nichts.** Sichtbar wurde es erst, weil beim Upgrade ausdrücklich ein
|
||||
Diff über die Baselines gezogen wurde. Bis dafür eine Prüfung existiert,
|
||||
ist diese ADR das einzige, was sich daran erinnert. Das ist FB-12,
|
||||
Punkt 3, und dort steht auch der Vorschlag: eine Prüfung, die die
|
||||
erklärt-erweiterten Dateien gegen die *vorige* Baseline hält und meldet,
|
||||
dass etwas nachzuziehen war. Sie kann nicht beurteilen, ob wir richtig
|
||||
nachgezogen haben — aber der Fehler ist Vergessen, nicht Falschmachen.
|
||||
- Wird eine der drei Erweiterungen eines Tages upstream übernommen, fällt
|
||||
sie hier ersatzlos weg und die Datei kehrt in den Byte-Vergleich zurück.
|
||||
Für den Typ `component` und das Meilenstein-Konzept ist das der
|
||||
erklärte Zielzustand, nicht bloß eine Möglichkeit.
|
||||
Reference in New Issue
Block a user