技术英语 / 系统课时
写清 Pull Request 的改动
写清 Pull Request 的改动
一份好的 Pull Request 描述不是把提交记录重新抄一遍,而是让 Reviewer 快速判断为什么要改、实际改了什么、影响范围在哪里,以及你如何确认它可用。本篇用一套简洁、可检索的英文结构,把改动信息组织成能直接进入 Review 的说明。
学习目标
- 用具体名词和动作动词概括 PR 的背景与核心改动
- 明确区分改动内容、影响范围和未涉及的范围
- 用可复核的验证描述替代
works for me一类模糊结论
先回答为什么要改
Reviewer 首先需要知道问题,而不是实现细节。开头通常用一两句话说明当前行为、它造成的具体问题,以及这次 PR 要解决的目标。尽量保留便于检索的技术名词,例如组件名、错误码、配置项或关联 Issue 编号。
比起 This PR improves retry logic.,更有用的写法是 This PR prevents synchronized retries after transient 5xx responses.。前者只有抽象评价,后者同时给出了改动对象、触发条件和目的。
如果 PR 对应已有问题,可以使用 Fixes #<ID>、Relates to #<ID> 等仓库约定,但不要让 Issue 链接代替背景说明。Reviewer 应当只看当前 PR 也能理解基本动机。
把改动和影响范围分开写
Changes 回答“代码做了什么”,Impact 回答“使用者会观察到什么”。两者混在一起时,Reviewer 很难判断哪些是实现细节,哪些属于兼容性或行为变化。
描述改动时优先使用明确动词,例如 replace、add、remove、reject、cache、retry。如果没有改变公开接口,也应直接写出边界,例如 No public API changes.;如果某项工作刻意不包含在本 PR 中,可以用 Out of scope 明确限制审查范围。
| 模糊表达 | 更具体的表达 |
|---|---|
Updated error handling. |
Return 429 when the per-user rate limit is exceeded. |
Improved tests. |
Added coverage for retry limits and timeout errors. |
Small refactor. |
Moved request validation into the shared middleware. |
用固定结构组织 PR 描述
下面是可直接改写后粘贴到 PR 描述中的片段示例。重点不是机械保留所有小标题,而是让背景、改动、影响与验证各自承担一个明确职责。
## Context
The API client uses a fixed delay after transient 5xx responses, which can cause multiple workers to retry at the same time.
## Changes
- Replaced the fixed delay with exponential backoff capped at 8 seconds.
- Added test coverage for retry count and maximum delay behavior.
## Impact
No public API changes. Retry timing changes only after transient 5xx responses.
## Verification
Verified the first three retry intervals and the 8-second cap with automated tests.预期结果:Reviewer 不需要阅读全部 diff,就能先确认问题背景、实现范围、外部影响和验证依据;搜索 5xx、backoff 或 retry 等关键词时也能迅速定位相关 PR。
让验证结果可以被复核
验证部分应说明“验证了什么”,而不只是写 Tested、Looks good 或 Works locally。对于自动化测试,可以描述覆盖的行为;对于手工验证,可以写清输入条件和观察到的结果。若存在未验证的平台或场景,也应明确说明,而不是默认它们已经通过。
PR 描述最终应让 Reviewer 能回答四个问题:为什么需要这次修改、代码具体改变了什么、谁会受到影响、现有证据是否足以支持合并。只保留能帮助这四个判断的信息,通常比堆叠实现细节更符合开源协作习惯。