提交信息与 PR 描述:让三个月后的自己看懂
把一团 diff 整理成「为什么改—改了什么—怎么验证」的提交信息和评审说明。
提示词(整段复制)
你是代码评审经验丰富的资深工程师。请根据下面的改动,写提交信息(commit message)和 PR 描述。
改动内容:{{diff}}
背景:{{背景}}
影响范围:{{影响}}
提交信息要求:
1. 只用一行标题 + 一段正文;标题不超过 50 个字符,动词开头,说清「做了什么」而不是「修了一下」;
2. 标题里带上模块名,格式为「模块: 做了什么」;
3. 正文说明「为什么改」,不要重复标题里的内容;
4. 如果有破坏性变更,标题下方空一行写 BREAKING CHANGE: 并说明受影响的调用方。
PR 描述要求,按四段:
1. 背景:这个问题造成什么实际影响(谁遇到了、多久一次);
2. 方案:为什么选这个改法,以及考虑过但放弃的另一种做法和放弃原因;
3. 改动清单:按文件/模块列,每条一句话,标出需要重点看的地方;
4. 验证方式:怎么证明改对了(跑了什么测试、手工验了哪些路径),以及没覆盖到的部分。
约束:不写「优化代码结构」「提升代码质量」这类无法验证的描述。复制时把 {{变量}} 换成你自己的内容;变量名不要改,改了模型容易把它当普通文字。
要替换的变量
实操建议
- 「考虑过但放弃的做法」这一段是评审效率的关键。写清楚之后,评审人不会再来提一遍你已经否掉的方案
- 「未覆盖到的部分」比「已测试的部分」更重要,它决定了敢不敢合
- 提交信息标题带模块名,出故障时 git log 一搜就能定位,比翻 PR 快得多
常见问题
小改动也需要写这么长的 PR 吗?
不需要。这段提示词里前三段可以缩成一句,但「为什么改」永远要写——它是唯一无法从 diff 反推出来的信息。
BREAKING CHANGE 怎么判断?
有人需要改自己的代码才能继续用,就是破坏性变更。包括函数签名、接口字段、默认行为、返回结构的变化。
