51 lines
1.9 KiB
Markdown
51 lines
1.9 KiB
Markdown
|
# Engineering design documents
|
||
|
|
|
||
|
|
This directory holds **engineering design documents**: proposals, architecture
|
||
|
|
decisions, and interface sketches that are argued and agreed *before* code is
|
||
|
|
written.
|
||
|
|
|
||
|
|
It is not the user-facing documentation site. That lives in `sites/docs`
|
||
|
|
(Astro Starlight, published). Nothing here is built, deployed, compiled, or
|
||
|
|
type-checked.
|
||
|
|
|
||
|
|
## Layout
|
||
|
|
|
||
|
|
| Path | Contents |
|
||
|
|
|---|---|
|
||
|
|
| `docs/design/NNNN-<slug>.md` | One design document per proposal, numbered in the order they were opened. |
|
||
|
|
| `docs/design/sketches/` | Non-compiling interface sketches referenced by a design document. |
|
||
|
|
|
||
|
|
## Sketch files
|
||
|
|
|
||
|
|
Files under `docs/design/sketches/` carry a trailing `.sketch` extension
|
||
|
|
(`foo.rs.sketch`, `foo.ts.sketch`, `foo.proto.sketch`) so that no build tool
|
||
|
|
picks them up:
|
||
|
|
|
||
|
|
* there is no root `Cargo.toml` workspace, and no crate's `src/` includes this
|
||
|
|
path, so `.rs.sketch` is invisible to cargo;
|
||
|
|
* `pnpm-workspace.yaml` globs only `server/`, `libraries/base/`, `sites/*` and
|
||
|
|
`desktop/`, so `.ts.sketch` is invisible to pnpm, nuxt and tsc;
|
||
|
|
* `torrential/build.rs` compiles only `torrential/proto/*.proto`, so
|
||
|
|
`.proto.sketch` is invisible to protoc.
|
||
|
|
|
||
|
|
Sketches are illustrative. They name the types, traits and field layouts a
|
||
|
|
design implies. They are deliberately incomplete and will not compile.
|
||
|
|
|
||
|
|
## Status values
|
||
|
|
|
||
|
|
Each design document declares a status in its frontmatter:
|
||
|
|
|
||
|
|
* **Draft**: written, not yet reviewed.
|
||
|
|
* **Accepted**: agreed. Implementation may begin.
|
||
|
|
* **Implemented**: shipped. The document is now history; the code is the truth.
|
||
|
|
* **Superseded by NNNN**: replaced.
|
||
|
|
|
||
|
|
A document at `Draft` or `Accepted` describes something that **does not exist
|
||
|
|
yet**. Do not read it as a description of current behaviour.
|
||
|
|
|
||
|
|
## Index
|
||
|
|
|
||
|
|
| # | Title | Status |
|
||
|
|
|---|---|---|
|
||
|
|
| [0001](design/0001-import-time-chunk-compression.md) | Import-time chunk compression for game delivery | Draft |
|