Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Design Documents

Firewood records its designs as living documentation in a single flat directory. Every design is YYYY-MM-DD-slug.md: the date the design was proposed, followed by a short slug. The date is assigned once, when the file is created, and never changes, so a design’s path stays a stable reference in review threads and cross-links. Freshness is a separate question, answered by git history: just design-age lists designs by last commit date, oldest first.

A design’s lifecycle state lives in its status frontmatter field, not in its location:

  • draft: a work in progress, not yet ready for review.
  • proposed: under review, not yet built.
  • active: describes what the code does today; kept up to date as the code evolves.
  • superseded: replaced by a newer design; kept for history.
  • rejected: considered and declined; kept for the record.

Note

This is a lightweight convention, not a mandatory gate. A proposed design is encouraged for significant or non-obvious work, where writing it down sharpens the discussion; small or low-risk changes do not need one, and nothing blocks a pull request for lacking one. An active design may also be written after the fact to document something already built.

Designs

DesignProposedStatus
Firewood mdBook Documentation Site2026-06-17active

Subsystems not yet documented as designs are tracked in ava-labs/firewood#2139.

Frontmatter

Every design begins with a YAML frontmatter block, stripped from the rendered site by the in-repo frontmatter-strip preprocessor:

FieldRequiredValues
titleyesHuman-readable design title.
statusyesdraft, proposed, active, superseded, or rejected.
categoryyesThe Firewood subsystem(s) the design touches: storage, ffi, revision-management, hashing, proposals, docs, or tooling. A design spanning several lists them, e.g. [storage, hashing]. Extend the list as new subsystems gain designs.
authorsyesList of GitHub handles.
tracking-issuenoAn owner/repo#N reference to the issue or PR tracking the work.

There is no date field because the proposal date is in the filename.

Propose a design

  1. Run just new-design <slug> to scaffold YYYY-MM-DD-<slug>.md from template.md. The slug is lowercase kebab-case: letters, digits, and single hyphens.
  2. Fill in the template.
  3. Add a row to the Designs table and a sidebar entry in docs/src/SUMMARY.md.
  4. Open a pull request.

Promote a design

When a proposed design is implemented, promote it in place:

  1. Flip the frontmatter status: proposed to status: active.
  2. Drop the Unresolved questions section, folding any settled answers into the design. Keep Drawbacks: it records what was accepted and why.
  3. Rewrite future-tense prose as present tense.
  4. Add cross-links to the implementing pull request(s) and commits.
  5. Update this index’s status marker and the sidebar entry in docs/src/SUMMARY.md.