程序员英语 05：写 Issue、Commit 与 PR
Issue 帮助别人理解问题，Commit 记录一次修改，PR 帮助评审者判断改动是否合适。三者可以围绕同一个缺陷，但不必粘贴同一段文字。
Issue：先让问题可复现
下面是虚构 CSV 导入器的完整教学案例：约定默认跳过空行；输入为表头、一个空行、一条数据；实际在空行处停止。
Title: Import stops at a blank line in default mode
Environment: csv-reader 2.4, Linux
Steps to reproduce:
1. Create a UTF-8 file with a header, a blank line, and one data row.
2. Import the file with default settings.
Expected: The importer skips the blank line and reads the data row.
Actual: The import stops at line 2 with "invalid record".
The same file imports successfully after I remove the blank line.标题包含对象、行为与条件，比 Bug report 更容易检索。步骤按顺序编号，预期和实际分开，最后一行是对照实验。版本、系统和结果来自案例设定，实际项目需要换成真实证据。
若文件内容决定能否复现，就附最小输入，而非只写“使用一个 CSV”。GitHub 创建 Issue 文档 说明了 Issue 与模板的入口；具体项目有模板时，按其字段填写。
Commit：一句话概括行为变化
可用动作开头：Skip blank lines before validating CSV records。它告诉读者改了什么，没有夸大成修复所有导入问题。
fix: skip blank lines before record validation 是另一种可能的团队格式；fix: 不是英语语法要求，也不是所有仓库必须使用的前缀。先遵循当前项目的提交约定。
需要正文时补充为什么：
Skip blank lines before validating CSV records
Blank lines reached the record validator and stopped default imports.
Handle them before validation so the importer follows the documented behavior.PR：让评审者知道看什么
一份短 PR 描述可以这样写：
Default imports stop when a blank line reaches the record validator.
This change skips blank lines before validation and keeps malformed,
non-empty records on the existing validation path.
Validation:
- Added a regression case with a blank line between two records.
- Checked that malformed, non-empty records still fail in strict mode.
Review focus: Please check the distinction between blank and whitespace-only lines.这段刻意把边界留给评审：空字符串和只含空格的行是否都该跳过，需要产品定义，不能靠一个 trim() 默默决定。Added、Checked 仅能用于已经完成的验证；计划做的检查写成 Planned validation。
高频表达与语气
| 目的 | 可以使用的表达 |
|---|---|
| 说明触发条件 | This occurs when ... |
| 说明影响 | This prevents users from ... |
| 说明修改 | This change allows ... |
| 请求具体评审 | Please check whether ... |
| 承认验证边界 | I have not tested this on ... |
| 标记待确认项 | It is unclear whether ... |
避免只有 optimized、improved 或 fixed the bug。这些词没有说明哪个行为发生了变化。
练习：把标题写具体
已知：虚构编辑器关闭前有未保存内容；选择 Cancel 后窗口仍关闭；期望窗口保持打开。写 Issue 标题、一个预期句和一个 PR 首句。修复尚未测试。
查看答案与讲解
标题：Editor closes after Cancel is selected in the unsaved-changes dialog。
预期：Selecting Cancel should keep the editor open with the unsaved content intact.
PR 首句：This change keeps the editor open when the user cancels the unsaved-changes dialog.
验证状态应另写 Validation is pending.，不能写 All tests pass.。如果正文没有说明未保存内容是否还在，实际 Issue 要把这项加入检查，不把预期误写成观察结果。
继续阅读
- 读写与对话练习
- 句法与表达查阅
- 句法与表达查阅