在 GitHub 上提交代码必备指南！
【CSDN 编者按】你是否经常参与开源项目？如果在 GitHub 上参与开源项目的 Pull Request，你知道正确的做法是什么吗？别担心，本文为你准备了详细的指南，希望对你有一定裨益。
以下为译文：
如果你是 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。
如果你是审查者
下面的一些建议也同样适用于代码作者回复评论。
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 之所以流行，有两个原因：
异步交流。开发人员可以随时进行审查和响应，这样可以避免自己的工作被打断或受干扰。
质量保证。在代码进入目标分支之前，对其进行检查和测试，以确保目标分支保持干净。通过队友发现日常使用的代码中的潜在问题。
如果你必须在 10 分钟内合并分支（一般非常不推荐这种做法），那么就不要发送消息要求别人立即审核代码，直接合并就行了。不要为了流程而打扰别人。如果你必须在短时间内合并分支，那么就找一个人进行结对编程，或者直接合并PR。
总结
PR 是一个很好的习惯。在过去十年中，我所从事的大多数项目都采用了这种标准的做法，如今我仍在新项目中学习关于 PR 的新知识和流程。
上述建议不一定适合所有项目，与制定严格的规则和流程相比，组建团队更为重要。在团队中，我们要友善待人，但也要有信心和纪律，同时以身作则，严格要求自己。
原文链接：https://medium.com/google-developer-experts/how-to-pull-request-d75ac81449a5
声明：本文由CSDN翻译，转载请注明来源。
60+专家，13个技术领域，CSDN 《IT 人才成长路线图》重磅来袭！