Architecture decision records¶
Durable answers to questions that shape pyDEXPI for years and would otherwise be relitigated every time the surrounding code grows.
An ADR belongs here when a question has all three of these properties:
- the options are mutually exclusive and expensive — picking one forecloses the others;
- the reasoning outlives the decision — someone in two years needs the argument, not just the conclusion;
- other work depends on the answer, so those issues need something citable.
A question that a pull request settles on its own is not an ADR. A closed issue is a poor place to find an argument, and an issue closed as wontfix is worse.
Deciding to wait is a decision. Record it, with the reasoning and the trigger for revisiting, rather than leaving the question open indefinitely.
Records¶
| Status | Title | |
|---|---|---|
| 0001 | Proposed | Pydantic as the parse target, or only as the schema |
| 0002 | Accepted | Comparing model states, and reviewing them in Git |
Writing one¶
Copy the shape of 0001: Context (what forces the decision, with evidence), Options
considered (each with its real cost), Decision, Consequences (including what gets worse),
and Revisit when (the concrete trigger). Number sequentially. Keep the status line current —
Proposed, Accepted, Superseded by NNNN.
They live under docs/mkdocs/ rather than docs/ because mkdocs.yml sets
docs_dir: docs/mkdocs, and anything outside it is not published with the site.