Architecture Decision Records
Dieses Projekt führt kein ADR-Log. Es gibt kein docs/adr/-Verzeichnis
und keine nummerierte Reihe von Decision Records zum Nachlesen.
Die Entscheidungen selbst sind festgehalten — als Fließtext statt als nummerierte Reihe, an vier Stellen, von denen jede eine andere Körnung von “Warum” trägt. Diese Seite sagt dir, zu welcher du greifen musst.
Wo das “Warum” lebt
Abschnitt betitelt „Wo das “Warum” lebt“| Wo | Was dort steht |
|---|---|
| Design-Entscheidungen | Die Entscheidungen auf Framework-Ebene und was jede davon kostet: Bun zuerst, ts-pattern statt switch, das Single-Threaded-Modell, welche CRDTs ausgeliefert werden, HOCON statt YAML, keine Streams-DSL, explizite replyTo-Refs, keine Transaktionen über Actors hinweg. |
JSDoc in src/ | Warum genau eine Bedingung, Schranke oder ein Trade-off so ist, wie er ist — direkt neben dem Code, für den er gilt. Die Regel des Repos lautet, dass JSDoc das Warum erklärt — Bedingungen, Rationale, nicht offensichtliche Trade-offs — niemals eine Wiederholung des Codes. |
CHANGELOG.md | Was sich in jedem Release geändert hat und was dazu geführt hat. Breaking Changes tragen einen BREAKING-Marker und eine einzeilige Migrationsnotiz. |
| Commit-Bodies + der Issue-Tracker | Die Arbeitsspur: was versucht wurde, was fehlschlug, und was eine Schranke oder einen Default nach dem Messen verschoben hat. |
Für die Stabilitätszusage, die eine Entscheidung mit sich bringt, siehe Versionspolitik.
Wohin eine neue Entscheidung gehört
Abschnitt betitelt „Wohin eine neue Entscheidung gehört“Wenn du etwas beiträgst, das eine Design-Entscheidung ändert, wird kein
separates ADR erwartet. Die
AGENTS.md
des Repos legt fest, wohin die Begründung gehört:
- Bedingungen und Trade-offs → JSDoc, neben den Code, für den sie gelten.
- Was sich geändert hat und warum → der Commit-Body, mit Referenz auf
das Issue als
#NNN. - Ein Kurswechsel → ein Kommentar am Issue, geschrieben während du es merkst, nicht hinterher. Eine Diagnose, die sich als falsch erwies, ein naheliegender Fix, der nicht funktionierte, eine Schranke, die sich nach dem Messen verschoben hat, oder Scope, der in eine andere Schicht gehört — jedes davon ist mehr wert, wenn es aufgeschrieben statt neu hergeleitet wird.
- Verhaltens- oder API-Änderungen → ein
CHANGELOG.md-Eintrag, dazu beide Dokumentationssprachen, wenn Docs berührt werden.
Die Messlatte ist dieselbe, die schon die Issue-Anleitung verwendet: Würde derjenige, der den Faden als Nächstes aufnimmt — dich selbst in sechs Monaten eingeschlossen — es dir danken, dass du es aufgeschrieben hast?
Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Design-Entscheidungen — das ausführliche “Warum” hinter der Form des Frameworks.
- Versionspolitik — was stabil vs. experimentell ist.
- FAQ — häufige Fragen zum Framework.