Skip to content

README.md

Latest commit

 

History

History
45 lines (37 loc) · 2.02 KB

README.md

File metadata and controls

45 lines (37 loc) · 2.02 KB
Raw

Documentation

This directory holds documentation that does not belong in rustdoc: the shape of the system, the reasoning behind it, and the constraints a reader needs before touching the code. API reference lives in doc comments next to the code, where it cannot drift.

Layout

docs/
├── README.md      # this index
├── specs/         # behavior and architecture specifications
├── plans/         # implementation plans derived from approved specs
└── adr/           # architecture decision records, numbered and immutable
  • specs/ — one file per feature, module, or subsystem, describing its behavior, public surface, invariants, and acceptance criteria.
  • plans/ — implementation-ordered, test-first steps for delivering an approved specification. Plans name exact files and verification commands, and are updated as the work progresses.
  • adr/ — a dated record per significant decision. Use adr/0001-record-architecture-decisions.md as the template. An accepted ADR is not edited; it is superseded by a later one.

Complex modules also carry a module-level README.md inside src/<module>/ covering their design, public surface, and important constraints.

The current module-release contract is in specs/tinybus-module-release.md, with its implementation sequence in plans/tinybus-module-release.md.

Conventions

  • Keep every Markdown file at 500 lines or fewer. When a topic outgrows that, split it into focused files and link them from the nearest README.md.
  • Update documentation in the same commit as the behavior it describes.
  • Prefer a concrete example over an abstract description.
  • Link between documents rather than duplicating content; one fact lives in one place.
  • Write a specification before a plan: the spec defines the outcome and constraints, while the plan defines the implementation sequence.