前两篇都在讲"读"。这一篇讲"写"。

但不是再给你一堆模板——模板第一篇已经给过了。这一篇给你的是一场完整的对话:从提 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 讨论,非特定项目原文。


这个系列的其他几篇