# PR #3134 完整报告

- 仓库：`radixark/miles`
- 标题：refactor(docs): nest CI pages under developer
- 合并时间：2026-09-07 14:25
- 原文链接：http://prhub.com.cn/radixark/miles/pull/3134

---

# 执行摘要

- 一句话：将 CI 文档目录从 docs/ci/ 迁移到 docs/developer/ci/，对齐开发者导航结构。
- 推荐动作：这是一个值得精读的、高质量的重构 PR。虽然变更规模不小（33 个文件），但其核心是高度机械和一致的路径替换操作，逻辑清晰。PR 审查过程严谨，通过自动化工具和人工审核确保了变更的完整性和正确性。对于维护文档结构和代码 - 文档映射规范的团队来说，这是一个很好的实践范例，展示了如何安全、彻底地进行大规模的目录重构。

# 功能与动机

根据 PR body，动机是为了让源码结构与文档站点的导航层级保持一致。文档站点已经将 CI 内容展示在 Developer Guide 下，但源码树中 CI 文档仍作为顶层文件夹存在。此次对齐为未来仅面向开发者的文档提供了统一的父目录，且不改变 CI 指南的含义，同时通过永久重定向保留了所有现有的 `/ci/*` URL。

# 实现拆解

1. **文件搬迁**：使用 `git mv` 将 `docs/ci/` 目录下的七个 Markdown 文件（如 `00-stage.md`, `01-label.md` 等）移动到 `docs/developer/ci/` 目录。这是变更的核心物理动作。
2. **导航与重定向配置**：更新 `docs/docs.json` 文件。在 `Developer Guide` 标签页的 `CI` 分组中，将所有页面路径从 `ci/*` 更新为 `developer/ci/*`。同时，在 `redirects` 数组中为所有七个移动的页面添加了永久重定向规则（`permanent: true`），将旧的 `/ci/*` 路径映射到新的 `/developer/ci/*` 路径。
3. **同步内部引用**：更新所有依赖于这些文档路径的引用。这包括：
 * `docs/developer/contributor-guide.md` 和 `docs/developer/versions.md` 等文档中的内部链接和文本描述。
 * `tests/ci/metric_history/*.py` 和 `tests/ci/test/test_stage_selection.py` 等测试文件中以 `# doc-dev:` 开头的哨兵注释，这些注释将代码模块与对应的文档页面关联起来。
 * `.github/workflows/*.yml` 文件和 `docker/Dockerfile` 中指向这些文档的注释链接。

关键文件：
- `docs/docs.json`（模块 文档配置；类别 config；类型 configuration）: 这是文档站点的导航和重定向配置文件，包含了本次变更的核心配置更新：页面路径重命名和永久重定向规则的添加。
- `tests/ci/test/test_stage_selection.py`（模块 阶段选择测试；类别 test；类型 test-coverage）: 这是路径敏感的测试文件，其变更展示了如何同步更新测试数据中的文档路径引用，确保了 CI 策略测试的正确性。
- `tests/ci/metric_history/constraints.py`（模块 约束模块；类别 test；类型 test-coverage）: 展示了代码 - 文档映射哨兵注释（`doc-dev`）的更新，这是维护代码与文档关联性的重要实践。

关键符号：未识别

## 关键源码片段

### `tests/ci/test/test_stage_selection.py`

这是路径敏感的测试文件，其变更展示了如何同步更新测试数据中的文档路径引用，确保了 CI 策略测试的正确性。

```python
# 在测试函数 test_docs_tooling_and_cpu_only_tests_skip_every_gpu_stage 中
# 模拟的变更文件路径被更新，以匹配新的文档位置
changed_files = (
    # 之前 : ChangedFile("M", ("docs/ci/00-stage.md",)),
    ChangedFile("M", ("docs/developer/ci/00-stage.md",)),  # 更新为新路径
    # ...
)
# ...
# 在测试函数 test_cli_publishes_all_gpu_stages_for_docs_diff 中
# 写入测试数据的路径也被同步更新
# 之前 : diff_path.write_bytes(b"M\0docs/ci/00-stage.md\0")
diff_path.write_bytes(b"M\0docs/developer/ci/00-stage.md\0")  # 更新为新路径

```

### `tests/ci/metric_history/constraints.py`

展示了代码 - 文档映射哨兵注释（`doc-dev`）的更新，这是维护代码与文档关联性的重要实践。

```python
# doc-dev: docs/developer/ci/03-metric-history-gate.md
# 这个注释标记了当前代码模块对应的文档页面。
# 在目录重构后，路径被更新以指向新的位置。
# 确保了代码与文档的映射关系保持准确。
"""The band constraint for the CI regression gate.

* A constraint decides whether one extracted scalar `cur` passes against a
  reference `ref` -- the mean of the trusted baseline for the historical
  gate.
# ... (模块的文档字符串)

```

# 评论区精华

Claude[bot] 的自动审查是主要的讨论内容，它确认了变更的机械性和正确性。其结论是："**Nothing blocking.**The comments below are optional suggestions." 它指出这是一个直接的、机械性的路径重命名（`docs/ci/*` → `docs/developer/ci/*`），并匹配了重定向和所有引用更新。审查中仅发现了一个微小的遗留问题：在 `docs/developer/contributor-guide.md` 第 36 行有一个过时的 `docs/ci internals` 注释，但这是一个仅影响外观的小问题，不影响功能。最终由 Shi-Dong 和 yueming-yuan 两位人工审核员批准合并。

- CI 文档目录重构的审查确认 (style): 审查认为变更无阻塞性问题，建议可合并。它确认了实现的完整性和正确性。

# 风险与影响

- 风险：风险极低。这是一个纯粹的文档路径重构和引用同步变更，不涉及任何业务逻辑、代码路径、认证、权限或数据处理的改动。主要风险在于：
 1. **链接断裂**：虽然已为所有七个页面添加了永久重定向，但如果项目中有未更新的外部链接或书签，它们仍会通过重定向正常工作。内部引用（如测试中的 `doc-dev` 注释）已全部更新。
 2. **测试覆盖**：测试文件中的路径引用（例如 `test_stage_selection.py`）已同步更新，确保了路径敏感测试的正确性。
- 影响：对用户和系统的影响范围有限且正面：
 1. **用户影响**：开发者和贡献者访问 CI 文档时，URL 将从 `/ci/*` 统一变为 `/developer/ci/*`，与文档导航栏的展示路径一致，提升了用户体验和信息架构的一致性。旧 URL 通过永久重定向保持兼容，不会立即失效。
 2. **系统影响**：文档站点的导航结构变得更加清晰和规范。代码库中关于“代码 - 文档”映射的元数据（`doc-dev` 哨兵注释）被准确维护，有助于未来的开发和维护。
 3. **团队影响**：为团队建立了更清晰的文档组织规范，便于未来在 `developer/` 目录下添加更多开发者专属文档。
 - 风险标记：文档路径重构

# 关联脉络

- 暂无明显关联 PR