文档贡献指南（Contributing）

文档贡献指南（Contributing）#

1. 目的与范围#

本页定义 DP-EVA 文档系统的贡献流程与基本规范，确保文档长期可维护、可导航、与代码一致。

范围：

  • docs/guides/*、docs/reference/*、docs/architecture/*、docs/policy/*、docs/plans/*、docs/reports/*

2. 相关方#

  • 开发者：更新使用说明、配置示例、行为变更说明

  • 维护者：把控质量标准、避免重复与冲突、治理归档

3. 基本原则#

  • 单一权威来源：字段字典与校验规则只在 docs/reference/* 维护，其他文档只引用不复制。

  • 相对路径链接：项目内资源链接统一使用相对路径，避免与环境绑定。

  • 与代码一致：用户接口（CLI/配置/输出目录/完成标记）变更必须在同一 PR 内同步更新文档。

  • 禁止文件系统绝对路径链接：禁止 /home/...、C:\...；引用仓库代码文件请使用仓库 URL。

3.1 语言与翻译#

  • 仓库根 README.md 保持全英文，负责项目概览与导航；详细安装、Quickstart 和 CLI 操作进入对应指南，避免多处维护。

  • docs/ 当前以中文为主要维护语言；命令、字段名、API 标识符和引文保留原文，无需机械翻译。

  • 后续逐步提供中英双语，优先翻译安装、Quickstart、配置与贡献指南，不要求每次中文修订等待全站翻译完成。

  • 新增译文时注明对应源文档及同步版本，并提供双向语言入口；行为变更同步更新已有译文，暂时未同步时显式标注差异。

  • 双语页面共享同一套代码示例与配置模板，不复制维护两套可执行示例。历史归档保持原语言，不批量改写。

4. 文档类型与落点#

  • 分类与落点以 docs/source/policy/docs-structure.md 为准。

常见落点：

  • 使用说明：docs/guides/

  • 权威查表：docs/reference/

  • 架构与决策：docs/architecture/ 与 docs/architecture/decisions/

  • 一次性结论：docs/reports/

  • 项目级计划：docs/plans/

  • 制度与规范：docs/policy/

  • 历史归档：docs/archive/

  • 执行期草案：.trae/documents/（不直接作为项目文档入口）

4.1 草案与项目文档迁移规则#

  • AI/开发执行期文档先放 .trae/documents/。

  • 当内容进入“团队共享、可复盘、可发布”的状态时，迁移到 docs/plans/ 或 docs/reports/。

  • 发布后统一归档至 docs/archive/vX.Y.Z/{plans,reports}/，并更新对应索引。

5. 必备元信息#

所有标记为 Status: active 的文档必须包含：

  • Status / Audience / Last-Updated / Owner(s)

建议补充：

  • Applies-To / Related

6. Review 与验收#

验收标准以 docs/source/policy/quality.md 为准。

建议的 PR 自检：

  • 链接检查：确保无断链、无绝对路径链接

  • 示例一致性：示例配置字段与 Pydantic 模型一致

  • 风险说明：对破坏性变更提供迁移说明与旧路径跳转入口（如确需重命名/重排）

  • 责任归属：确认本次变更文档具备 owner 或 owners

  • 模板证据：在英文 PR 模板中记录影响、必要同步、验证结果和风险；不适用项明确标为 None 或说明原因。

7. 稳态化提交流程（标准）#

  1. 在提交前执行 python scripts/run_gate.py docs_pr；门禁命令的唯一来源是 scripts/gates.toml。需要完整发布验证时执行 python scripts/run_gate.py release。

  2. 在英文 PR 描述中填写：

    • 变更摘要和 public-contract impact；

    • 必要的文档、recipe、依赖或运行环境同步；

    • 可复现的验证命令、结果与未覆盖项；

    • 兼容性、迁移和回滚信息。

  3. 由对应 Owner 或 Code Owner 完成审查后合并。

计划与报告适用于重大架构、迁移或发布工作，并按文档生命周期维护；普通 PR 不以归档 计划/报告作为模板必填项。

8. 模板#

  • 页面模板：/docs/_templates/page.md

  • ADR 模板：/docs/_templates/adr.md

  • 报告模板：/docs/_templates/report.md

目录