2.9 KiB
2.9 KiB
PLoop 文档贡献约定
本文是 docs/ 子树的维护规则;根目录 README.md 是项目入口,README.md 是分类导航,plan/TODO.md 是唯一的执行状态台账。
归属:一个事实只有一个家
按读者要解决的问题落位,而不是按文件格式随意新增目录:
| 内容 | 唯一归属 |
|---|---|
| 用户问题、目标、范围、非目标与用户验收 | requirements/ |
| 当前实施状态、证据、阻塞与下一步 | plan/TODO.md |
| 非平凡 AI 实施的目标、允许路径、验收与完成证据 | plan/work-items/ |
| 已确认的取舍与原因 | decisions/decisions.md |
| PLoop 自身架构、数据/接口/运行时契约 | design/ |
| 公共 benchmark 的格式、评分、结果与采用边界 | benchmarks/ |
| 外部项目或论文的观察,以及可借鉴/不照搬边界 | reference/ |
| 能由另一位开发者实际复现的操作流程 | guides/ |
上层文档只概述并链接到事实所有者;不要复制字段表、评分口径、架构理由或执行状态。设计文档描述当前机制,决策文档保存取舍,指南提供按步骤验证的操作,参考文档不暗示已被 PLoop 采用。
语言与来源
- 当前内部文档以中文为单一权威来源,不要求把每份设计/计划翻成英文。
- 只有明确面向外部发布且承诺双语的文档,才建立英文/中文配对与对应 CI 规则;在此之前不创建半完成的翻译副本。
- 数据集原文、gold、自动生成的 OpenAPI/JSON Schema 与运行 artifact 的权威来源是冻结数据、生成器或代码。文档只说明版本、派生关系和读取方式,不手抄第二份真值。
- 仓库内文档相互引用使用相对 Markdown 链接;本机研究快照可以作为证据链接,但不能是 PLoop 运行所依赖的路径。
与实现同步
- 改变用户结果、范围或验收时,先更新
requirements/;改变公开 API、领域契约、数据格式、评分口径、运行命令或安全边界时,同一变更必须更新其拥有文档、相关 README/guide 和必要的决策记录。 - 新增或调整任务时更新
plan/TODO.md;没有可复现证据,实施项不得标记为DONE。 - 非平凡 AI 实施先创建/更新
plan/work-items/中的工作项;它链接需求、设计与验证,TODO 只保存当前状态和入口链接。 - 文档站若未来启用,Markdown 仍留在其业务归属目录;站点只能由显式清单投影,不能复制维护一套内容。
检查与规模
- 当前提交至少确认新增/移动的相对链接有效。M0a 已提供
make check-docs,检查仓库内相对路径与 Markdown 锚点,并被make check和 CI 调用。 - 在文档规模尚小时,以清晰的归属和短链为先,不设机械字数预算或全仓文档示例编译。只有相应文档站、双语发布面或生成 API 实际出现后,才针对该子树增加专项检查。