Architecture Decision Records¶
The decision record for contributors. Each ADR documents one architectural decision: the context that prompted it, the alternatives considered, the choice made, and the consequences. Reading them chronologically is the canonical way to understand "why is X this way?".
| # | Title | Status |
|---|---|---|
| ADR 001 | v0.4 roadmap: WASM-primary positioning + feature completeness | Closed |
| ADR 002 | Feature selection: per-feature -D flags with one frozen nano profile |
Accepted |
| ADR 003 | Library and module loading: micropython-lib direct + frozen-tiny + lazy-fetch | Accepted |
| ADR 004 | Benchmarking methodology | Accepted |
| ADR 005 | Future optimization: landscape map (PROTO) | Proto |
| ADR 006 | JS interop: direct DOM bridge via sync host calls | Accepted |
| ADR 007 | WASM fat loss: the size-reduction roadmap | In Progress |
| ADR 008 | Golden program tracking: what runs on nanopython | In Progress |
| ADR 009 | v0.5 roadmap: usable WASM + selective Python parity + size-then-perf | Implemented |
| ADR 010 | v0.6 roadmap: closing the wall, broadening the surface | Proposed |
| ADR 011 | Everyday stdlib: dataclasses, pytest, and the eight modules a CPython script reaches for daily | Accepted (implemented 2026-06-12) |
| ADR 012 | Build profiles and the feature matrix: full as default, profiles as named feature bundles | Implemented 2026-06-13 |
| ADR 013 | Restoring exception unwinding across vendor-C frames (the try/except-over-MPZ wall) | Proposed |
Reading order¶
- New contributor orientation: ADR 009 (v0.5 roadmap) → ADR 010 (current roadmap) → TR-001 (the methodology paper).
- Designing a new feature: ADR 002 (build flags) + ADR 003 (module loading) + ADR 008 (compatibility tracking).
- Working on the wasm story: ADR 001 (positioning) → ADR 006 (JS bridge) → ADR 007 (size reduction).
- Benchmarking or perf work: ADR 004 (methodology) → ADR 005 (landscape PROTO).
Conventions¶
Each ADR has the same skeleton:
- Status: Proposed / Accepted / Implemented / Closed / Proto / In Progress
- Decider: usually "project maintainers"
- Supersedes: what older decision this replaces (if any)
- Branches from: what other ADR this builds on
- Consequences: one-sentence summary of what this commits the project to
- Numbered sections: Context, Decision, Implementation plan, Consequences, See also
The numbered prefix (NNN-) reflects creation order, not status. ADRs aren't superseded silently: a newer ADR that replaces an older one updates the older one's Status to "Superseded by …".