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

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

作者 | Nick Skelton
译者 | 弯月    责编 | 苏宓
出品 | CSDN(ID:CSDNnews)

以下为译文:

如果你是 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 之所以流行,有两个原因:

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

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

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

总结


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

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

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

声明:本文由CSDN翻译,转载请注明来源。

60+专家,13个技术领域,CSDN 《IT 人才成长路线图》重磅来袭!

(0)

相关推荐