---
url: /zh/contribute/design-records.md
description: Wow 的设计记录放在哪里，决策台账和评审台账怎样维护，以及什么时候一个改动需要自己的记录。
---

# 设计记录

设计记录解释代码为什么是现在的样子：问题、约束、兼容性边界、决定以及被否决的备选方案。站点说明怎样使用 Wow；记录则为修改它的人说明它为什么这样工作。

## Wow 10 {#wow-10}

Wow 10 是整体重新设计的，它的记录集中在 [`documentation/designs/`](https://github.com/Ahoo-Wang/Wow/tree/main/documentation/designs) 中，以中文撰写：

| 记录 | 包含 |
| --- | --- |
| `README.md` | 索引、约定，以及每次整体评审的日志 |
| `00-architecture.md` | 立场、价值、原则和整体架构：先读它 |
| `01`–`08` | 每篇一个主题：编程模型、写入路径、日志与快照、订阅与等待、读取侧与契约、模块、迁移、线上格式 |
| `09-capability-parity.md` | 每项 9.x 能力的去向 |
| `decisions.md` | 决策台账 |
| `reviews.md` | 评审台账 |
| `roadmap.md`、`progress.md` | 里程碑和工作包，以及工作的进展 |
| `docs-plan.md` | 用户文档和 Skills 的计划 |

`00` 只写结论和理由；细节在各主题记录中，两者不一致时以主题记录为准，并在同一个改动中修正 `00`。每篇记录都注明它的日期、基线和状态：草案、已采纳、进行中、已实现或已被取代。

## 决策台账 {#the-decision-ledger}

Wow 10 的每个决定都只在 `decisions.md` 中记录一次，带一个编号，比如 `D6`，代码注释、记录和拉取请求引用这个编号，而不是重复论证。决定的状态是**已定**（带日期和决定人）、**待定**（带建议）、**待证据**（等待某个 spike 的结果）或**已撤销**（指明取代它的东西）。依赖某个待证据假设的工作，在证据到位之前不开始。决定确定之后，先更新台账，再更新它影响的记录。

## 评审台账 {#the-review-ledger}

`reviews.md` 是评审发现的唯一记录。每个发现都有编号、严重程度（P0 到 P2）、它在代码中的位置、发生什么以及何时发生、它的去向（修复、拉取请求、决定）和状态：待处理、进行中、已修复（带拉取请求）、移到 10.x、放弃，或待重新评审。发现先记录，再分派，修复的拉取请求要注明它的编号。

## 什么时候需要记录 {#when-a-change-needs-a-record}

* 跨 JVM 模块或跨仓库的决定，或者改变公开契约、线上或存储格式、模块边界的决定，要记录下来：决定写进台账，理由写进它所属的主题记录。
* 只关于单个 TypeScript 包或应用的设计，放在它旁边的 `docs/design/` 中。
* 某个改动的计划、评审笔记或临时证据不进入仓库：由拉取请求保存。

[文档治理](./documentation)给出其他每类文档的归属。