在 GitHub 上提交代码必备指南！

 关注

“脚本之家

”，与百万开发者在一起

【CSDN 编者按】你是否经常参与开源项目？如果在 GitHub 上参与开源项目的 Pull Request，你知道正确的做法是什么吗？别担心，本文为你准备了详细的指南，希望对你有一定裨益。

作者 | Nick Skelton     

译者 | 弯月    责编 | 苏宓

出品 | CSDN（ID：CSDNnews）

以下为译文：

— 1 —

如果你是 PR 的作者

1. PR 不宜过大

将拉取请求（Pull Request，即 PR）控制在很小是一门艺术。在编写代码的时候，你经常会有重写、重构代码或整理代码的格式的冲动，但总的来说，优秀的开发人员会抵制一次性修改所有内容的诱惑。他们会集中一个目标，并将需要更改的代码量降到最低。有些人甚至会相互比较“删除的代码行数”与“增加的代码行数”比率。如果你需要重构和优化代码，那么请分别进行。不要找借口将所有改动都塞到一个  PR 中，这是懒惰。

相反，你应该想办法将 PR 控制在很小，这才是创造力。

2. 自我审查

创建好 PR 后，你应该进行全面的自我审查。在完成一段代码之后，你可能迫不及待地想将代码推送到 PR，然后等着其他人发现错误，尤其是你花了好几天的时间完成了一项比较大的改动时。别偷懒，要自律，你的工作还没有结束。

你可以在自我审查中，问问自己：“这个名字好吗？有没有更好的？”或者，“这个真的可以为 null 吗？”通过这样的问题，你不仅可以检查自己的代码，还可以在日常的编程工作中建立自我反思的好习惯。换句话说，这种自我审查的过程可以让你成为更好的开发人员。

3. 去掉不必要的文件

在自我审查的时候，你会经常发现某个文件只改了一些空格、调整了格式、优化了导入或一些文本更改，这些改动对 PR 根本没有影响。

遇到这种情况，你应该重新打开分支，将这些文件还原回去，你只是做了一些略微的改进，功能上没有变化，而且多余的文件出现自 PR 中只会给审核代码的人带来负担，尤其是 PR 比较大的时候。

如果格式化很重要，请创建一个单独的 PR，然后在 CI 中添加一个格式化的工具，并利用工具整理整个应用的格式。但是，避免这些不必要的文件很重要，这是对代码审核者的尊重。此外，这些无关紧要的变动还会污染 git 的历史记录，让人们很难通过这些历史记录找到文件某些更改背后的意图。

4. 创建有意义的标题

一般，标题我们都会照抄分支名称或相关的票据。关于标题的规则只有一条，即遵循某种约定，建立简洁而又意义的标题，基本思想与分支命名一样。

创建拉取请求也是创建文档，保持拉取请求的历史记录易于浏览，可以方便搜索过去的决策和思考过程。

5. 有意义的描述

再次强调，你应该将 PR 视为文档，一篇经常会被阅读的文档。PR 的描述应尽可能全面，但要简洁，尽可能做到透过描述看懂你的意图和决策过程，无需花时间讨论。

有一种有效的方法是建立 PR 模板。模板的内容应与团队达成共识，并随时间的推移进行开发和调整，下面是给新手的一些建议：

• 变更概述。你需要说明的 PR 中没有包含的方案（经过评估后被放弃的替代方法）。这样可以避免与审核代码的人重复讨论你已经尝试过的方案。

• 面向审核者的问题/注释。你希望审核者对于哪些代码提供一些具体的建议？代码的哪些部分很安全，可以忽略？你重构了哪部分代码，变动的文件虽然很多，但没有任何功能上的影响。告诉审核者可以放心地跳过哪部分 PR，他们会非常感谢你。

• 如何测试/演示。对于 QA 来说，这样的说明非常便利，比如预发布环境中的用户和密码、配置和设置说明等等，任何可以帮助审核者测试修改的内容。

• 附件：屏幕截图和视频。图片和视频的表达能力更强。变化前后的演示非常便利。

6. 确认每条评论

在远程异步通信中，有一点很重要，你需要向对方传达你看到了评论。有时，只需要一个简单的表情符号。无论评论多小，都不能忽视，尤其是在新团队中。一旦与团队建立融洽的关系，你就可以顺其自然了，因为你们之间互相都了解。但是，刚开始的时候，一定要有礼貌，注意言辞，以及个人的行为。

7. 合并需要征求每个人的同意

说起礼貌，你应该耐心等待别人提出意见，然后积极地给予回应。如果等待的时间过长，你可以通过电子邮件和即时消息询问，或者直接去找他们，让他们知道你还在等待。

在我看来，如果你们团队成员超过了 3 个人，则不必让每个人都审查每个 PR。制定一个系统来确定由谁来审查每个 PR，比如让每个人负责一些模块；如果你是新手，则可以让架构师/高级开发人员审查你所有的 PR。

— 2 —

如果你是审查者

下面的一些建议也同样适用于代码作者回复评论。

