# PR #26322 完整报告

- 仓库：`sgl-project/sglang`
- 标题：fix(ci): enforce legacy docs/ gate in Lint workflow
- 合并时间：2026-05-26 20:06
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/26322

---

# 执行摘要

- 一句话：修复 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 检测的例子之一。