pr-explainer

PR 解读器

创建一个本地、自包含的 HTML 页面，帮助审阅者理解 PR 的来龙去脉：改了什么、为什么重要、如何运作、与系统的关系，以及如何验证。

必要工作流

1. 在编写 HTML 之前先理解 PR

   • 收集 PR 标题/编号、分支、链接（如有）、基础分支、提交范围、变更文件以及已完成的验证。
   • 使用 git status --short 检查当前状态。
   • 使用 git log --oneline -n 10 检查最近的提交。
   • 使用 git diff <base>...HEAD --stat 和 git diff <base>...HEAD 检查改动范围。
   • 如果某个提交承载了主要改动，使用 git show --stat <commit> 和 git show <commit> 检查该提交。

2. 确定解释路径

   • 不要按原始 diff 的文件顺序解释文件。
   • 在可能的情况下，按以下顺序讲解改动：
     1. 问题，
     2. 系统背景，
     3. 改动前后的数据或控制流，
     4. 关键代码改动，
     5. 来自测试/构建/手动检查的证明，
     6. 审阅者要点。
   • 将变更文件分类为核心行为、管道/集成、测试、发布元数据或无关噪声。
   • 只突出有助于解释 PR 的文件。

3. 以易于理解为目标编写

   • 使用通俗语言、简短章节、具体的改动前后示例、小而聚焦的代码片段、图示、表格和提示框。
   • 在介绍实现细节之前先说明问题。
   • 在使用缩写或特定包的术语之前先加以定义。
   • 避免直接堆砌完整 diff，也避免假设审阅者已了解内部背景。

4. 创建本地自包含的 HTML 文件

   • 将生成的文件放在 .pr-review/ 中。
   • 使用一个包含全部 CSS 和内容的 HTML 文件。
   • 默认不要提交 .pr-review/。
   • 优先使用仓库忽略规则或 .git/info/exclude，确保生成的审阅页面不进入提交。

推荐的 HTML 结构

除非 PR 明确需要不同的讲解顺序，否则使用以下结构：

1. Hero 区

   • PR 编号/标题、一句话摘要、分支/链接/状态。
   • 小型指标：变更文件数、新增测试数、受影响的包数。

2. 问题

   • 之前的行为。
   • 为什么它错误、令人困惑、缺失或存在风险。

3. 系统背景

   • 此改动位于产品或架构的哪个位置。
   • 上游调用方、下游行为，以及为什么这是正确的层级。
   • 有意保持不变的行为。

4. 改动前后的流程

   • 当 PR 改变了流程、状态、所有权、权限、请求处理、数据转换或组件关系时，展示旧路径与新路径的可视化对比。

5. 代码讲解

   • 分步解释讲解路径。
   • 仅针对重要文件给出聚焦的 diff。
   • 说明每个片段的作用以及为什么必要。

6. 测试 / 验证

   • 新增或更新的测试。
   • 运行过的测试、构建、类型检查、lint 或手动验证命令。
   • 已知的无关警告或失败（如有）。

7. 审阅者要点

   • 对 PR 最简短而有用的心智模型。
   • 审阅实际 diff 时审阅者应重点关注的内容。

图示

当图示能够降低认知负担时添加图示。优先使用简单的 HTML/CSS 图示，避免依赖外部资源。

适合的图示类型：

• 请求流：客户端 → 服务端 → 处理器 → 服务 → 结果
• 改动前后路径：有问题的路径 vs. 修复后的路径
• 所有权图：包/模块的职责边界
• 数据转换：输入 → 规范化形式 → 输出
• 状态机：pending → running → complete/error

每个图示都必须回答："这能帮助审阅者更快理解什么？"

聚焦差异代码片段

沿着讲解脉络展示代码片段，不要贴出大段补丁。每个重要片段应包含：

• 文件路径，
• 仅包含相关的新增／删除行，
• 用视觉样式区分新增／删除内容，
• 简短说明，
• 与 PR 故事的联系。

使用以下格式：

<div class="diff">
  <div class="diff-title">packages/example/src/file.ts</div>
  <pre>
<span class="del">- old behavior</span>
<span class="add">+ new behavior</span>
  </pre>
</div>

评审者无需打开 GitHub 也应能理解该 PR，但页面不应取代最终的完整差异审查。

验证要求

最后提供验证依据。可用时请包含准确的命令，例如：

pnpm --filter @scope/package test path/to/test.ts -- --run
pnpm turbo build --filter ./packages/package

如果未运行验证，请明确说明，并列出建议运行的命令。

最终检查清单

在确认页面完成之前，请确认页面包含：

• 清晰的一句话总结，
• 问题陈述，
• 前后对比说明，
• 更广泛的系统背景，
• 合适时提供的可视化图示，
• 分步骤的代码讲解，
• 标注文件路径的聚焦差异，
• 测试和验证命令，
• 给评审者的要点总结，
• 自包含的 HTML/CSS，
• 存放在 .pr-review/ 中，
• 除非收到明确要求，否则不要暂存或提交。

默认输出

收到创建 PR 解读页面的请求时，生成或更新 .pr-review/*.html 文件，并总结：

1. 输出路径，
2. 涵盖的 PR 故事，
3. 包含的关键章节，
4. 纳入的验证证据，
5. .pr-review/ 是否仍未跟踪或已排除。