8. 签出代码

你的计算机上应该始终保有一个项目的两个克隆：一个用于正常工作，一个用于审查 PR。这样审查 PR 的时候，就不会影响到当前的任务了。

签出分支后，点击构建，并保持运行状态，同时切换到浏览器。

9. 阅读标题和说明

如果有人花了很大力气编写了自己的 PR 指南，那么你至少应该耐心地读完。在等待PR在你的另一个项目克隆上构建的同时，请阅读相关的票据，阅读 PR 的标题和说明，并提出你的审核意见。

10. 在本地验证你的建议

如果发现可以改进的地方时，请尝试在本地克隆中修改代码。当你是项目的新成员时，这一点尤为重要。即便你提出的建议无法实现，或者甚至根本编译不过去，也不必感到尴尬。在自己的 IDE 中修改代码，如果成功，你会收获满满的成就感；如果失败，你也会庆幸没有打扰到别人。

在确认你的建议可行后，不要让自己的工作白费，你可以将代码复制过去，放入 PR 注释中，这样作者就可以直接复制了。

11. 如果建议太大，就直接写成 PR

如果你发现自己的建议太大，那就不要浪费精力，直接在他们的分支上建个分支，然后创建一个 PR，合并到原来的 PR 中。这种 PR 不需要常规 PR 的花哨功能，因为它只是评论的一部分，可以让你们做进一步的探讨，然后由原作者考虑修改，最后如果一切顺利，则合并到主 PR 中。

12. 抵制评论的冲动

发表评论时，我们往往情不自禁说个滔滔不绝。克制这种情绪的关键是设身处地为他人着想。不要忘了回顾一下所有的评论，仔细想一想有多少评论确实会被多方接受，而且能尽快实现。

以下是一些关于评论的技巧：

13. 如果没有更好的替代方案，请不要发表评论

如果你不喜欢代码的写法，请提出更好的方法，否则还是闭嘴。

14. 要有信心，不要偷懒

不要使用“也许”、“我不知道”、“如果”、“我不确定”之类暗示怀疑的词语。如果不确定，那么请反省一下，为什么你不确定。或者也可以做一些实验和研究，找回自信。

15. 修改代码之前先模仿原来的风格

每个人都有自己的风格，而且都对比较执着于自己的风格。刚加入新团队时，现有成员通常都会捍卫项目的现状，而新成员则会表达“他们的前一个项目有何不同，或者如何更好地完成工作”等看法。

适应现有的风格，可以让你尽快融入心团队，而他们也更愿意针对某些重要的方面提出建议，比如 SDK 的选择、体系结构决策以及模式和实践等等。在你完全掌握了他们的风格之后，再提出现代化的风格，他们更容易接受。

16. 挑剔是好事 

有时，同事审查你的代码，只提出了一些风格上的意见，看似很挑剔，你也会感到沮丧。 

但是，你应该这样想：审查者已经很难找出你代码中的实际问题。 

遇到挑剔的意见，比如关于风格的注释，你可以礼貌地强调 IDE 工具可以自动处理好 90% 的样式问题。

17. 面对面的交流

有时，你们两人针对某个 PR 的评论，反复争论不休。这个时候，你应该冷静一下，然后写一封邮件，约个时间面对面的交流。

网上的交流有时候来来回回，很浪费时间。还不如到会议室，面对面的交流，但切记冷静，反复思考自己的观点，而且一定要保持客观。面对面交流的目的是寻找最佳解决方案。

18. 心平气和

建立 PR，难免被审查者指出问题。所以，首先最重要的就是：挑刺。但是你需要专业地挑刺，不要带个人情绪。

请注意解读评论的方式，有些人并不是故意的，他们只是没有过多的思考，很着急，或表达能力不够好。他们提的意见都是出自善意。

19. 没有紧急的 PR

PR 之所以流行，有两个原因：

1. 异步交流。开发人员可以随时进行审查和响应，这样可以避免自己的工作被打断或受干扰。

2. 质量保证。在代码进入目标分支之前，对其进行检查和测试，以确保目标分支保持干净。通过队友发现日常使用的代码中的潜在问题。

如果你必须在 10 分钟内合并分支（一般非常不推荐这种做法），那么就不要发送消息要求别人立即审核代码，直接合并就行了。不要为了流程而打扰别人。如果你必须在短时间内合并分支，那么就找一个人进行结对编程，或者直接合并PR。

— 3 —

总结

PR 是一个很好的习惯。在过去十年中，我所从事的大多数项目都采用了这种标准的做法，如今我仍在新项目中学习关于 PR 的新知识和流程。

上述建议不一定适合所有项目，与制定严格的规则和流程相比，组建团队更为重要。在团队中，我们要友善待人，但也要有信心和纪律，同时以身作则，严格要求自己。

原文链接：https://medium.com/google-developer-experts/how-to-pull-request-d75ac81449a5

声明：本文由CSDN翻译，转载请注明来源。

关注视频号，参与留言送书活动

  推荐阅读：