技术英语 / 系统课时
用 PR 标题说明修改意图
用 PR 标题说明修改意图
维护者在 PR 列表、通知邮件或发布记录里,通常只能先看到标题。好的标题应在脱离正文后仍能说明“做了什么修改、作用于什么对象”,让维护者不用打开 PR 就能判断它大致属于修复、功能、重构还是文档变更。
学习目标
- 能用明确的动词和对象组成可独立理解的 PR 标题
- 能根据修复、功能、重构和文档修改选择合适表达
- 能识别过于模糊、描述过程而不是结果的标题
标题先写修改动作,再写修改对象
最实用的结构是“动词 + 具体对象 + 必要的限定信息”。标题不需要把完整背景塞进去,但必须让读者知道这次变更实际改变了什么。
例如 Fix crash when parsing empty config files 比 Fix config issue 更有效。前者说明修复的是崩溃,触发条件是解析空配置文件;后者只告诉维护者“配置有问题”,几乎无法帮助判断影响范围。
同样,Add retry support for failed uploads 比 Improve upload logic 更具体。Improve 没有说明到底增加了什么能力,而 Add retry support 直接指出可观察的行为变化。
根据修改类型选择动词
常见 PR 不需要复杂英语,关键是动词准确。修复缺陷时优先使用 Fix;增加用户或开发者可见能力时使用 Add;修改既有行为时可以使用 Update 或更具体的动作;只调整内部结构且不改变外部行为时使用 Refactor;文档修改则直接使用 Document、Clarify、Update docs 等表达。
| 修改类型 | 更明确的标题 | 应避免的标题 |
|---|---|---|
| Bug 修复 | Fix duplicate notifications after reconnect |
Fix bug |
| 新功能 | Add filtering by repository language |
Add feature |
| 重构 | Refactor token validation into a shared helper |
Cleanup code |
| 文档 | Clarify local setup instructions for Windows |
Update README |
这些动词不是强制规范。具体项目如果在贡献指南中规定了 feat:、fix:、作用域或其他 Conventional Commits 风格,应优先遵循仓库规则。没有明确规范时,再使用自然、直接的英文标题。
写结果,不写自己的工作过程
Try another approach for caching、Changes after review、Address comments 都是在描述贡献者做了什么,却没有告诉维护者代码最终发生了什么变化。
假设评审意见要求避免重复读取配置,修改完成后的标题更适合写成 Reuse parsed configuration across validation steps,而不是 Address review feedback。评审过程可以在 PR 描述和评论中保留,标题应反映当前代码状态。
同样,不要把 Issue 编号当成主体。Fix #142 能建立关联,却无法说明 #142 是什么。更好的方式是先描述修改,再在 PR 描述中关联 Issue,例如标题写 Prevent duplicate jobs after scheduler restart,正文再写 Fixes #142。
控制信息量,让标题脱离上下文仍然成立
标题过短会失去信息,过长又会把 PR 描述压进一行。通常只需要保留最能区分这次修改的对象和条件。
例如 Fix incorrect status returned by API when a deleted project is requested 信息完整,但如果仓库上下文已经明确这是 API 服务,可以压缩为 Return 404 for deleted projects。后者直接描述最终行为,也更容易在列表中扫描。
反过来,Handle deleted projects 又太宽泛:读者不知道是隐藏项目、阻止删除,还是改变接口状态码。删词时不能删除决定修改性质的核心信息。
提交前做一次脱离上下文检查
写完标题后,假设维护者只能看到这一行,并问自己三个问题:能否判断主要修改动作,能否知道修改对象,能否大致理解结果或触发条件。如果其中一个答案是否定的,就补上最关键的信息。
例如从 Fix validation 改成 Reject empty repository names during validation,不仅增加了对象,还直接描述了修改后的行为。这样的标题即使出现在几十个 PR 的列表里,维护者也能迅速判断它是否与自己负责的模块相关。
PR 标题不追求复杂词汇,而追求信息密度。优先选择明确动词,写清具体对象和最终结果,并把讨论背景、Issue 关联和实现细节留给 PR 描述,标题就能真正承担“让维护者快速理解修改意图”的职责。