This directory contains the Architecture Decision Records for tunaOS. These records are durable.
In ADRs, we document significant architectural and process decisions that the project made throughout its evolution. Each ADR captures context, rationale, trade-offs, and consequences.
RFC-PROCESS.md governs the ADR process (ADR 0004 established it; the tracker issues are #1093 / #1094).
When the project adopts an architectural change, significant refactor, or policy:
- We draft and review an RFC per RFC-PROCESS.md.
- Upon maintainer sign-off and merge, we record an ADR in
docs/adr/with the formatNNNN-short-title.md. - We backfill historical decisions as needed to ensure decision transparency.
| ADR | Title | Status | Date | Tracking / Context |
|---|---|---|---|---|
| 0001 | Rename GDX flavor to NVIDIA | Accepted | 2026-06 | Suffix clarity (-gdx → -nvidia) |
| 0002 | In-browser ISO builder with zero-publish architecture | Accepted | 2026-08 | #667, #1203 |
| 0003 | mkosi unified image co-build investigation and PoC | Recorded | 2026-08-11 | #999 |
| 0004 | RFC lifecycle policy (RFC-PROCESS.md) | Accepted | 2026-08-11 | #1093, #1094 |
| 0005 | Flavor equality, no primary desktop tier | Accepted | 2026-08-11 | #1315, #1316 |
| 0006 | Date-based versioning + stability tiers | Accepted; tiers superseded by 0016 | 2026-08-13 | VERSIONING.md, #274 |
| 0007 | Registry mirror support & fallback architecture | Accepted | 2026-08-13 | RFC-009, registry-map.yaml |
| 0008 | Where shell ends and Python begins | Accepted | 2026-08-14 | #1651 |
| 0009 | Clarify suite-common namespace ownership | Accepted | 2026-08-19 | #1585 |
| 0010 | Spec-driven work with Spektacular | Accepted | 2026-09-24 | RFC 011, #2673 |
| 0011 | Private adoption metrics | Accepted | 2026-09-27 | RFC 012, #2775 |
| 0012 | Fork config compatibility foundation | Superseded by #3668/#3807 | 2026-10-18 | RFC 013, #3433 |
| 0013 | Opt-in fork config consumer preview | Superseded; retired by #3807 | 2026-10-19 | RFC 013, #3439 |
| 0014 | Versioned ISO media provenance | Accepted approach, contract stage | 2026-10-19 | RFC 014, #3381 |
| 0015 | Credentials for non-owner publish destinations | Accepted | 2026-10-25 | RFC 016, #3801 |
| 0016 | :testing and :stable image rings, no LTS |
Accepted | 2026-10-30 | RFC 018, #4154 |
| 0017 | Protected native-package removal | Accepted (design); implementation not started | 2026-10-31 | RFC 017, #3803 |