Design Records
A design record explains why the code is shaped the way it is: the problem, the constraints, the compatibility boundary, the decision and the alternatives rejected. The site says how to use Wow; the records say why it works that way, for the people who change it.
Wow 10
Wow 10 was redesigned as a whole, and its records live together in documentation/designs/, in Chinese:
| Record | Holds |
|---|---|
README.md | The index, the conventions, and a log of every whole review |
00-architecture.md | The stance, the value, the principles and the overall architecture: read it first |
01–08 | One topic each: the programming model, the write path, the log and snapshots, subscriptions and waits, the read side and the contract, modules, migration, the wire formats |
09-capability-parity.md | Where every 9.x capability went |
decisions.md | The decision ledger |
reviews.md | The review ledger |
roadmap.md, progress.md | The milestones and work packages, and where the work stands |
docs-plan.md | The plan of the user documentation and the Skills |
00 keeps to conclusions and reasons; detail lives in the topic records, and where they disagree the topic record wins and 00 is fixed in the same change. Each record states its date, baseline and status: draft, adopted, in progress, implemented or superseded.
The decision ledger
Every Wow 10 decision is recorded once, in decisions.md, under a number, D6 say, that code comments, records and pull requests cite instead of repeating the argument. A decision is settled (with its date and who decided), open (with a recommendation), awaiting evidence (waiting on a spike's result) or revoked (naming what replaced it). Work that depends on an assumption awaiting evidence does not start before the evidence is in. When a decision is settled, the ledger is updated first, then the records it affects.
The review ledger
reviews.md is the one record of what reviews found. Each finding has a number, a severity (P0 to P2), its place in the code, what happens and when, where it went (a fix, a pull request, a decision) and a status: open, in progress, fixed with its pull request, moved to 10.x, dropped, or to be re-reviewed. A finding is recorded before it is assigned, and a fix's pull request names its number.
When a change needs a record
- A decision that spans JVM modules or the repository, or changes a public contract, a wire or storage format, or a module boundary, is recorded: a decision in the ledger, its reasoning in the topic record it belongs to.
- A design for a single TypeScript package or application stays beside it, in its
docs/design/. - A plan, review notes or scratch evidence for one change stays out of the repository: the pull request holds it.
Documentation Governance gives the home of every other kind of document.