pr-description

name	pr-description
description	写 Pull Request 描述时使用。让 reviewer 快速理解与审查。
category	docs
tags	["pr","协作"]

PR 描述

何时用

• 创建 Pull Request 之前,需要填写描述。
• 更新已有 PR,需要补充说明测试方法或设计变更。
• 接到 reviewer 反馈"看不懂这个 PR 在做什么"时,说明描述不够。
• AI 辅助完成了实现,需要人工补充上下文和验证步骤。

核心规则

1. 讲清"做了什么、为什么、怎么验证",不让 reviewer 猜

规则： PR 描述必须包含三部分:改了什么(变更摘要)、为什么改(背景/动机)、怎么验证(测试方法)——缺一不可。

为什么： AI 辅助写代码时,描述最常见的问题是只写"做了什么"而完全不写"为什么"和"怎么验证"。reviewer 看到一堆代码改动不知道背景是什么、这个方案是否是最优选择,也不知道怎么本地复现来验证。结果要么盲目通过,要么来回追问浪费时间。典型事故:PR 描述写"修复 bug",reviewer 花 20 分钟读代码才弄清楚是哪个 bug、怎么触发、为什么这样修。

怎么做：

• 用固定结构写描述:背景→改动摘要→验证步骤,三段清晰分隔。
• 背景可以一两句话说清楚:是 issue 触发、是需求变更、还是性能优化?
• 验证步骤要具体到"执行什么命令/点击什么按钮/看到什么输出"。

---

2. 关联 issue/需求;破坏性变更与迁移步骤显著标注

规则： 关联对应的 issue 编号或需求单;如果有 breaking change,必须在描述顶部显著标注,并附上迁移步骤。

为什么： AI 生成的 PR 里经常找不到任何 issue 关联,也没有 breaking change 警告。前者让项目管理失去可追溯性,半年后不知道某个改动是为了什么;后者让接入方在升级后莫名跑挂,只能自己去 git log 里找原因。破坏性变更不显著标注是最容易被忽视的 PR 问题,影响范围往往远超当前 repo。

怎么做：

• 描述开头加 Closes #123 或 Related to #456 自动关联 issue。
• 有 breaking change 时在描述最顶部加醒目标注:⚠️ Breaking Change + 影响范围 + 迁移方法。
• API 签名变更、配置格式变化、依赖版本升级等都算潜在 breaking change,不确定就标注。

---

3. 给测试计划/验证步骤,reviewer 能复现

规则： 描述中的"测试计划"要具体到可操作的步骤:运行什么命令、访问什么 URL、输入什么数据、期望看到什么结果。

为什么： AI 写的 PR 描述里"测试方法"常是一行:已通过单元测试。reviewer 无法判断:单元测试覆盖了哪些场景?有没有集成测试?手动测了哪些场景?UI 改动有没有截图?结果只能靠"信任 CI 绿了就行"通过 PR,这是生产事故的温床。特别是 UI 改动或涉及第三方服务的改动,仅靠 CI 无法验证。

怎么做：

• 给出本地复现步骤:1. 拉取分支 2. 执行 XXX 3. 访问 /endpoint 4. 预期返回 200 + {…}。
• UI 改动附截图或录屏(before/after)。
• 说明哪些场景有自动化测试覆盖,哪些靠手动验证。

---

4. PR 聚焦一件事,过大就拆;说明取舍与已知遗留

规则： 单个 PR 只做一件事;超过 400 行 diff 或涉及多个不相关改动时主动拆分;对无法当前解决的遗留问题,在描述中明确说明。

为什么： AI 辅助开发时容易在一个 PR 里顺手做了重构+功能+修 bug,产生千行 diff。reviewer 面对大 PR 的选择往往是:浅看后盲目通过,或者拖着不审导致 PR 堆积。两者都有风险。同时 AI 有时为了"让代码跑起来"引入了临时方案却不说明,reviewer 不知道这是临时的还是正式的,后续也没人跟进清理。

怎么做：

• 拆分原则:功能改动、重构、修 bug 各一个 PR;相互独立的功能各一个 PR。
• 描述里说明已知的取舍:当前方案为临时修复,完整方案见 #789。
• 已知 TODO 或已知限制显式列出,加 issue 链接跟踪,不要藏在代码注释里。

---

5. 自检清单(测试过、文档更新、无残留)随 PR 附上

规则： PR 描述末尾附一个可勾选的自检清单,提交前自己过一遍打勾,让 reviewer 看到你已自查过什么。

为什么： AI 完成实现后很容易忽略收尾工作:console.log 没删、CHANGELOG 没更新、文档没同步。自检清单是一种强制提醒机制——不是给 reviewer 看的形式主义,而是给自己设的最后一道门。有了清单,reviewer 也能快速判断"作者已确认过测试通过",减少重复问题。

怎么做：

• 模板里内置标准清单,每次按需勾选:[ ] 测试已通过、[ ] 无调试代码残留、[ ] 相关文档已更新、[ ] breaking change 已标注。
• 勾选时认真执行,不要机械全打勾——没做到的项目如实留空并说明原因。
• 团队统一模板放在 .github/pull_request_template.md。

---

正例 / 反例

反例:只写"做了什么",无背景无验证

<!-- 反例 — reviewer 一头雾水 -->

## 改动

修复了用户登录的问题,更新了 auth 相关逻辑。

---

已测试。

<!-- 正例 — 背景、改动、验证三位一体 -->

## 背景

用户反馈使用 SSO 登录后跳转回错误页面(见 #342)。
根因:OAuth callback 处理时未正确解析 `state` 参数,导致 redirect_uri 丢失。

## 改动摘要

- 修复 `OAuthCallbackHandler.parseState()` 中 URL decode 顺序错误
- 新增 `state` 参数为空时的降级处理(重定向至首页)
- 补充了原先缺失的集成测试用例

## 验证步骤

1. 本地启动:`docker compose up`
2. 访问 `http://localhost:3000/login`
3. 点击"使用 SSO 登录",完成认证
4. 预期:跳转回 `/dashboard`,不再出现 404

也可运行自动化测试:`npm run test:integration -- auth`

Closes #342

---

反例:破坏性变更隐藏在正文里

<!-- 反例 — breaking change 埋在第三段,接入方看不到 -->

## 改动

重构了配置加载模块,提升了性能。现在支持多种格式。
注意:配置文件格式从 JSON 改为 TOML(在第三段才提到)。

<!-- 正例 — breaking change 置顶显著标注 -->

## ⚠️ Breaking Change

配置文件格式从 JSON 变更为 TOML。升级步骤:
1. 将 `config.json` 重命名为 `config.toml`
2. 将所有值改为 TOML 语法(字符串加引号,对象用 `[section]`)
3. 运行 `npx migrate-config` 可自动转换(见工具说明)

## 改动背景

…（后续内容）

---

自查清单

• PR 描述包含背景、改动摘要、验证步骤三个部分。
• 已关联对应 issue 或需求单(Closes #xxx / Related to #xxx)。
• 有 breaking change 时已在描述顶部显著标注并附迁移步骤。
• 验证步骤具体可操作,reviewer 能独立复现。
• PR 只做一件事;过大或多事时已拆分或说明原因。
• 临时方案/已知遗留已在描述中明确标注并关联跟踪 issue。
• 末尾自检清单已如实勾选,没有机械全打勾。