执行摘要

• 一句话：修复 CI 中 legacy docs/ 变更检测失效问题
• 推荐动作：该 PR 属于基础设施加固，值得关注其通过三路 diff 替代 --cached 的思路，以及显式 diff 失败处理的模式。对于贡献者而言，应了解 docs/ 目录的新校验规则。

功能与动机

pre-commit 钩子 check-no-docs-changes 在 CI 环境未生效，自引入以来每次 PR 均被绕过（如 #24593, #23329 等 14 个 PR 均带有 docs/ 修改）。这是因为 git diff --cached --name-only 在 CI 干净检出中为空，导致脚本提前退出 0。此变更目的是在 CI 层面真正执行 docs/ 目录变更限制。

实现拆解

1. 设置 fetch-depth: 0：在 actions/checkout@v4 中设置，确保完整历史可用，以便计算三路 diff 的 merge-base。
2. 新增 CI 步骤：在 lint.yml 中新增 Reject changes under legacy docs/，仅对 pull_request 事件触发。使用 git diff --name-only origin/$BASE_REF...HEAD 获取变更文件列表，并用显式 if ! 捕获 diff 失败（如缺少 merge-base）。
3. 失败防护：若 diff 命令失败则退出码 2；若结果为空则跳过；否则通过 xargs 将文件列表传递给 scripts/ci/check_no_docs_changes.py。
4. 放置顺序：该步骤在 Python 环境设置之前，实现失败快速反馈，避免因无关工具安装浪费时间。

关键文件：

• .github/workflows/lint.yml（模块 CI 工作流；类别 infra；类型 infrastructure）: 核心变更：新增 legacy docs/ 变更检测步骤，并修复浅克隆问题。

关键符号：未识别

评论区精华

该 PR 评论数较少，无实质性 review 讨论。

• 暂无高价值评论线程

风险与影响

• 风险：

  1. 浅克隆兼容性：git fetch --no-tags origin $BASE_REF 依然可能因 BASE_REF 未 fetch 而失败（虽然已加固 if !）。
  2. 对本地工作流无影响：pre-commit-config.yaml 未修改，本地检测保持原样。
  3. allowlist 依赖外部脚本：check_no_docs_changes.py 内建了允许列表（如 docs/conf.py），此 PR 未修改该脚本，因此需确保 allowlist 符合预期。
     - 影响：对 CI 影响：Lint workflow 新增一个步骤，增加了约 0-2 秒执行时间。
     对开发者影响：任何修改 docs/ 目录（非 allowlist 中文件）的 PR 将被自动拒绝，需通过签署 CLA 或修改 allowlist 来解决。
     影响范围：仅影响 .github/workflows/lint.yml 文件，不涉及业务逻辑。

• 风险标记：CI 脚本健壮性, 浅克隆兼容风险

关联脉络

• PR #24593 some PR with docs/ changes: PR body 提及该 PR 被作为绕过 docs 检测的例子之一。
• PR #23329 another PR with docs/ changes: PR body 提及该 PR 被作为绕过 docs 检测的例子之一。
• PR #25120 another PR with docs/ changes: PR body 提及该 PR 被作为绕过 docs 检测的例子之一。