This directory holds the architectural design notes for the
devcontainer library — the choices made before each major piece of
code landed, why they were made, and the trade-offs we accepted.
They are written for contributors and embedders who want to
understand why the code looks the way it does, not as user-facing
documentation. For usage, see the top-level README.
The docs reflect the state of the world at the time they were
written. They are not kept perfectly in sync with the code; when a
record disagrees with main, the code is authoritative. Sections
that explicitly call out alternatives, probe results, or "future
work" are kept because the reasoning is still useful even after the
work shipped.
- Code-level API documentation lives next to the code as Go doc
comments —
pkg.go.dev/github.com/crunchloop/devcontainerrenders it. - The Dev Containers spec itself lives at containers.dev. These records describe our implementation choices against that spec, not the spec itself.
- In-flight planning, milestone trackers, draft proposals, and
scratch notes are kept under
design/private/(gitignored).
Each document opens with a **Status:** line. The values you'll see:
- Draft for review — written before the work landed; reflects the design as proposed.
- Accepted — decided, code matches.
- Implemented — written before the work landed; code now matches and the document is the architectural record.
When a section in a document is superseded by a later decision, the later document is linked from an "Appendix" at the bottom of the older one.