前两篇都在讲"读"。这一篇讲"写"。
但不是再给你一堆模板——模板第一篇已经给过了。这一篇给你的是一场完整的对话:从提 PR,到被质疑,到改,到合并。每一句都是真会用到的话。
一、为什么单独讲"对话"
写技术英语最难的不是"写一段话",是接住别人的话。
你可以准备好 PR 描述,但你准备不了 reviewer 会问什么。所以真正要练的是:对方说了 X,我该回什么。
这篇按真实节奏走一遍:
① 提 PR(第一次开口)
② 收到 review 意见(有同意、有不同意、有看不懂)
③ 回复(三种情况三种说法)
④ 改完再推(怎么通知)
⑤ 被要求 rebase / squash(怎么处理)
⑥ 合并(说什么、不说什么)
二、① 提 PR:描述写对了,省一半沟通
结构(四块,缺一块就会被问)
## What
Add retry with exponential backoff to the upload client.
## Why
Fixes #482 — uploads fail permanently on transient 503s.
The client currently gives up after one attempt.
## How
Wrap the upload call in a retry loop with jittered exponential
backoff, capped at 5 attempts / 30s total. Kept it opt-in via
`retry=True` to avoid changing existing behaviour.
## Testing
- [x] Added `test_upload_retries_on_503`
- [x] Manually verified against staging with `tc` injecting 20% loss
四块的作用:
| 块 | 回答的问题 | 少写的后果 |
|---|---|---|
| What | 这是干什么的 | reviewer 得自己猜 |
| Why | 为什么要做 | 被问"这个有必要吗" |
| How | 怎么做的 | 被问"为什么不用 X 方案" |
| Testing | 怎么验证的 | 被要求补测试,卡一周 |
三个容易踩的坑
坑 1:把 What 写成 How
❌ Added a while loop with a counter
✅ Add retry with exponential backoff
读者关心"你解决了什么问题",不关心"你用了什么语法"。
坑 2:忘了 Fixes #482
这一行是硬规矩。写了,PR 合进去时 issue 自动关闭;不写,你得手动去关,还容易忘。
坑 3:没说"我考虑过什么"
Kept it opt-in via `retry=True` to avoid changing existing behaviour.
这一句话顶三个问题。没这句,reviewer 一定会问"这会不会影响现有用户"。
主动交代取舍,是最省时间的写作技巧。
三、② 收到意见:先分类,再回复
review 意见不是一种东西。先判断是哪一类,决定要不要改。
| 类型 | 长什么样 | 要不要改 |
|---|---|---|
| 阻塞性问题 | 没前缀,直接指出 bug | 必须改 |
nit: | nit: this name could be clearer | 可选,不改也能合 |
question: | question: why not reuse the existing helper? | 要回答,未必改 |
suggestion: | suggestion: consider extracting this | 看情况 |
thought: | thought: we hit something similar in #210 | 不用回也行 |
nit 是关键。 很多人把所有意见都当阻塞项,逐个改,结果 PR 拖了三周。nit: 的意思是"我个人偏好,你随意"。
反过来也要注意:如果你认为某个 nit 值得采纳,改了也没坏处。但别因为 nit 卡住整个 PR。
四、③ 回复:三种情况,三套说法
情况 A:同意,改了
最短的回复最好。
Good catch — fixed in 1a2b3c4.
或者更短:
Fixed. Thanks!
不要写 “I have now updated the code as you suggested and pushed the changes.” —— 太长,而且没人关心过程。
一个细节:带上 commit hash。 fixed in 1a2b3c4 让 reviewer 直接跳过去看,不用翻整个 PR。
情况 B:不同意,但要礼貌
这是最难的一种。 模板:
I see your point, but I kept it as-is because <理由>.
Happy to change if you feel strongly.
最后那句是核心。 它的意思是:
我保留我的判断,但如果你坚持,我改。
这是维护者之间的标准妥协句式——既不卑不亢,又把决定权交回去了。
变体(对方是项目维护者时,语气可以更软):
That's a fair concern. My reasoning was <理由>, but
I'm not attached to it — happy to switch if you prefer.
I'm not attached to it(我对这个没有执念)是很好用的一句,表示"我不是在争,我只是在解释"。
情况 C:看不懂对方什么意思
千万不要假装懂。
Not sure I follow — do you mean I should <A>, or <B>?
给出两个选项,让对方选。 比 Could you clarify? 有效得多,因为对方只需要回一个字母。
情况 D:不同意,而且有硬理由
I considered that, but it would break backward compatibility
for users on v1.x, since <具体原因>.
The current approach keeps v1 working; we can revisit for v2.
结构:承认考虑过 → 给出具体后果 → 提供未来的路。
“提供未来的路"很重要——它表明你不是在拒绝,是在排序。
五、④ 改完再推:一句话通知
改完推上去之后,要主动说一声,否则 reviewer 不知道。
Updated — PTAL.
PTAL = Please Take Another Look。三个字母,这是标准说法。
如果要说明改了什么:
Pushed a fix for the timeout issue and renamed the helper
per your suggestion. PTAL.
只列出"改了什么”,不要复述整个过程。
六、⑤ 被要求 rebase / squash
场景:主线动了,你的分支有冲突
Could you rebase onto main? There's a conflict in config.py.
回应:
Sure, rebasing now. Will ping when it's up.
做完之后:
Rebased onto main (d4e5f6a). Conflict was in the default
timeout value — kept the new default, applied our retry logic
on top.
关键是最后一句话:说明冲突怎么解的。
因为 rebase 会改写历史,reviewer 看不出你保留了哪一边。主动说,省他一次追问。
场景:被要求把多个 commit 合成一个
Squash please — we prefer a single commit per PR.
回应:
Squashed into one commit (a1b2c3d). Message updated to
describe the whole change.
一个心态提醒
rebase 和 squash 不是批评,是项目规范。 很多新手把"要你 squash"理解成"你提交得太乱",其实是维护者想把历史整理干净。
回一句 sure 就行,不用道歉。
七、⑥ 合并:说什么、不说什么
维护者合并时
LGTM, thanks!
或
Merged. Thanks for the contribution!
你(贡献者)合并后
一句就够:
Thanks for the review!
不要写长篇感谢信。 也不要追问"这个会发在哪个版本"——去 release notes 看。
如果你的 PR 被关了(没合并)
这是最容易失态的时刻。 对方的说法通常很客气:
Thanks for the PR. We're going to close this for now —
the maintainers discussed it and we don't think it fits
the project's direction right now.
你的回应(如果还想在这个项目待着):
Understood, thanks for taking the time to review.
就这样。 不要争辩,不要问"为什么不早说",不要在 issue 里发长文。
记住一件事:被关掉不等于被否定。 很多项目关 PR 的原因和维护者心情无关,纯粹是方向不对。
八、几个高频小句,存着备用
| 场景 | 说法 |
|---|---|
| 承认自己错了 | You're right, my mistake. |
| 承认但保留 | Fair point — I'll think about it. |
| 需要更多信息 | Could you point me to an example? |
| 卡住了 | I'm stuck on <具体点>. Any pointers? |
| 时间不够 | I won't be able to get to this until next week — is that ok? |
| 想撤回 | Closing this — I found a simpler approach in #500. |
| 请求帮忙测试 | Would anyone be able to test this on Windows? |
这些句子不需要"翻译成中文再想一遍",直接背下来用。
九、三句实话
第一,PR 描述写得好,能省掉一半来回。 我见过最长的 review 拉锯,起因都是"为什么做这个"没说清。四块结构不是为了规范,是为了少被问。
第二,Happy to change if you feel strongly 这一句,值得单独背。
它解决了技术沟通里最难的问题:怎么在不认同的情况下,不把关系搞僵。
第三,态度比语法重要。 一个语法有错但态度诚恳的 PR,会有人耐心指导。一个语法完美但语气生硬的 PR,会被直接忽略。
你不是在考试,你是在跟人合作。
这是我的个人整理。文中句式来自公开的 GitHub PR 和 code review 讨论,非特定项目原文。
这个系列的其他几篇
- GitHub 是最好的英语老师:从读 Issue 到能开口 —— 从哪儿练
- 技术文档有四种,读法完全不同 —— 读之前先认类型
- 读不懂一句技术英语时,真正该查的不是单词 —— 句子怎么拆
- 技术人的口语:不追求流利,追求说对 —— 怎么说
- 计算机英语高频术语对照表 —— 随时查