跳转至

Docs-Impact — 功能改动与文档同批同步

触发场景：本次 staged 变更包含 src/** 或 wxt.config.ts。 目标：把“文档要不要更新”变成提交者必须回答、机器可以核对的显式契约，而不是靠记忆。

结论

触发产品影响路径时，commit message 必须且只能包含一条 Docs-Impact trailer。只能二选一：

  1. 列出本次同步更新并已 staged 的 Markdown 文档；
  2. 写 none — 具体理由，说明为什么用户路径、接口、配置或可见结果没有变化。

scripts/hooks/commit-msg 已接入自动门禁；pnpm test:docs-impact 会在隔离临时 Git 仓库验证通过与拒绝路径。即使本地 hook 未安装或被绕过，提交者和审查者仍要执行本规则。

触发范围

当前只把以下路径视为产品影响路径：

  • src/**
  • wxt.config.ts

仅修改 docs/**、scripts/** 或 package.json 不会单独触发本契约。发布版本一致性由发布专用检查负责，不把版本文件混进 Docs-Impact。

写法一：列出同步文档

Docs-Impact: docs/product/google-maps-collection.md

多篇文档使用英文逗号分隔：

Docs-Impact: docs/product/google-maps-collection.md, docs/wiki/shared-queue-architecture.md

每个路径必须同时满足：

  • 位于 docs/；
  • 以 .md 结尾；
  • 在提交后的文件树中存在；
  • 出现在本次 staged 变更中。

因此，引用一篇“本来就存在但本次没改”的文档不能充当同步证据。

写法二：声明无文档影响

Docs-Impact: none — 删除未引用的 JWT 辅助文件，不改变用户路径、接口或配置语义

要求：

  • none 后必须有破折号和非空理由；
  • 理由必须具体到本次改动；
  • 裸写 Docs-Impact: none 不合格；
  • 门禁只能检查格式，理由是否成立由独立审查者核对真实 diff。

选择哪类文档

改动事实 优先同步
用户入口、步骤、状态、错误提示、可见结果或限制变化 docs/product/
架构、数据流、字段语义或内部组件约定变化 docs/wiki/
新需求或契约变化 docs/specs/
修复了具体 bug docs/issues/
团队操作流程或门禁变化 docs/rules/

同一改动可以同时更新多层。例如：新增用户可见能力时，产品页说明怎么用，SPEC 记录契约，Wiki 记录架构。

提交前检查

git diff --cached --name-only
git diff --cached
pnpm docs:check

逐项确认：

  • 是否触发 src/** 或 wxt.config.ts；
  • trailer 只有一条；
  • 文档路径真实、位于 docs/、以 .md 结尾；
  • trailer 引用的每篇文档都已 staged；
  • none 理由经 diff 核对后成立；
  • 现有 ISSUE / SPEC 提交规则仍然同时满足。

不能做

  • 不根据文件 glob 猜“应该更新哪一篇文档”；人负责声明，机器只验证声明。
  • 不用 Docs-Impact: none 逃避用户文档更新。
  • 不把同一文档只改在工作树却不 staged。
  • 不用 --no-verify 作为长期流程；hook 误拦截应修规则或脚本。
  • 不用 git add . 混入无关文件；只暂存本次明确范围。

相关依据