github-pr-workflow

GitHub 拉取请求工作流

提交一个评审者无需追问澄清问题就能批准合并的 PR。目标是在标题和正文中提供高价值信息，证明变更有效，并在收到反馈时妥善回复。

适用场景

• 你即将为一个功能已完成的变更开启 PR。
• 评审者留下了评论，你需要回复并推送修复。
• PR 已开启超过一天，需要重新整理（冲突未解决、缺少说明、缺少验证）。

不适用场景

• 变更的功能尚未完成。先完成工作；在评审中反复受阻的草稿 PR 只会制造噪音。
• 仓库使用的不是 GitHub 代码托管平台。请遵循相应平台的惯例，不要强行套用 GitHub 的做法。

开启 PR 前的分支整理

• 从目标基分支执行变基或合并，确保差异是最新的。
• 将 WIP 提交压缩成便于评审的单元。优先为每项逻辑变更保留一个提交；如果工作确实分多个步骤，不要强行要求每个 PR 只有一个提交。
• 确认测试、类型检查和 lint 在本地通过。在 PR 正文中说明任何有意跳过的检查。
• 删除未纳入跟踪的调试输出、注释掉的代码和 TODO 标记。

PR 标题

• 使用祈使语气，少于 70 个字符。
• 以用户可见的变更开头，而不是以修改的文件开头。Allow CSV export from reports table 优于 Update reports.tsx。
• 如果仓库使用议题前缀惯例（PAP-1234:、[security]），请遵循。
• 末尾不要加句号。

PR 正文

使用以下结构：

## Summary
- 1–3 bullets describing what changed and why.

## Implementation notes
- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
- Migration or config implications.

## Verification
- The exact commands or steps you ran.
- Screenshots or short clips for UI changes (required if pixels moved).
- Edge cases you exercised by hand.

## Risk and rollback
- What breaks if this is reverted, and how to revert cleanly.

只有明显琐碎的 PR（拼写错误、文档）才可以省略 Risk and rollback 部分。

验证证据

• CI 测试通过是必要条件，但还不够。评审者还需要了解变更端到端运行是否正确。
• 对于 UI 工作，请提供标准路径和一个边缘场景的截图。如果项目支持深色和浅色模式，请标注模式。
• 对于迁移，请提供试运行计划和回退步骤。
• 对于性能变更，请提供变更前后的测量结果，而不是形容词。

回复评审评论

• 回复每条评论，哪怕只回复“已在 中修复”——默默修复会让评审者猜测。
• 评审进行期间，将修复作为新提交推送；除非评审者同意，否则不要 amend。
• 如果你不同意反馈，用一句话说明理由，然后让评审者决定。不要因评论升级争论。
• 推送变更后，明确重新请求评审。

合并检查清单

• 所有必需检查均已通过。
• 所有评审评论均已解决。
• PR 标题和正文仍然准确（如果评审期间范围发生变化，请更新）。
• 按照项目惯例，将关联议题移至 in_review 或 done。
• 合并后删除分支，除非它是长期存在的集成分支。

反模式

• PR 说明只写“见提交记录”。评审者不应该还得去读提交日志。
• 在同一个 PR 中混合重构和行为变更，却不在正文中区分。
• 使用“处理反馈”之类的提交打包无关编辑。每轮反馈一个提交没问题；把所有进行中的工作都塞进一个提交则不行。
• 在评审进行期间强制推送，却不告知评审者。