提交信息与 PR 描述:让三个月后的自己看懂

把一团 diff 整理成「为什么改—改了什么—怎么验证」的提交信息和评审说明。

什么时候用:提交信息全是「fix bug」「update」,或者 PR 描述写完还是没人敢合的时候用。

提示词(整段复制)

你是代码评审经验丰富的资深工程师。请根据下面的改动,写提交信息(commit message)和 PR 描述。

改动内容:{{diff}}
背景:{{背景}}
影响范围:{{影响}}

提交信息要求:
1. 只用一行标题 + 一段正文;标题不超过 50 个字符,动词开头,说清「做了什么」而不是「修了一下」;
2. 标题里带上模块名,格式为「模块: 做了什么」;
3. 正文说明「为什么改」,不要重复标题里的内容;
4. 如果有破坏性变更,标题下方空一行写 BREAKING CHANGE: 并说明受影响的调用方。

PR 描述要求,按四段:
1. 背景:这个问题造成什么实际影响(谁遇到了、多久一次);
2. 方案:为什么选这个改法,以及考虑过但放弃的另一种做法和放弃原因;
3. 改动清单:按文件/模块列,每条一句话,标出需要重点看的地方;
4. 验证方式:怎么证明改对了(跑了什么测试、手工验了哪些路径),以及没覆盖到的部分。

约束:不写「优化代码结构」「提升代码质量」这类无法验证的描述。

复制时把 {{变量}} 换成你自己的内容;变量名不要改,改了模型容易把它当普通文字。

要替换的变量

变量示例值
{{diff}}(粘贴 git diff 或改动说明)
{{背景}}(这个改动是因为什么需求或故障)
{{影响}}(涉及哪些模块、有没有破坏性变更)

实操建议

常见问题

小改动也需要写这么长的 PR 吗?

不需要。这段提示词里前三段可以缩成一句,但「为什么改」永远要写——它是唯一无法从 diff 反推出来的信息。

BREAKING CHANGE 怎么判断?

有人需要改自己的代码才能继续用,就是破坏性变更。包括函数签名、接口字段、默认行为、返回结构的变化。

配套工具