pr-descriptionlisted

# 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 或涉及多个不相关改动