diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b7ab1b9..cb7a484 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -45,3 +45,16 @@ Closes # - [ ] PR description is **English** only — no AI/agent/Cursor tool attribution, no auto-generated summary blocks (e.g. `CURSOR_SUMMARY`, "Made with …") - [ ] No version bumps, tags, releases, or NuGet publish steps included unless explicitly requested - [ ] Public API / diagnostic / generated code changes are documented if user-visible + +## Documentation checklist + + + +- [ ] New/changed public API → Spec updated (`docs/spec/`) +- [ ] New/changed diagnostic ID → Spec updated + `AnalyzerReleases.Unshipped.md` updated +- [ ] Implementation detail changed → Design Doc updated (`docs/design/`) +- [ ] New RFC → used `docs/rfc/_template.md` template +- [ ] RFC status changed → frontmatter updated + archived to `docs/rfc/archive/` if Implemented/Rejected +- [ ] New ADR → numbered from `docs/adr/README.md` next available +- [ ] `CHANGELOG.md` `[Unreleased]` entry added +- [ ] No documentation changes needed diff --git a/AGENTS.md b/AGENTS.md index f3fc821..a34a070 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,7 +39,7 @@ DesignPatterns.slnx ├── DesignPatterns.Extensions.Autofac/ # Autofac 扩展 + Autofac 生成器 targets ├── DesignPatterns.Package/ # NuGet 元包（PackageId=Skymly.DesignPatterns） ├── tests/ # 单元 / 生成器 Verify / Analyzer / DI -├── docs/ # DEVELOPMENT、ROADMAP、模式文档 +├── docs/ # 维护者文档（DOCUMENTATION、DEVELOPMENT、ROADMAP、rfc/、adr/、spec/、design/、模式文档） ├── .github/ # Issue/PR 模板、CI └── AGENTS.md ``` @@ -115,7 +115,7 @@ dotnet test DesignPatterns.slnx -c Release | State（M1–M2） | `ITransitionTable`、`[StateMachine]`、`[Transition]` | `StateTransitionGenerator` | | DI Health Checks | `AddDesignPatternsHealthChecks`、`IHealthCheck` | —（运行时扩展） | -模式文档：[docs/Strategy.md](docs/Strategy.md)、[docs/ChainOfResponsibility.md](docs/ChainOfResponsibility.md)、[docs/Composite.md](docs/Composite.md)、[docs/FactoryRegistry.md](docs/FactoryRegistry.md)、[docs/Decorator.md](docs/Decorator.md)、[docs/EventAggregator.md](docs/EventAggregator.md)、[docs/FactoryKeyConventions.md](docs/FactoryKeyConventions.md)、[docs/StateTransitionTable.md](docs/StateTransitionTable.md)、[docs/rfc/StateTransitionTable.md](docs/rfc/StateTransitionTable.md)。 +模式文档：[docs/Strategy.md](docs/Strategy.md)、[docs/ChainOfResponsibility.md](docs/ChainOfResponsibility.md)、[docs/Composite.md](docs/Composite.md)、[docs/FactoryRegistry.md](docs/FactoryRegistry.md)、[docs/Decorator.md](docs/Decorator.md)、[docs/EventAggregator.md](docs/EventAggregator.md)、[docs/FactoryKeyConventions.md](docs/FactoryKeyConventions.md)、[docs/StateTransitionTable.md](docs/StateTransitionTable.md)。设计提案见 [docs/rfc/](docs/rfc/README.md)，架构决策见 [docs/adr/](docs/adr/README.md)。 --- @@ -312,6 +312,39 @@ git push origin v0.1.0-preview3 --- +## 文档体系 + +本仓库文档分为 5 种类型，完整规范见 [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md)。Agent 与人类开发者均须遵守。 + +| 类型 | 目录 | 用途 | 关键规则 | +|------|------|------|----------| +| **RFC** | `docs/rfc/` | 设计提案与讨论 | 新增模式/诊断/破坏性 API 必须 RFC；模板 `docs/rfc/_template.md`；已实现移入 `archive/` | +| **ADR** | `docs/adr/` | 架构决策记录（不可变） | RFC Accepted → 产出 ADR；编号不复用；正文不修改，仅 Supersede | +| **Spec** | `docs/spec/` | 稳定契约（API 面、诊断 ID、不变量） | 变更需 RFC + ADR；随代码 PR 同步更新 | +| **Design Doc** | `docs/design/` | 实现细节、设计权衡、已知局限 | 随代码 PR 同步更新 | +| **Roadmap** | `docs/ROADMAP.md` | 功能与技术 backlog | 完成项移入「已完成（归档）」章节 | + +**Plan** 以 GitHub Issue 为载体，不新建文档文件。 + +### Agent 文档工作流约定 + +| 场景 | Agent 行为 | +|------|-----------| +| 新增诊断 ID | 确认是否有对应 RFC；无则提示需创建 RFC | +| 修改公共 API | 确认是否有对应 RFC + ADR；无则提示需创建 RFC | +| 创建 RFC | 使用 `docs/rfc/_template.md`；frontmatter 从 `Draft` 开始 | +| 创建 ADR | 编号取 `docs/adr/README.md` 中下一个可用编号 | +| RFC 状态变更 | 更新 frontmatter `状态` + `更新` 日期；归档时移动到 `archive/` | +| Spec 变更 | 确认 RFC 已 Accepted；同步更新 Spec 版本号 | +| CHANGELOG | 在 `[Unreleased]` 下添加条目 | +| 文档目录 | 不在 `docs/` 之外创建文档文件（`.Local/` 除外） | + +### 现有模式文档迁移 + +现有 `docs/.md`（Strategy.md、Composite.md 等）将逐步拆分迁移至 `docs/spec/` + `docs/design/`。迁移计划见 [docs/spec/README.md](docs/spec/README.md)。迁移可逐模式进行，不要求一次性完成。 + +--- + ## Git / Issue / PR / Commit - **语言（权威）**：Issue / PR / Commit **一律英语**；与用户对话默认**简体中文**。本条为权威表述，**覆盖** `docs/DEVELOPMENT.md`、`CONTRIBUTING.md` 中任何「中英文均可」的旧措辞。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 177ab64..3eb70ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,7 +63,28 @@ dotnet test tests/DesignPatterns.SourceGenerators.Tests --filter FullyQualifiedN ## 文档 -- 用户可见变更：更新根目录 [`CHANGELOG.md`](CHANGELOG.md)（英语，Keep a Changelog；发版时将 `[Unreleased]` 条目迁入版本节） -- 新模式：在 [DesignPatterns.Samples](https://github.com/Skymly/DesignPatterns.Samples) 增加示例项目、更新本仓 `docs/` 与 [`AGENTS.md`](AGENTS.md) -- key 命名：遵循 [`docs/FactoryKeyConventions.md`](docs/FactoryKeyConventions.md) -- 架构 backlog：见 [`docs/ROADMAP.md`](docs/ROADMAP.md) +本仓库文档体系分为 RFC、ADR、Spec、Design Doc、Roadmap 五种类型，完整规范见 [`docs/DOCUMENTATION.md`](docs/DOCUMENTATION.md)。人类开发者和 AI 编码助手均须遵守。 + +### 文档工作流 + +| 变更类型 | 需要的文档操作 | +|----------|----------------| +| 新增模式 / 诊断 ID / 破坏性 API | 创建 RFC → Accepted 后产出 ADR → 实现 PR 中更新 Spec + Design Doc | +| Bug fix | Issue + PR；如影响实现细节则更新 Design Doc | +| 公共 API 变更 | Spec 更新 + CHANGELOG 条目 | +| 诊断 ID 变更 | Spec 更新 + `AnalyzerReleases.Unshipped.md` 更新 | +| 用户可见变更 | 更新 [`CHANGELOG.md`](CHANGELOG.md)（英语，Keep a Changelog；发版时将 `[Unreleased]` 条目迁入版本节） | +| 新模式 | 在 [DesignPatterns.Samples](https://github.com/Skymly/DesignPatterns.Samples) 增加示例项目、更新本仓 `docs/` 与 [`AGENTS.md`](AGENTS.md) | +| key 命名 | 遵循 [`docs/FactoryKeyConventions.md`](docs/FactoryKeyConventions.md) | +| 架构 backlog | 见 [`docs/ROADMAP.md`](docs/ROADMAP.md) | + +### 文档目录 + +| 目录 | 用途 | +|------|------| +| [`docs/DOCUMENTATION.md`](docs/DOCUMENTATION.md) | 文档体系标准（类型、生命周期、模板、归档） | +| [`docs/rfc/`](docs/rfc/README.md) | RFC — 设计提案与讨论 | +| [`docs/adr/`](docs/adr/README.md) | ADR — 架构决策记录 | +| [`docs/spec/`](docs/spec/README.md) | Spec — 稳定契约 | +| [`docs/design/`](docs/design/README.md) | Design Doc — 实现细节 | +| [`docs/ROADMAP.md`](docs/ROADMAP.md) | 路线图 | diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md new file mode 100644 index 0000000..5d11cbe --- /dev/null +++ b/docs/DOCUMENTATION.md @@ -0,0 +1,536 @@ +# 文档体系标准 + +> **权威源**。本文档定义本仓库所有文档的类型、结构、生命周期与归档规则。人类开发者和 AI 编码助手（Agent）均须遵守。`AGENTS.md`「文档体系」章节为本文档的精简摘要。 +> +> - **语言**：内部维护者文档以**中文**为主；面向库使用者的文档在 [DesignPatterns.Docs](https://github.com/Skymly/DesignPatterns.Docs) 仓库。 +> - **冲突优先级**：`AGENTS.md` > `docs/DOCUMENTATION.md` > 其他文档。 + +--- + +## 1. 文档类型总览 + +| 类型 | 目录 | 用途 | 稳定性 | 变更门槛 | +|------|------|------|--------|----------| +| **RFC** | `docs/rfc/` | 设计提案与讨论记录 | 提案阶段，频繁迭代 | 自由修改（Review 前） | +| **ADR** | `docs/adr/` | 架构决策记录（不可变卡片） | 已决策，仅追加 | 仅 Supersede，不修改原文 | +| **Spec** | `docs/spec/` | 稳定契约（API 面、诊断 ID、不变量） | 版本化稳定 | 需 RFC + ADR 方可变更 | +| **Design Doc** | `docs/design/` | 实现细节、设计权衡、已知局限 | 随实现演进 | PR 随代码同步更新 | +| **Roadmap** | `docs/ROADMAP.md` | 功能与技术 backlog | 滚动维护 | 维护者评审 | +| **Plan** | GitHub Issue | 任务计划（目标、步骤、验收） | 短生命周期 | Issue 内自由更新 | + +### 1.1 不作为独立文档类型 + +| 内容 | 载体 | +|------|------| +| 编码规范、兼容基线、打包、测试 | `AGENTS.md`（权威源） | +| 开发环境、构建、仓库布局 | `docs/DEVELOPMENT.md` | +| 发布流程 | `docs/PUBLISHING.md` | +| 变更日志 | `CHANGELOG.md`（Keep a Changelog 格式） | +| 贡献流程 | `CONTRIBUTING.md` | + +--- + +## 2. RFC — Request for Comments + +### 2.1 用途 + +对**有设计争议或影响面较大**的变更提出设计方案，供讨论与决策。小改动（bug fix、单方法新增）无需 RFC，直接 Issue + PR。 + +### 2.2 何时需要 RFC + +| 场景 | 需要 RFC？ | +|------|-----------| +| 新增模式（新源生成器 + 诊断） | ✅ 必须 | +| 新增或变更公共 API（破坏性） | ✅ 必须 | +| 新增诊断 ID（`DP###`） | ✅ 必须 | +| 跨模块架构变更 | ✅ 必须 | +| 单模块内 bug fix | ❌ Issue + PR | +| 单模块内新增非破坏性 API | ❌ Issue + PR（但需在 Design Doc 记录） | +| 文档/测试/重构 | ❌ Issue + PR | +| 工程整改（CI、构建脚本） | ⚠️ 视影响面，由维护者判断 | + +### 2.3 文件命名 + +``` +docs/rfc/.md +``` + +示例：`CompositeParallelTraversal.md`、`HierarchicalStateMachine.md`。 + +### 2.4 Frontmatter 标准 + +每份 RFC **必须**以如下元数据块开头（blockquote 格式，字段固定）： + +```markdown +> **状态**：Draft | Review | Accepted | Rejected | Implemented | Superseded +> **类型**：Feature | Pattern | Architecture | Process +> **创建**：YYYY-MM-DD +> **更新**：YYYY-MM-DD +> **作者**：维护者 / 贡献者 +> **关联 Roadmap**：FXX（如有） +> **关联 Issue**：#XXX（如有） +> **衍生 ADR**：ADR-XXX（Accepted 后填写） +``` + +### 2.5 正文章节模板 + +```markdown +# RFC: <标题> + +> （frontmatter） + +## 摘要 +一段话说明提案内容。 + +## 动机 +为什么需要这个变更？现有局限是什么？ + +## 非目标 +明确不做什么，避免范围蔓延。 + +## 设计方案 +### 概念模型 +### API 设计 +### 诊断影响 +### 实现方案 + +## 替代方案 +考虑过但否决的方案及原因。 + +## 开放问题 +讨论中尚未决策的问题（Review 阶段）。 + +## 决策记录 +Review 结束后记录最终决策与理由（Accepted 阶段填写）。 + +## 参考 +``` + +### 2.6 生命周期 + +``` +Draft → Review → Accepted → Implemented → (archive) + ↘ Rejected → (archive) +``` + +| 状态 | 含义 | 操作 | +|------|------|------| +| **Draft** | 作者撰写中，未公开征求意见 | 可自由修改 | +| **Review** | 公开征求意见 | 更新 frontmatter `状态`；讨论在 GitHub Issue 或 PR Comments | +| **Accepted** | 决策通过，待实现 | 填写「决策记录」章节；创建衍生 ADR；关联 Roadmap 项标记「进行中」 | +| **Rejected** | 决策否决 | 记录否决理由；移入 `archive/` | +| **Implemented** | 已实现并合并 | 关联 PR 号；移入 `archive/` | +| **Superseded** | 被后续 RFC 取代 | 标注取代者链接；移入 `archive/` | + +### 2.7 归档规则 + +- 状态变为 **Rejected**、**Implemented** 或 **Superseded** 时，文件移入 `docs/rfc/archive/`。 +- 归档文件**不再修改**（除修正链接失效）。 +- `docs/rfc/README.md` 状态板保留归档条目的链接。 + +--- + +## 3. ADR — Architecture Decision Record + +### 3.1 用途 + +记录**最终架构决策**的简短不可变卡片。ADR 不是讨论场所——讨论在 RFC 中完成，ADR 只记录结论。 + +### 3.2 与 RFC 的关系 + +- RFC **Accepted** → 产出一份 ADR（在 RFC frontmatter `衍生 ADR` 字段和 ADR `关联 RFC` 字段双向链接）。 +- 少数情况下，无需完整 RFC 的小决策也可直接写 ADR（如编码风格选择），但需在 ADR 中说明为何跳过 RFC。 + +### 3.3 文件命名 + +``` +docs/adr/ADR--.md +``` + +编号从 `001` 开始，零填充三位，**不复用编号**。示例：`ADR-001-roslyn-source-generators.md`。 + +### 3.4 格式模板 + +```markdown +# ADR-NNN: <标题> + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | Superseded by ADR-XXX | Deprecated | +| **日期** | YYYY-MM-DD | +| **关联 RFC** | [docs/rfc/XXX.md](../rfc/XXX.md)（或「无 — 直接决策」） | + +## 背景 + +为什么需要做这个决策？当时的约束和问题是什么？ + +## 决策 + +最终决定了什么？一句话概括 + 补充说明。 + +## 后果 + +这个决策带来的正面和负面影响。 + +## 参考 + +- 相关 ADR、文档、外部链接 +``` + +### 3.5 不可变原则 + +- ADR 一旦 **Accepted**，正文**不修改**。 +- 若决策被推翻，创建新 ADR 并将旧 ADR 状态改为 `Superseded by ADR-XXX`，旧 ADR 正文仍不修改。 +- 编号**永不复用**。 + +--- + +## 4. Spec — 规范文档 + +### 4.1 用途 + +定义模式的**稳定契约**：公共 API 面、诊断 ID、不变量、兼容基线。Spec 是「接口」级别的文档——描述 **what**，不描述 **how**。 + +### 4.2 与 Design Doc 的关系 + +| 维度 | Spec | Design Doc | +|------|------|------------| +| 回答 | What（契约是什么） | How + Why（怎么实现、为什么这样做） | +| 稳定性 | 高——变更需 RFC + ADR | 中——随实现演进 | +| 读者 | 库使用者 + 维护者 | 维护者 | +| 位置 | `docs/spec/` | `docs/design/` | + +### 4.3 文件命名 + +``` +docs/spec/.md +``` + +与模式名一致。示例：`docs/spec/Strategy.md`。 + +### 4.4 章节模板 + +```markdown +# Spec: <模式名> + +> **版本**：vX.Y（与 NuGet 包版本对齐） +> **关联 Design Doc**：[docs/design/.md](../design/.md) +> **关联 ADR**：ADR-XXX（如有） + +## API 面 + +### 运行时接口 +（接口定义、方法签名、泛型约束） + +### 特性（Attribute） +（特性类、属性、构造函数签名） + +### 生成器产出 +（生成的类名、方法签名、命名空间） + +## 诊断 ID + +| ID | 级别 | 触发条件 | 消息格式 | +|----|------|----------|----------| +| DPXXX | Warning | ... | ... | + +## 不变量 + +1. ... +2. ... + +## 兼容基线 + +- netstandard2.0 / net8.0 +- ... + +## 不在范围内 + +- ... +``` + +### 4.5 变更门槛 + +- **新增 API** 或 **新增诊断 ID**：需 RFC → ADR → Spec 更新。 +- **破坏性变更 API**：需 RFC → ADR → Spec 更新 + CHANGELOG `Breaking` 条目。 +- **文档修正**（措辞、示例）：直接 PR，无需 RFC。 + +--- + +## 5. Design Doc — 设计文档 + +### 5.1 用途 + +记录模式的**实现细节**、设计权衡、已知局限、与生态的边界。Design Doc 是「实现」级别的文档——描述 **how** 和 **why**。 + +### 5.2 文件命名 + +``` +docs/design/.md +``` + +与对应 Spec 同名。示例：`docs/design/Strategy.md`。 + +### 5.3 章节模板 + +```markdown +# Design Doc: <模式名> + +> **关联 Spec**：[docs/spec/.md](../spec/.md) +> **关联 RFC**：[docs/rfc/XXX.md](../rfc/XXX.md)（如有） +> **关联 ADR**：ADR-XXX（如有） + +## 概述 + +## 设计目标 + +## 实现概览 + +### 运行时 +（关键类、数据结构、算法） + +### 源生成器 +（增量管线阶段、EquatableArray 结构） + +### 诊断 +（检测逻辑、报告位置） + +## 设计权衡 + +### 选择了 X 而非 Y，因为... +（链接到 ADR） + +## 与生态的边界 + +## 已知局限 + +## 参考 +``` + +### 5.6 变更门槛 + +- 随代码 PR 同步更新，无需独立 RFC。 +- 但若实现变更导致 Spec 契约变更，则需走 RFC 流程。 + +--- + +## 6. Roadmap + +### 6.1 用途 + +维护 `docs/ROADMAP.md` 作为功能与技术 backlog 的滚动清单。 + +### 6.2 生命周期 + +``` +候选 → 排期 → 进行中 → 已完成（归档） + ↘ 暂缓 / 明确不做 +``` + +- **候选**：在 Roadmap 中登记，未排期。 +- **排期**：分配到 FXX 阶段，准备启动。 +- **进行中**：创建 RFC（如需要）+ Issue + 分支。 +- **已完成**：移入 Roadmap「已完成（归档）」章节。 +- **暂缓 / 明确不做**：移入对应章节，记录理由。 + +### 6.3 与其他文档的联动 + +| Roadmap 状态 | 关联文档 | +|--------------|----------| +| 排期 → 进行中 | 创建 RFC（如需要）→ Accepted → 产出 ADR | +| 进行中 → 已完成 | Spec 更新 + Design Doc 更新 + CHANGELOG 条目 + RFC 归档 | + +--- + +## 7. Plan — 任务计划 + +### 7.1 载体 + +GitHub Issue 即 Plan。不新建文档文件。 + +### 7.2 Issue 结构 + +大型特性 Issue 应包含： + +```markdown +## 目标 +## 关联 RFC +## 步骤 +- [ ] 子任务 1 +- [ ] 子任务 2 +## 验收标准 +## 关联 PR +- #XXX +``` + +### 7.3 何时需要 Issue + +- 所有 PR 必须关联一个 Issue（bug fix 可使用 `bug_report` 模板，功能使用 `feature_request` 模板）。 +- 大型特性（跨多 PR）使用一个主 Issue + 子任务 checklist。 + +--- + +## 8. 目录结构 + +``` +docs/ +├── DOCUMENTATION.md # 本文件 — 文档体系标准 +├── README.md # 文档索引 +├── DEVELOPMENT.md # 开发手册 +├── ROADMAP.md # 路线图 +├── PUBLISHING.md # 发布流程 +├── rfc/ +│ ├── README.md # RFC 索引 + 状态板 +│ ├── _template.md # RFC 模板 +│ ├── .md # 进行中的 RFC +│ └── archive/ +│ └── .md # 已实现/已否决的 RFC +├── adr/ +│ ├── README.md # ADR 索引 +│ └── ADR-NNN-.md # 架构决策记录 +├── spec/ +│ ├── README.md # Spec 索引 +│ ├── _template.md # Spec 模板 +│ └── <PatternName>.md # 模式规范 +├── design/ +│ ├── README.md # Design Doc 索引 +│ └── <PatternName>.md # 模式设计文档 +└── (横切约定文档保留在 docs/ 根目录) + ├── FactoryKeyConventions.md + ├── AppSettings.md + ├── Autofac.md + ├── Configuration.md + └── PluginAssemblies.md +``` + +### 8.1 现有模式文档的迁移 + +现有 `docs/<PatternName>.md`（Strategy.md、Composite.md 等）将逐步拆分迁移至 `docs/spec/` + `docs/design/`： + +| 现有文件 | 迁移目标 | +|----------|----------| +| `docs/Strategy.md` | `docs/spec/Strategy.md` + `docs/design/Strategy.md` | +| `docs/ChainOfResponsibility.md` | `docs/spec/ChainOfResponsibility.md` + `docs/design/ChainOfResponsibility.md` | +| `docs/Composite.md` | `docs/spec/Composite.md` + `docs/design/Composite.md` | +| `docs/FactoryRegistry.md` | `docs/spec/FactoryRegistry.md` + `docs/design/FactoryRegistry.md` | +| `docs/Decorator.md` | `docs/spec/Decorator.md` + `docs/design/Decorator.md` | +| `docs/EventAggregator.md` | `docs/spec/EventAggregator.md` + `docs/design/EventAggregator.md` | +| `docs/StateTransitionTable.md` | `docs/spec/StateTransitionTable.md` + `docs/design/StateTransitionTable.md` | + +迁移遵循以下规则： +- **API 面、诊断 ID 表、不变量、兼容基线** → Spec +- **实现概览、设计权衡、与生态边界、已知局限、示例** → Design Doc +- 横切约定文档（`FactoryKeyConventions.md`、`AppSettings.md` 等）保留在 `docs/` 根目录，不迁移。 +- 迁移可逐模式进行，不要求一次性完成。迁移时创建一个独立 PR。 + +--- + +## 9. 工作流程 + +### 9.1 新功能/新模式完整流程 + +``` +1. Roadmap 候选 → 排期 +2. 创建 RFC（Draft）→ 公开 Review +3. RFC Accepted → 产出 ADR → Roadmap 标记「进行中」 +4. 创建 Issue（Plan）+ 子任务 +5. 实现 → PR（随代码更新 Spec + Design Doc） +6. 合并 → RFC 标记 Implemented → 移入 archive/ +7. CHANGELOG 条目 → Roadmap 标记「已完成」 +``` + +### 9.2 Bug Fix 流程 + +``` +1. Issue（bug_report） +2. PR（修复 + 测试 + Design Doc 更新如需要） +3. 合并 → CHANGELOG 条目 +``` + +### 9.3 文档变更流程 + +``` +1. Issue（说明文档变更内容与原因） +2. PR（文档修改） +3. 合并 +``` + +### 9.4 Agent 工作流约定 + +AI 编码助手（Agent）在本仓库工作时，除遵守 `AGENTS.md` 的全部规则外，还须： + +| 场景 | Agent 行为 | +|------|-----------| +| 新增诊断 ID | 必须先确认是否有对应 RFC；无则提示需创建 RFC | +| 修改公共 API | 必须先确认是否有对应 RFC + ADR；无则提示需创建 RFC | +| 创建 RFC | 使用 `docs/rfc/_template.md` 模板；frontmatter 从 `Draft` 开始 | +| 创建 ADR | 使用 `docs/adr/` 目录；编号取 `docs/adr/README.md` 中下一个可用编号 | +| RFC 状态变更 | 更新 frontmatter `状态` + `更新` 日期；归档时移动文件到 `archive/` | +| Spec 变更 | 确认关联 RFC 已 Accepted；同步更新 Spec 版本号 | +| Design Doc 变更 | 随代码 PR 同步更新 | +| ROADMAP 变更 | 完成项移入「已完成（归档）」；新增项放入对应阶段 | +| CHANGELOG | 在 `[Unreleased]` 下添加条目 | +| 文档目录 | 不在 `docs/` 之外创建文档文件（`.Local/` 除外，见 AGENTS.md） | + +### 9.5 人类开发者工作流约定 + +人类开发者除遵守 `CONTRIBUTING.md` 的全部规则外，还须： + +| 场景 | 开发者行为 | +|------|-----------| +| 发起 RFC | 在 `docs/rfc/` 创建文件，提交 PR 标记 `Draft` → `Review` | +| 评审 RFC | 在 RFC PR 的 Comments 中讨论；决策后更新状态为 `Accepted`/`Rejected` | +| 创建 ADR | RFC Accepted 后，在 `docs/adr/` 创建 ADR 文件，双向链接 | +| 归档 RFC | 实现合并后，将 RFC 移入 `archive/`，更新 `docs/rfc/README.md` | +| Spec 变更评审 | 确认 RFC + ADR 齐备后批准 Spec 更新 | +| Roadmap 维护 | 定期评审 Roadmap，更新状态 | + +--- + +## 10. 文档与 Git 的关系 + +| 文档类型 | 提交方式 | +|----------|----------| +| RFC | 独立 PR（`docs: RFC <name>`）或随实现 PR | +| ADR | 随 RFC PR 或独立 PR（`docs: ADR-NNN <title>`） | +| Spec | 随实现 PR（与代码变更同一 PR） | +| Design Doc | 随实现 PR（与代码变更同一 PR） | +| Roadmap | 随实现 PR 或独立 PR | +| CHANGELOG | 随实现 PR | + +### 10.1 PR 模板中的文档 checklist + +PR 模板包含文档变更 checklist，提交者须勾选： + +- [ ] 新增/变更公共 API → Spec 已更新 +- [ ] 新增/变更诊断 ID → Spec 已更新 + `AnalyzerReleases.Unshipped.md` 已更新 +- [ ] 新增/变更实现细节 → Design Doc 已更新 +- [ ] 新增 RFC → 使用 `_template.md` 模板 +- [ ] RFC 状态变更 → frontmatter 已更新 + 归档操作已完成 +- [ ] CHANGELOG `[Unreleased]` 已添加条目 + +--- + +## 11. 文档质量检查清单 + +提交文档相关 PR 前，检查： + +- [ ] 文件位置正确（RFC 在 `docs/rfc/`，ADR 在 `docs/adr/`，Spec 在 `docs/spec/`，Design Doc 在 `docs/design/`） +- [ ] Frontmatter 格式符合标准（字段完整、日期格式 `YYYY-MM-DD`） +- [ ] 章节结构符合模板 +- [ ] 交叉链接有效（RFC ↔ ADR ↔ Spec ↔ Design Doc 双向链接） +- [ ] `docs/README.md` 索引已更新 +- [ ] `docs/rfc/README.md` 状态板已更新（RFC 状态变更时） +- [ ] `docs/adr/README.md` 索引已更新（新增 ADR 时） +- [ ] 语言：内部文档中文为主，技术术语可用英文 +- [ ] 无 AI/LLM 工具名称（遵守 `AGENTS.md` 隐私规则） +- [ ] 无私有工作区路径（遵守 `AGENTS.md` 隐私规则） + +--- + +## 12. 参考 + +- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) +- [Semantic Versioning](https://semver.org/spec/v2.0.0.html) +- [RFC Process (Rust)](https://github.com/rust-lang/rfcs) — RFC 生命周期参考 +- [ADR (Michael Nygard)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) — ADR 概念起源 diff --git a/docs/README.md b/docs/README.md index 9f09da2..d42615b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,17 +2,36 @@ 本目录面向**维护者与贡献者**（中文为主）。面向库使用者的英文/中文指南见 [DesignPatterns.Docs](https://github.com/Skymly/DesignPatterns.Docs)（VitePress 站点：[skymly.github.io/DesignPatterns.Docs](https://skymly.github.io/DesignPatterns.Docs/)）。 +> **文档体系标准**：[DOCUMENTATION.md](DOCUMENTATION.md) — 定义所有文档的类型、结构、生命周期与归档规则。人类开发者和 AI 编码助手均须遵守。 + ## 入门 | 文档 | 说明 | |------|------| +| [DOCUMENTATION.md](DOCUMENTATION.md) | **文档体系标准**（类型、生命周期、模板、归档、工作流） | | [DEVELOPMENT.md](DEVELOPMENT.md) | 环境、构建、测试、架构约定 | | [CONTRIBUTING.md](../CONTRIBUTING.md) | 贡献流程、测试与 Roslyn 组件结构 | | [PUBLISHING.md](PUBLISHING.md) | NuGet 预览/正式发版流程 | | [ROADMAP.md](ROADMAP.md) | 功能与技术 backlog | | [../AGENTS.md](../AGENTS.md) | AI 编码助手上下文（诊断 ID 权威登记） | -## 模式设计（实现细节） +## 设计提案与决策 + +| 目录 | 说明 | +|------|------| +| [rfc/](rfc/README.md) | RFC — 设计提案与讨论记录（[状态板](rfc/README.md)） | +| [adr/](adr/README.md) | ADR — 架构决策记录（[索引](adr/README.md)） | + +## 规范与设计文档 + +| 目录 | 说明 | +|------|------| +| [spec/](spec/README.md) | Spec — 模式稳定契约（API 面、诊断 ID、不变量） | +| [design/](design/README.md) | Design Doc — 实现细节、设计权衡、已知局限 | + +> 现有模式文档（`docs/<PatternName>.md`）将逐步拆分迁移至 `spec/` + `design/`，见 [spec/README.md](spec/README.md#迁移计划)。 + +## 模式设计（现有文档，待迁移） | 文档 | 模式 | |------|------| @@ -39,12 +58,6 @@ | [Configuration.md](Configuration.md) | `IConfiguration` → `IStrategyRegistry` 桥接 | | [PluginAssemblies.md](PluginAssemblies.md) | 卫星程序集 + 多项目 Registry 约定 | -## RFC（已落地） - -| 文档 | 说明 | -|------|------| -| [rfc/StateTransitionTable.md](rfc/StateTransitionTable.md) | State 转换表 v1 设计记录（已实现于 0.1.0-preview4） | - 用户向精简版见 DesignPatterns.Docs：[registry-key-conventions](https://skymly.github.io/DesignPatterns.Docs/registry-key-conventions)。 ## 与用户文档站的分工 diff --git a/docs/adr/ADR-001-primitives-over-frameworks.md b/docs/adr/ADR-001-primitives-over-frameworks.md new file mode 100644 index 0000000..bfe556b --- /dev/null +++ b/docs/adr/ADR-001-primitives-over-frameworks.md @@ -0,0 +1,31 @@ +# ADR-001: Primitives over frameworks + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | +| **日期** | 2026-06-14 | +| **关联 RFC** | 无 — 项目创立时的核心设计原则 | + +## 背景 + +DesignPatterns 定位为技术探索库，需要选择运行时库的设计哲学：是提供厚重基类体系（abstract base class + inheritance hierarchy），还是提供轻量可组合的 primitives。 + +## 决策 + +采用 **primitives 而非厚重基类体系**：运行时库提供接口、特性、轻量工具类，用户通过组合而非继承使用。Core 不引入强制基类。 + +## 后果 + +**正面**： +- 用户可选择性采用，无需全量 commit 到框架 +- 与现有 DI 容器、其他库兼容性好 +- 编译期胶水（源生成器）可针对 primitives 做静态分析 + +**负面**： +- 无法提供「开箱即用」的一站式框架体验 +- 用户需理解 primitives 的组合方式 + +## 参考 + +- [AGENTS.md](../../AGENTS.md)「项目是什么」章节 +- [docs/DEVELOPMENT.md](../DEVELOPMENT.md)「架构原则」章节 diff --git a/docs/adr/ADR-002-roslyn-incremental-source-generators.md b/docs/adr/ADR-002-roslyn-incremental-source-generators.md new file mode 100644 index 0000000..e9b073a --- /dev/null +++ b/docs/adr/ADR-002-roslyn-incremental-source-generators.md @@ -0,0 +1,33 @@ +# ADR-002: Roslyn incremental source generators + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | +| **日期** | 2026-06-14 | +| **关联 RFC** | 无 — 项目创立时的技术选型 | + +## 背景 + +DesignPatterns 需要在编译期减少样板代码并发现误用。可选方案：代码生成工具（T4、MSBuild task）、Roslyn 源生成器（`ISourceGenerator`）、Roslyn 增量源生成器（`IIncrementalGenerator`）。 + +## 决策 + +采用 **Roslyn 增量源生成器**（`IIncrementalGenerator` + `ForAttributeWithMetadataName`），而非 `ISourceGenerator` 或 T4。 + +## 后果 + +**正面**： +- 增量管线只在输入变化时重新执行，IDE 响应快 +- `ForAttributeWithMetadataName` 精确过滤，减少不必要的语法树遍历 +- 与 Roslyn 诊断管线集成，可在编译期报告 `DP###` 诊断 +- 生成代码可调试（`#nullable enable`、`#pragma` 支持） + +**负面**： +- 绑定 Roslyn 4.8+，限制了 VS / SDK 兼容范围 +- 增量管线调试复杂度高（需用 `driver.RunGenerator` + snapshot 测试） +- `EquatableArray` 等增量安全数据结构增加了实现复杂度 + +## 参考 + +- [AGENTS.md](../../AGENTS.md)「兼容基线」章节 +- [docs/DEVELOPMENT.md](../DEVELOPMENT.md)「Roslyn 组件」章节 diff --git a/docs/adr/ADR-003-dual-tfm-netstandard20-net80.md b/docs/adr/ADR-003-dual-tfm-netstandard20-net80.md new file mode 100644 index 0000000..a995668 --- /dev/null +++ b/docs/adr/ADR-003-dual-tfm-netstandard20-net80.md @@ -0,0 +1,32 @@ +# ADR-003: Dual TFM — netstandard2.0 + net8.0 + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | +| **日期** | 2026-06-14 | +| **关联 RFC** | 无 — 项目创立时的兼容性决策 | + +## 背景 + +运行时库需要选择目标框架。`netstandard2.0` 覆盖 .NET Framework / .NET Core / .NET 5+，但无法使用 `FrozenDictionary`、`Span<T>` 优化等新 API。`net8.0` 可用最新 API 但不覆盖旧运行时。 + +## 决策 + +运行时库同时目标 **`netstandard2.0` + `net8.0`**，两者均须可用并随包分发。使用 `#if` 分条件编译，`net8.0` 路径使用 `FrozenDictionary` 等优化。 + +## 后果 + +**正面**： +- 覆盖最广泛的 .NET 运行时（.NET Framework 4.6.1+ / .NET Core 2.0+ / .NET 5+） +- `net8.0` 消费者获得性能优化版本 +- 元包必须同时携带两个 TFM 的 `lib`，确保消费者拿到对应版本 + +**负面**： +- `#if` 条件编译增加代码复杂度 +- 测试需覆盖两个 TFM 路径 +- 打包脚本需验证两个 `lib` 目录均存在 + +## 参考 + +- [AGENTS.md](../../AGENTS.md)「兼容基线」章节 +- [docs/DEVELOPMENT.md](../DEVELOPMENT.md)「环境要求」章节 diff --git a/docs/adr/ADR-004-core-does-not-reference-msdi.md b/docs/adr/ADR-004-core-does-not-reference-msdi.md new file mode 100644 index 0000000..4ad677e --- /dev/null +++ b/docs/adr/ADR-004-core-does-not-reference-msdi.md @@ -0,0 +1,32 @@ +# ADR-004: Core does not reference MSDI + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | +| **日期** | 2026-06-14 | +| **关联 RFC** | 无 — 项目创立时的架构边界决策 | + +## 背景 + +DesignPatterns 运行时库（`DesignPatterns/`）需要决定是否直接依赖 `Microsoft.Extensions.DependencyInjection`（MSDI）。直接引用可简化 DI 集成，但会强制所有消费者引入 MSDI 依赖。 + +## 决策 + +**Core 不引用 MSDI**。DI 集成归 `DesignPatterns.Extensions.DependencyInjection` 独立项目，消费者按需引用。Autofac 集成同理归 `DesignPatterns.Extensions.Autofac`。 + +## 后果 + +**正面**： +- Core 可在不使用 MSDI 的环境中使用（Autofac、其他容器、无容器） +- 消费者不被迫引入 MSDI 依赖 +- DI 扩展可独立演进和发布 + +**负面**： +- 生成器需通过 `build/*.targets` MSBuild Import 机制在 DI 扩展项目中注册生成器路径 +- DI 集成相关诊断（DP060–DP062）需放在 Analyzer 而非生成器中，因为 Analyzer 可引用 MSDI 类型 + +## 参考 + +- [AGENTS.md](../../AGENTS.md)「编码标准」章节 +- [docs/DEVELOPMENT.md](../DEVELOPMENT.md)「架构原则」章节 +- [docs/Autofac.md](../Autofac.md) diff --git a/docs/adr/ADR-005-state-transition-table.md b/docs/adr/ADR-005-state-transition-table.md new file mode 100644 index 0000000..6bc6797 --- /dev/null +++ b/docs/adr/ADR-005-state-transition-table.md @@ -0,0 +1,39 @@ +# ADR-005: State transition table + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | +| **日期** | 2026-06-14 | +| **关联 RFC** | [docs/rfc/archive/StateTransitionTable.md](../rfc/archive/StateTransitionTable.md)、[docs/rfc/archive/HierarchicalStateMachine.md](../rfc/archive/HierarchicalStateMachine.md) | + +## 背景 + +DesignPatterns 缺少有限状态机 primitive。现有库（Stateless、Akka.NET）功能全面但厚重。需要一个轻量的、声明式标注 + 生成胶水 + 可选手动 Builder 的方案，与 Strategy/Factory 同级。 + +## 决策 + +采用 **enum 状态 + enum 触发器 + 编译期生成冻结查找表** 的方案： + +- 运行时：`ITransitionTable<TState, TTrigger>` 接口 + `TransitionTableBuilder` 手动 Builder +- 编译期：`[StateMachine]` + `[Transition]` 特性 → 源生成器生成冻结查找表与强类型 API +- 诊断：DP026–DP039 覆盖重复边、非法 enum、guard 签名、entry/exit action、字面量边校验 +- v3：层级状态机（`[StateParent]` + 编译期展平 + DP056–DP059） + +**不是**通用状态机框架：层次状态（v3 之前）、历史、持久化、重试不在 v1 范围。 + +## 后果 + +**正面**： +- 与 Strategy/Factory/Chain 同级的轻量 primitive +- 编译期诊断拦截非法转换，运行时零分配查找 +- 层级状态机（v3）通过编译期展平实现，运行时无层级开销 + +**负面**： +- 仅支持 enum 状态/触发器，不支持任意类型状态 +- 层级展平增加了生成器复杂度 + +## 参考 + +- [docs/spec/StateTransitionTable.md](../spec/StateTransitionTable.md)（待创建） +- [docs/design/StateTransitionTable.md](../design/StateTransitionTable.md)（待创建） +- [docs/StateTransitionTable.md](../StateTransitionTable.md)（现有模式文档，待迁移） diff --git a/docs/adr/ADR-006-composite-parallel-traversal.md b/docs/adr/ADR-006-composite-parallel-traversal.md new file mode 100644 index 0000000..7dc3ad2 --- /dev/null +++ b/docs/adr/ADR-006-composite-parallel-traversal.md @@ -0,0 +1,39 @@ +# ADR-006: Composite parallel traversal + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | +| **日期** | 2026-06-30 | +| **关联 RFC** | [docs/rfc/archive/CompositeParallelTraversal.md](../rfc/archive/CompositeParallelTraversal.md) | + +## 背景 + +Composite 模式已有串行遍历（`Traverse` / `TraverseAsync`），但大树遍历性能受限。需要并行遍历能力，同时保持线程安全契约清晰。 + +## 决策 + +新增 `TraverseParallel` / `TraverseParallelAsync` / `TraverseForestParallel` / `TraverseForestParallelAsync` 方法： + +- **BFS 同层并行**：同一层级节点并行处理 +- **DFS 子节点并行递归**：子节点并行递归，配合 `MaxParallelDepth` 超过阈值后回退串行 +- **`MaxDegreeOfParallelism`** 限流 +- **`AggregateException`** 聚合错误 +- **`ConfigureAwait(false)`** async 路径 +- **`#if` 分裂**：net8.0 用 `Parallel.ForEachAsync`，netstandard2.0 用 `SemaphoreSlim` + `Task.WhenAll` +- **线程安全责任**：用户责任 + 文档契约（不提供线程安全收集器） + +## 后果 + +**正面**： +- 大树遍历性能显著提升 +- net8.0 / netstandard2.0 双路径覆盖 + +**负面**： +- 用户需自行保证节点处理逻辑的线程安全 +- `MaxDegreeOfParallelism = 1` 退化为串行（非并行），用户需理解此语义 + +## 参考 + +- [docs/spec/Composite.md](../spec/Composite.md)（待创建） +- [docs/design/Composite.md](../design/Composite.md)（待创建） +- [docs/Composite.md](../Composite.md)（现有模式文档，待迁移） diff --git a/docs/adr/ADR-007-composite-tree-schema-validation.md b/docs/adr/ADR-007-composite-tree-schema-validation.md new file mode 100644 index 0000000..92eab07 --- /dev/null +++ b/docs/adr/ADR-007-composite-tree-schema-validation.md @@ -0,0 +1,39 @@ +# ADR-007: Composite tree schema validation + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | +| **日期** | 2026-07-07 | +| **关联 RFC** | [docs/rfc/archive/CompositeTreeSchemaValidation.md](../rfc/archive/CompositeTreeSchemaValidation.md) | + +## 背景 + +现有 Composite 诊断（DP010–DP015, DP040–DP041）覆盖键唯一性、父键存在性、循环检测、契约实现等基础校验，但不校验树的整体结构形态（最大深度、父子类型兼容性、节点计数）。 + +## 决策 + +新增编译期树结构 schema 校验： + +- **`[CompositeSchema(MaxDepth, MaxNodes)]`**（契约级约束） +- **`[CompositePart(AllowedChildTypes)]`**（节点级约束） +- **DP063**：最大深度超限（Warning） +- **DP064**：子节点类型不在 `AllowedChildTypes` 集合中（Error） +- **DP065**：节点计数超限（Warning） +- 源生成器阶段从 flat parent-key 映射计算树结构并报告诊断，无需运行时开销 + +## 后果 + +**正面**： +- 编译期拦截结构违规，运行时零开销 +- `AllowedChildTypes` 提供细粒度父子类型约束 +- 与现有 Composite 诊断体系无缝集成 + +**负面**： +- 生成器需在编译期重建完整树拓扑（深度计算、节点计数） +- `AllowedChildTypes` 使用 `Type[]`，泛型变体需同步维护 + +## 参考 + +- [docs/spec/Composite.md](../spec/Composite.md)（待创建） +- [docs/design/Composite.md](../design/Composite.md)（待创建） +- [docs/Composite.md](../Composite.md)（现有模式文档，待迁移） diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..7acbb6c --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,23 @@ +# ADR 索引 + +架构决策记录（Architecture Decision Record）。ADR 是不可变卡片，记录最终决策；讨论在 RFC 中完成。 + +- **格式与生命周期**：见 [DOCUMENTATION.md](../DOCUMENTATION.md#3-adr--architecture-decision-record) +- **模板**：[_template.md](_template.md) +- **编号规则**：从 ADR-001 开始，零填充三位，**不复用编号** + +## 决策列表 + +| ADR | 标题 | 状态 | 日期 | 关联 RFC | +|-----|------|------|------|----------| +| [ADR-001](ADR-001-primitives-over-frameworks.md) | Primitives over frameworks | Accepted | 2026-06-14 | — | +| [ADR-002](ADR-002-roslyn-incremental-source-generators.md) | Roslyn incremental source generators | Accepted | 2026-06-14 | — | +| [ADR-003](ADR-003-dual-tfm-netstandard20-net80.md) | Dual TFM — netstandard2.0 + net8.0 | Accepted | 2026-06-14 | — | +| [ADR-004](ADR-004-core-does-not-reference-msdi.md) | Core does not reference MSDI | Accepted | 2026-06-14 | — | +| [ADR-005](ADR-005-state-transition-table.md) | State transition table | Accepted | 2026-06-14 | StateTransitionTable, HierarchicalStateMachine | +| [ADR-006](ADR-006-composite-parallel-traversal.md) | Composite parallel traversal | Accepted | 2026-06-30 | CompositeParallelTraversal | +| [ADR-007](ADR-007-composite-tree-schema-validation.md) | Composite tree schema validation | Accepted | 2026-07-07 | CompositeTreeSchemaValidation | + +## 下一个可用编号 + +**ADR-008** diff --git a/docs/adr/_template.md b/docs/adr/_template.md new file mode 100644 index 0000000..60b4331 --- /dev/null +++ b/docs/adr/_template.md @@ -0,0 +1,23 @@ +# ADR-NNN: <标题> + +| 字段 | 值 | +|------|-----| +| **状态** | Accepted | +| **日期** | YYYY-MM-DD | +| **关联 RFC** | [docs/rfc/XXX.md](../rfc/XXX.md)（或「无 — 直接决策」） | + +## 背景 + +为什么需要做这个决策？当时的约束和问题是什么？ + +## 决策 + +最终决定了什么？一句话概括 + 补充说明。 + +## 后果 + +这个决策带来的正面和负面影响。 + +## 参考 + +- 相关 ADR、文档、外部链接 diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100644 index 0000000..e9941db --- /dev/null +++ b/docs/design/README.md @@ -0,0 +1,15 @@ +# Design Doc 索引 + +设计文档（Design Document）— 记录模式的实现细节、设计权衡、已知局限。 + +- **格式与变更门槛**：见 [DOCUMENTATION.md](../DOCUMENTATION.md#5-design-doc--设计文档) +- **模板**：[_template.md](_template.md) +- **与 Spec 的关系**：[Spec](../spec/) 描述 **what**（契约），Design Doc 描述 **how** + **why**（实现） + +## 已有 Design Doc + +（Design Doc 将随模式文档迁移逐步创建。现有模式文档位于 `docs/<PatternName>.md`，将拆分迁移至 `docs/spec/` + `docs/design/`。） + +## 迁移计划 + +见 [docs/spec/README.md](../spec/README.md#迁移计划) 中的迁移计划表。 diff --git a/docs/design/_template.md b/docs/design/_template.md new file mode 100644 index 0000000..50527de --- /dev/null +++ b/docs/design/_template.md @@ -0,0 +1,35 @@ +# Design Doc: <模式名> + +> **关联 Spec**：[docs/spec/<PatternName>.md](../spec/<PatternName>.md) +> **关联 RFC**：[docs/rfc/XXX.md](../rfc/XXX.md)（如有） +> **关联 ADR**：ADR-XXX（如有） + +## 概述 + +## 设计目标 + +## 实现概览 + +### 运行时 + +（关键类、数据结构、算法） + +### 源生成器 + +（增量管线阶段、EquatableArray 结构） + +### 诊断 + +（检测逻辑、报告位置） + +## 设计权衡 + +### 选择了 X 而非 Y，因为... + +（链接到 ADR） + +## 与生态的边界 + +## 已知局限 + +## 参考 diff --git a/docs/rfc/README.md b/docs/rfc/README.md new file mode 100644 index 0000000..bfe1dc7 --- /dev/null +++ b/docs/rfc/README.md @@ -0,0 +1,20 @@ +# RFC 状态板 + +Request for Comments — 设计提案与讨论记录。 + +- **格式与生命周期**：见 [DOCUMENTATION.md](../DOCUMENTATION.md#2-rfc--request-for-comments) +- **模板**：[_template.md](_template.md) +- **归档**：已实现 / 已否决 / 已取代的 RFC 移入 [archive/](archive/) + +## 活跃 RFC + +（无活跃 RFC — 所有 RFC 均已实现并归档） + +## 归档 RFC + +| RFC | 标题 | 最终状态 | 创建日期 | 衍生 ADR | +|-----|------|----------|----------|----------| +| [StateTransitionTable.md](archive/StateTransitionTable.md) | State 转换表 | Implemented | 2026-06-14 | ADR-005 | +| [HierarchicalStateMachine.md](archive/HierarchicalStateMachine.md) | State 层级状态机 | Implemented | 2026-06-28 | ADR-005 | +| [CompositeParallelTraversal.md](archive/CompositeParallelTraversal.md) | Composite 并行遍历 | Implemented | 2026-06-30 | ADR-006 | +| [CompositeTreeSchemaValidation.md](archive/CompositeTreeSchemaValidation.md) | Composite 树 schema 校验 | Implemented | 2026-07-07 | ADR-007 | diff --git a/docs/rfc/_template.md b/docs/rfc/_template.md new file mode 100644 index 0000000..5a262c8 --- /dev/null +++ b/docs/rfc/_template.md @@ -0,0 +1,46 @@ +# RFC: <标题> + +> **状态**：Draft +> **类型**：Feature | Pattern | Architecture | Process +> **创建**：YYYY-MM-DD +> **更新**：YYYY-MM-DD +> **作者**：维护者 / 贡献者 +> **关联 Roadmap**：FXX（如有） +> **关联 Issue**：#XXX（如有） +> **衍生 ADR**：ADR-XXX（Accepted 后填写） + +## 摘要 + +一段话说明提案内容。 + +## 动机 + +为什么需要这个变更？现有局限是什么？ + +## 非目标 + +明确不做什么，避免范围蔓延。 + +## 设计方案 + +### 概念模型 + +### API 设计 + +### 诊断影响 + +### 实现方案 + +## 替代方案 + +考虑过但否决的方案及原因。 + +## 开放问题 + +讨论中尚未决策的问题（Review 阶段）。 + +## 决策记录 + +Review 结束后记录最终决策与理由（Accepted 阶段填写）。 + +## 参考 diff --git a/docs/rfc/CompositeParallelTraversal.md b/docs/rfc/archive/CompositeParallelTraversal.md similarity index 97% rename from docs/rfc/CompositeParallelTraversal.md rename to docs/rfc/archive/CompositeParallelTraversal.md index c6cf8c5..d141b5b 100644 --- a/docs/rfc/CompositeParallelTraversal.md +++ b/docs/rfc/archive/CompositeParallelTraversal.md @@ -1,8 +1,13 @@ # RFC: Composite 并行遍历 -> **状态**：设计完成，待实现 Phase 1 -> **日期**：2026-06-30 -> **关联**：[Composite.md](../Composite.md)、[ROADMAP.md](../ROADMAP.md) +> **状态**：Implemented +> **类型**：Feature +> **创建**：2026-06-30 +> **更新**：2026-07-07 +> **作者**：维护者 +> **关联 Roadmap**：F5 +> **关联 Issue**：— +> **衍生 ADR**：[ADR-006](../../adr/ADR-006-composite-parallel-traversal.md) ## 概述 diff --git a/docs/rfc/CompositeTreeSchemaValidation.md b/docs/rfc/archive/CompositeTreeSchemaValidation.md similarity index 98% rename from docs/rfc/CompositeTreeSchemaValidation.md rename to docs/rfc/archive/CompositeTreeSchemaValidation.md index c1236cc..6bd70a8 100644 --- a/docs/rfc/CompositeTreeSchemaValidation.md +++ b/docs/rfc/archive/CompositeTreeSchemaValidation.md @@ -1,8 +1,13 @@ # RFC: Composite 树 schema 校验 -> **状态**：设计完成，待实现 -> **日期**：2026-07-15 -> **关联**：[Composite.md](../Composite.md)、[ROADMAP.md](../ROADMAP.md)、[CompositeParallelTraversal.md](CompositeParallelTraversal.md) +> **状态**：Implemented +> **类型**：Feature +> **创建**：2026-07-15 +> **更新**：2026-07-07 +> **作者**：维护者 +> **关联 Roadmap**：F5+ +> **关联 Issue**：#218 +> **衍生 ADR**：[ADR-007](../../adr/ADR-007-composite-tree-schema-validation.md) ## 概述 diff --git a/docs/rfc/HierarchicalStateMachine.md b/docs/rfc/archive/HierarchicalStateMachine.md similarity index 98% rename from docs/rfc/HierarchicalStateMachine.md rename to docs/rfc/archive/HierarchicalStateMachine.md index 0975139..8ac0470 100644 --- a/docs/rfc/HierarchicalStateMachine.md +++ b/docs/rfc/archive/HierarchicalStateMachine.md @@ -1,12 +1,13 @@ -# RFC：State 层级状态机（编译期展平） - -| 字段 | 值 | -|------|-----| -| **状态** | Accepted（5 个开放问题已决策，待实现） | -| **作者** | 维护者 | -| **创建** | 2026-06-28 | -| **关联** | [ROADMAP.md](../ROADMAP.md) F3 长期探索候选、[StateTransitionTable.md](../StateTransitionTable.md) v2、[rfc/StateTransitionTable.md](StateTransitionTable.md) §2.3 | -| **诊断** | `DP056` 起新区段 | +# RFC: State 层级状态机（编译期展平） + +> **状态**：Implemented +> **类型**：Pattern +> **创建**：2026-06-28 +> **更新**：2026-07-07 +> **作者**：维护者 +> **关联 Roadmap**：F3 +> **关联 Issue**：— +> **衍生 ADR**：[ADR-005](../../adr/ADR-005-state-transition-table.md)（与 StateTransitionTable RFC 共享 ADR） --- diff --git a/docs/rfc/StateTransitionTable.md b/docs/rfc/archive/StateTransitionTable.md similarity index 92% rename from docs/rfc/StateTransitionTable.md rename to docs/rfc/archive/StateTransitionTable.md index 859cc7b..3f94c15 100644 --- a/docs/rfc/StateTransitionTable.md +++ b/docs/rfc/archive/StateTransitionTable.md @@ -1,12 +1,13 @@ -# RFC：State 转换表（有限状态转换 primitive） +# RFC: State 转换表（有限状态转换 primitive） -| 字段 | 值 | -|------|-----| -| **状态** | Accepted / Implemented（v1 已于 0.1.0-preview4 发布；v2 guard/DI/DP036/entry-exit actions/IStateMachine 已实现） | -| **作者** | 维护者 / 贡献者 | -| **创建** | 2026-06-14 | -| **关联** | [ROADMAP.md](../ROADMAP.md) F3、`DP026` 起新诊断区段 | -| **评审后** | 已迁入 [docs/StateTransitionTable.md](../StateTransitionTable.md) | +> **状态**：Implemented +> **类型**：Pattern +> **创建**：2026-06-14 +> **更新**：2026-07-07 +> **作者**：维护者 / 贡献者 +> **关联 Roadmap**：F3 +> **关联 Issue**：— +> **衍生 ADR**：[ADR-005](../../adr/ADR-005-state-transition-table.md) --- @@ -41,7 +42,7 @@ - 层次 / 并发 / 历史状态（UML 状态机超集） - 持久化快照、分布式状态、超时转换 -- ~~Entry / exit / internal transition 动作~~（v1 非目标；**v2 已实现** entry/exit action 委托 + `[Transition(OnEnter/OnExit)]` 源生成，见 [StateTransitionTable.md](../StateTransitionTable.md)） +- ~~Entry / exit / internal transition 动作~~（v1 非目标；**v2 已实现** entry/exit action 委托 + `[Transition(OnEnter/OnExit)]` 源生成，见 [StateTransitionTable.md](../../StateTransitionTable.md)） - Guard 的编译期表达式求值（v1 无 guard；v2 仅运行时委托） - `string` / `int` 状态键（v1 仅 **enum**；与 DP025 字面量键校验正交，后续再评） - 反射扫描或 AppDomain 自动发现转换 @@ -218,7 +219,7 @@ public static partial class OrderStatusMachine; v1 **不**生成 `{State}Triggers` 或 `{State}Keys` 常量类——触发器与状态均直接使用 consumer 定义的 enum 成员。 -命名规则写入 [ROADMAP.md](../ROADMAP.md)「命名规则」表： +命名规则写入 [ROADMAP.md](../../ROADMAP.md)「命名规则」表： | 模式 | 生成类型示例 | |------|----------------| @@ -235,7 +236,7 @@ v1 **不**生成 `{State}Triggers` 或 `{State}Keys` 常量类——触发器与 ## 7. 诊断 ID（预留 DP026–DP032） -下一可用 ID：**DP026**（[AGENTS.md](../../AGENTS.md)）。实现前在 `DiagnosticIds.cs` 正式登记。 +下一可用 ID：**DP026**（[AGENTS.md](../../../AGENTS.md)）。实现前在 `DiagnosticIds.cs` 正式登记。 | ID | 级别 | 归属 | 触发条件 | |----|------|------|----------| @@ -294,7 +295,7 @@ OrderStatusTransitionTable.RegisterDi(services); // Singleton ITransitionTable<, services.AddTransitionTable(OrderStatusTransitionTable.Instance); ``` -启用开关：MSBuild 属性 `DesignPatterns_EnableDiIntegration`（引用 DI 扩展包时自动为 `true`）。详见 [StateTransitionTable.md](../StateTransitionTable.md#v2di-集成)。 +启用开关：MSBuild 属性 `DesignPatterns_EnableDiIntegration`（引用 DI 扩展包时自动为 `true`）。详见 [StateTransitionTable.md](../../StateTransitionTable.md#v2di-集成)。 --- @@ -311,7 +312,7 @@ services.AddTransitionTable(OrderStatusTransitionTable.Instance); | **M4 v2 DI 集成** | 生成 `RegisterDi` 方法、`AddTransitionTable` 扩展 | PR #126 | [x] | | **M4 v2 字面量边校验** | DP036 `StateTransitionLiteralEdgeAnalyzer` | PR #127 | [x] | -**模块边界**（强制）：M1 / M2 / M3 各为独立 PR，符合 [AGENTS.md](../../AGENTS.md) 跨模块规则。 +**模块边界**（强制）：M1 / M2 / M3 各为独立 PR，符合 [AGENTS.md](../../../AGENTS.md) 跨模块规则。 --- @@ -355,10 +356,10 @@ services.AddTransitionTable(OrderStatusTransitionTable.Instance); ## 15. 参考 -- [Strategy.md](../Strategy.md) — 注册表 + 生成器模式参考 -- [FactoryKeyConventions.md](../FactoryKeyConventions.md) — 键约定（State v1 不用 string key） -- [EventAggregator.md](../EventAggregator.md) — 组合用 pub/sub -- [ROADMAP.md](../ROADMAP.md) F3 准入标准 +- [Strategy.md](../../Strategy.md) — 注册表 + 生成器模式参考 +- [FactoryKeyConventions.md](../../FactoryKeyConventions.md) — 键约定（State v1 不用 string key） +- [EventAggregator.md](../../EventAggregator.md) — 组合用 pub/sub +- [ROADMAP.md](../../ROADMAP.md) F3 准入标准 - Stateless 文档 — 生态边界对照 --- diff --git a/docs/spec/README.md b/docs/spec/README.md new file mode 100644 index 0000000..14f591d --- /dev/null +++ b/docs/spec/README.md @@ -0,0 +1,25 @@ +# Spec 索引 + +规范文档（Specification）— 定义模式的稳定契约：API 面、诊断 ID、不变量、兼容基线。 + +- **格式与变更门槛**：见 [DOCUMENTATION.md](../DOCUMENTATION.md#4-spec--规范文档) +- **模板**：[_template.md](_template.md) +- **与 Design Doc 的关系**：Spec 描述 **what**（契约），[Design Doc](../design/) 描述 **how** + **why**（实现） + +## 已有 Spec + +（Spec 文档将随模式文档迁移逐步创建。现有模式文档位于 `docs/<PatternName>.md`，将拆分迁移至 `docs/spec/` + `docs/design/`。） + +## 迁移计划 + +| 模式 | 现有文档 | Spec 目标 | Design Doc 目标 | +|------|----------|-----------|-----------------| +| Strategy | [docs/Strategy.md](../Strategy.md) | `docs/spec/Strategy.md` | `docs/design/Strategy.md` | +| Chain of Responsibility | [docs/ChainOfResponsibility.md](../ChainOfResponsibility.md) | `docs/spec/ChainOfResponsibility.md` | `docs/design/ChainOfResponsibility.md` | +| Composite | [docs/Composite.md](../Composite.md) | `docs/spec/Composite.md` | `docs/design/Composite.md` | +| Factory Registry | [docs/FactoryRegistry.md](../FactoryRegistry.md) | `docs/spec/FactoryRegistry.md` | `docs/design/FactoryRegistry.md` | +| Decorator | [docs/Decorator.md](../Decorator.md) | `docs/spec/Decorator.md` | `docs/design/Decorator.md` | +| Event Aggregator | [docs/EventAggregator.md](../EventAggregator.md) | `docs/spec/EventAggregator.md` | `docs/design/EventAggregator.md` | +| State Transition Table | [docs/StateTransitionTable.md](../StateTransitionTable.md) | `docs/spec/StateTransitionTable.md` | `docs/design/StateTransitionTable.md` | + +迁移可逐模式进行，不要求一次性完成。每个模式的迁移创建一个独立 PR。 diff --git a/docs/spec/_template.md b/docs/spec/_template.md new file mode 100644 index 0000000..8005591 --- /dev/null +++ b/docs/spec/_template.md @@ -0,0 +1,39 @@ +# Spec: <模式名> + +> **版本**：vX.Y（与 NuGet 包版本对齐） +> **关联 Design Doc**：[docs/design/<PatternName>.md](../design/<PatternName>.md) +> **关联 ADR**：ADR-XXX（如有） + +## API 面 + +### 运行时接口 + +（接口定义、方法签名、泛型约束） + +### 特性（Attribute） + +（特性类、属性、构造函数签名） + +### 生成器产出 + +（生成的类名、方法签名、命名空间） + +## 诊断 ID + +| ID | 级别 | 触发条件 | 消息格式 | +|----|------|----------|----------| +| DPXXX | Warning | ... | ... | + +## 不变量 + +1. ... +2. ... + +## 兼容基线 + +- netstandard2.0 / net8.0 +- ... + +## 不在范围内 + +- ...