如何完善 Pull Request 指南

我不知道你们怎么样，但我很喜欢按下合并按钮，把代码发布到生产环境的那种感觉。作为软件工程师，我们的最终目标就是让我们的代码走向世界。然而，除非你勇于冒险，否则在按下合并按钮之前，你还得克服一个巨大的障碍——获得拉取请求的批准。接下来，我们就来聊聊如何让你的拉取请求得到最佳审核，这样审核人员就能清楚地了解代码的内容，你也能更快地按下合并按钮。

Pull Request（拉取请求）讲述的是你修改背后的故事。它是你和审阅者之间的一次对话，作为故事的作者，你需要确保审阅过程尽可能简单便捷。至关重要的是，我们的 PR 必须提供审阅者所需的一切信息。它们应该简洁明了地描述我们修改背后的动机和想法，并预先解答审阅者可能提出的任何问题。

概述您的公关策略

就像一个好故事一样，我们的拉取请求也应该从章节大纲开始。在我们的例子中，章节就是我们的提交记录。我们都见过一些提交记录完全没有提供任何有用的信息，但每个提交信息都应该展现拉取请求故事的进展。

提交的主题行应概述所做的更改，而正文应提供其他上下文，例如更改的原因、任何可能的未来影响以及对工单或问题编号的引用。

使用常规提交可以帮助提供更直观的洞察。

组织你的公关活动

清晰明确的提交信息固然重要，但为了让你的代码故事易于理解，这些提交记录需要以合理的方式组织。你需要确保审阅者能够轻松地理解你对代码变更的描述。

但如果你之后需要修复或重构某些内容，而你已经提交了代码怎么办？完全没问题！作为开发者，我们可以通过变基来改变历史。如果你还不熟悉变基，它允许我们重新处理提交。你可以更改提交顺序、重写提交信息，甚至将两个或多个提交合并在一起。以下是变基和合并之间区别的简要说明。

关注你的公关规模

如果把提交比作拉取请求的章节，那么实际的代码实现和变更就是故事本身。关注故事的规模至关重要。计算机编程中有一条原则叫做单一职责原则，它指出……

计算机编程中的每个模块、类或函数都应该负责程序功能的某一特定部分，并且应该将该部分功能完全封装起来。该模块、类或函数的所有服务都应该与其职责紧密相关。

总而言之，单个模块、类或函数应该只专注于一件事。同样的道理也适用于代码拉取请求（Pull Request）。你可能认为，涉及大量文件的拉取请求会比涉及较少文件的拉取请求获得更多评论，但一项研究表明，开发人员一次审查的代码量不应超过 200-400 行。超过 400 行代码后，发现缺陷的能力就会下降。

因此，通过将一个大的拉取请求拆分成几个小的拉取请求，实际上增加了收到反馈的机会，也增加了审阅者发现他们在拉取请求较大时可能错过的错误的可能性。

您的公关介绍

我们已经介绍了公关故事的各个章节以及故事本身，但是一个好故事如果没有引言怎么能算得上好故事呢？这就是标题和描述的作用所在。

拉取请求标题是您向审阅者提供的第一条信息，它简要概述了拉取请求的内容。描述部分则可以提供更多细节，供审阅者或将来查看此拉取请求的任何人参考。

切记不要假设读者事先了解你正在处理的代码库区域。作为作者，你的职责是为他们提供必要的背景信息。你可以通过说明你的更改“是什么”、“为什么”和“如何”来实现这一点。

这部分应该详细说明你的拉取请求中的更改。还记得提交记录就像故事的大纲吗？这就是它们发挥作用的地方。用你的提交信息作为基础，向审核人员解释你的更改。在之前内容的基础上，添加更多细节。这部分描述还应该包含任何待办事项，并将其链接到相应的后续工单。

“为什么”部分应该解释你做出更改的理由，包括你做出的任何架构决策以及这些决策可能带来的任何影响。这可以包括解释为什么添加这个特定功能的用户故事、你进行重构背后的思考，甚至​​可以解释你的思考过程。

最后是“如何测试”。你的代码审阅者应该如何测试你的代码？请提供在演示环境中重现更改的步骤。你需要尽可能清晰明确——提供需要测试的路由的直接链接，以及他们可能需要的任何功能标志或权限。你还需要确保列出所有需要测试的具体场景。例如，审阅者可能需要执行哪些步骤才能重现错误状态。

成为自己的评论员

在向拉取请求添加任何审阅者之前，我会先自己进行审阅。我会仔细查看我的每一次提交，确保它们逻辑清晰、易于理解，并且还会查看代码本身。在此过程中，我经常会在自己的拉取请求中添加注释，对一些可能让审阅者产生疑问的代码行进行评论。你可以利用注释来解释你选择某种特定方式的原因，例如，当某个方向略微偏离常规时；或者你也可以突出显示某一行代码，以征求更多人的意见。

继续对话

现在，你已经完成了拉取请求的说明，添加了审阅者，并正式提交了拉取请求，你可能会认为事情到此就结束了。然而，围绕你修改的讨论才刚刚开始。拉取请求的意义就在于让其他人查看你的代码，以便发现错误或提供反馈。而拉取请求流程中至关重要的一环就是对这些反馈做出回应。

Pull Request 就像一个故事，你应该围绕这个故事与审阅者展开讨论。无论你收到一条、两条还是十条评论，都应该确保回复每一条。在每条评论都得到解决之前，无论是否采纳建议，Pull Request 都不应该被合并。如果你采纳了审阅者的建议，请务必注明。

并非所有评论都属于您的拉取请求范围。最终，您有权决定哪些内容属于范围之内，哪些不属于范围之内。但如果某些内容超出范围，则需要创建一个后续工单。一个优秀的拉取请求的关键在于完全透明。向审阅者解释为什么他们的建议超出范围，并附上后续工单的链接，以便他们处理该问题。

所有意见都得到解决后，终于到了按下合并按钮的时候了！你已经完成了将代码合并到生产环境的目标，待办事项清单上又划掉了一项。现在，是时候用新的代码重新开始整个流程了。

你有什么技巧可以完善你的 pull request 吗？请在下方留言！

请务必在Twitter或Threads上关注我，我会发布很多关于科技的文章，说实话，还有很多关于狗狗的文章。