技术英语 / 系统课时
写出可评审的 Pull Request
写出可评审的 Pull Request
可评审的 Pull Request 不只是“代码已经推上来了”,而是让评审者迅速判断改动是否必要、实现是否合理、风险是否可控。本篇将把问题背景、实现思路、关键改动、测试证据和已知限制组织成清晰英文正文。
学习目标
- 用英文说明 PR 的问题背景与实现意图
- 提供足够的测试证据、风险和已知限制
- 把正文写成帮助评审决策的信息,而不是文件变更清单
先回答评审者真正关心的问题
评审者通常需要连续做五个判断:为什么要改、这次怎么改、哪些地方最值得看、如何证明没有破坏既有行为、还有哪些风险没有消除。因此 PR 正文应围绕这些判断组织,而不是机械重复 git diff 中已经能看到的内容。
Updated parser.ts and tests. 信息很弱,因为评审者仍然不知道改动目的。更有效的写法是:This changes the parser to reject empty configuration files before tokenization, so callers receive a validation error instead of an unexpected exception.
用固定信息块降低阅读成本
一个实用的 PR 正文可以使用稳定的信息结构。片段示例:下面是 PR 描述模板,不属于可执行代码,实际内容应替换成当前变更的真实实现和验证结果。
## Summary
Fixes the crash that occurs when the validator receives an empty configuration file.
## Why
The parser currently enters tokenization before checking whether any input exists. This causes an exception instead of a user-facing validation error.
## What changed
- Added an early empty-input check.
- Reused the existing validation error type.
- Added regression coverage for empty and whitespace-only files.
## Testing
- Existing parser tests pass.
- New regression tests cover empty input and whitespace-only input.
## Limitations
This PR does not change validation behavior for malformed non-empty files.
## Reviewer notes
The main behavior change is in the parser entry path; the error type and public API remain unchanged.Summary 说明结果,Why 解释必要性,What changed 概括设计选择,Testing 给证据,Limitations 主动划出未解决范围。若项目要求关联 Issue,可以在合适位置写 Closes #<ID>,但不要为了“显得完整”随意声明会自动关闭并不对应的 Issue。
测试证据要能被复核
不要只写 Tested locally.。这句话没有告诉评审者测了什么,也无法判断测试覆盖了哪些风险。更好的证据包含测试命令、覆盖场景和结果。
提交前可以先检查当前未提交改动里是否存在 Git 能识别的空白错误:
git diff --check预期输出
text
当命令成功且没有发现空白错误时,终端通常没有输出,并以退出码 0 结束。若项目有自己的测试命令,应在 PR 中写出实际执行的命令和结果;不要写自己没有运行过的测试,也不要把“CI 应该会通过”当成测试证据。
对于界面变更,可说明 Before、After 和验证路径;对于性能改动,应提供可重复的基准条件;对于行为修复,至少要覆盖“原来失败的输入”和“不能被破坏的正常输入”。
让评审者知道从哪里开始看
大 PR 最容易产生的问题不是代码多,而是评审顺序不明确。可以用一句 Reviewer notes 指出关键入口,例如:Start with the validation branch in parser.ts; the remaining changes are regression tests and error-message updates.
如果改动中存在取舍,也应主动写明原因。I chose to reuse the existing error type to avoid changing the public API. 比让评审者从实现细节反推设计意图更高效。遇到尚未确定的地方,可以写 I would especially like feedback on ...,把开放问题变成明确的评审请求。
已知限制要主动写,不要等评审发现
Known limitations 不代表代码质量差,它是在定义本次变更的边界。若某个异常输入仍未覆盖、迁移只能向前兼容、性能数据只在某个平台验证,都应简洁写出。
同时避免把 PR 正文写成承诺清单。This should be safe 太模糊;更好的表达是说明证据:The public method signatures are unchanged, and the regression suite passes. 对无法验证的部分,则明确写 Not tested on Windows,让风险保持可见。
当正文能独立解释“为什么改、怎么改、如何验证、哪里有风险”时,评审者就能把注意力放在真正需要判断的代码上,而不是先花一轮评论追问上下文。