拥抱开源，参与开源·从贡献一次PR开始

背景

猪厂一年一度技术盛宴已经拉下帷幕，在今年的网易技术奖评选中，涌现了很多的优秀的项目。而在技术奖的评选当中，有开源引入奖、社区贡献奖、自研开源奖三大奖项是与开源项目密切相关的。相信很多同学在平时项目开发当中，都有使用过大量的开源项目所提供的丰富且强大的功能，为我们的业务系统插上翅膀。肯定也有很多同学想要为自己在业务当中经常使用的一些开源项目贡献自己的一份力量，为开源社区添砖加瓦的同时，也能正向反馈于我们的业务系统当中。

然而，或许很多同学都因为无人指导或找不到比较完整的首次参与开源贡献的资料而止步不前，无法迈出参与社区开源贡献的第一步，贡献自己的第一个PR。

今年，我们团队有幸参与了网易技术奖·社区贡献奖的奖项角逐，并且最终我们参与社区贡献的项目AntDesign/ProComponents也有幸获得了最终的社区贡献奖的奖项。因此，借此机会给大家分享一下我们首次参与社区贡献的一些经验与实践，希望能为有意参与开源社区贡献的同学，提供打开社区贡献之门的钥匙，指引一个相对明确的方向与道路。

基本概念

社区身份

我们先来看一下在开源社区当中常见的几种身份：

Contributor: 项目的贡献者，首次将代码合并到主干分支（master或main）时授予。
Committer/Collaborator
- Committer: 提交者，被授予仓库写入权限的人
- Collaborator：合作者
  
  假如A创建了一个github仓库，A在他github项目主页的Settings------Collaborators里面进行添加，邀请B为合作者。B在收到邀请提醒后，可选择接受邀请。B此时拥有了A所创建项目的直接读写权利。
Member：组织成员

在github当中可以创建组织Organization，而Member就是这个组织的成员，组织的所有者可以根据情况给该组织下的成员分配不同的权限。
Maintainer/owner：仓库维护者，拥有该组织的所有权限

其他关键流程概念

在了解了github当中各种角色身份的含义之后呢，我们再来看一下经常接触的一些概念。

ISSUE：议题，在这里你可以发表一些对于这个项目的一些意见、建议、提bug、询问项目使用的一些细节问题等等，项目的Contributor和维护者会在这里面查看一些项目的Bug或者是合理的可行的功能需求进行修复或需求开发。
- Tag：标签
  
  我们在看ISSUE的时候，可以注意一下标题右侧的标签，这些标签是项目的维护者或合作者为当前的ISSUE打上的特殊标签，用于对ISSUE进行分类。比如说，如果我们想要提自己人生中第一个PR,那么你可以在ISSUE列表当中，查找一下是否有类似help wanted或pr Welcome的标签,因为打上这个标签的ISSUE就说明这个问题是经过了项目维护者审核，觉得提出的这个问题是正确的，并且向该问题的提出者或其他人征集解决这个问题或实现这个建议的PR.我们针对这样的ISSUE提的PR,大概率是能被项目维护者采纳的。
  
  我们在查看ISSUE时，可以优先看看这个ISSUE上打上的标签，能够帮你更高效的查找问题。
Fork：分支，我们可以使用这个功能在自己的账号下面将目标项目仓库相关分支的代码复制下来，在复制下来的仓库基础上进行开发
PR：Pull Request，即拉取请求，当你在自己的仓库下完成了开发，想让目标项目拉取你的更改合并到主分支时，就需要向那个目标项目的目标分支提PR,注意，你提的PR不一定是合并到主分支，有一些大的改动，可能会要求合并到feature、next之类的未来分支，因此，在提PR之前，最好先跟项目维护者确认好，我们这个更改应该合到哪个分支。
Review: 所有的PR都需要经过项目维护者或合作者的Review之后，才能被合入目标分支，我们提了PR之后，需要留意这些审查者所提出的疑问与建议，及时的答复，否则，这个PR可能会被直接关闭掉。
Approve：在Review时，如果项目维护者或合作者认为这个实现思路没什么大问题，会自提交review结果的同时，将当前这个PR标记为Approved,即接受你这一次的变更，那么，你只需要将review中提的建议修改好，邀请对方重新review一下即可。

检出项目

好了，了解了相关的基础概念之后，我们正式来看一下如何参与开源贡献吧。首先，就是检出项目。

当我们选择好了我们想要参与贡献的目标项目之后，我们只需要打开该项目github首页，点击右上角的fork按钮

然后在这个页面上，点击Create fork即可在你自己的账号下面复制一个这个项目的仓库了。其中Owner通常就是你自己的账号，无需修改，但如果你曾经加入过某个github的组织的话，你还可以将这个项目复制到该组织的空间下面。

上面操作完之后，我们就可以直接在github首页上搜索相关的关键字看到我们复制到自己的空间下面的项目了，进入这个项目当中，复制项目的Clone链接，将项目克隆到你的电脑上，如果是前端项目，通常在代码检出之后，我们需要先运行一下npm install或yarn安装一下项目依赖。至此，我们开发前的准备工作就已经完成了。

贡献第一个PR

签署协议

有一些项目，如react，如果你想要参与该项目的社区贡献的话，需要与这个项目签署一个协议，如CLA协议（Contributor License Agreement(贡献者许可协议，简称CLA)）。当然，并不是所有的项目都要求签署这个协议，具体还得看每个项目的要求。这边以react项目为例，带大家看一下应该如何签署CLA协议。

React Cla 协议地址

如果大家是以个人的身份参与开源社区贡献，那么选择第一个即可，如果是以公司组织的身份参与，则选择右侧的选项。我们这边就介绍一下个人参与社区贡献的例子：

我们只需要按照提供的表单填写相关的信息即可。然后拉到最下面，勾选I agree后点击submit按钮即可完成协议的签署了。

确定要贡献的内容

我们在正式开发之前，需要先确定自己本次要开发的内容是什么？是修复一个bug 还是新增一个新特性，又或者是修改文档，还是打包脚本。至少我们得先明确目标，之后才能有的放矢。当然，大家在贡献第一个PR时，可能会存在迷茫，不知道该做什么。那么你就可以像刚刚我介绍ISSUE的标签中所说的，去目标项目的ISSUE列表当中，找一下有没有一些打了help wanted或pr welcome之类标签的ISSUE,甚至有一些项目，为了让初次参与开源贡献的同学能够更容易上手，会给这个pr标记上难度级别，如：easy for first pr，如果看到这样的标签，不要犹豫，在那个ISSUE下面回复一下说明自己想要做这个任务，以免跟别人做了重复的工作。这种类型的issue通常非常抢手，说不定你一刷新就不见了，所以，很多时候还是得看手速和是否能够当机立断。

检出新分支并开发

确定了需要贡献的内容之后，我们就可以检出一个新分支开发时开发了，在此，这边为大家提供一些检出分支的分支名的规范建议，这样可以更好的分类和管理你的本地分支。当然，不按照这个规范也是可以的。

这边推荐我们常见的的分支可以使用：修改类型/ISSUE的id的形式，如：feat/ISSUE-ID 或 feat/title格式，这样，以后我们需要看这一次的提交究竟在做什么时，就可以直接通过issue的id找到原始问题，了解上下文了。如果你这次提交的更改与ISSUE无关，那么可以将ISSUE的ID换成本次修改的简要英文描述。

feat: 新特性，通常是想要新增一些以前没有的新功能时使用
fix: Bug修复，用于修复一些你发现的或者是ISSUE上提出的问题
docs：相关的文档的改动，如README文档等
refactor: 重构代码，对已有的逻辑进行重构
ci: 跟gitlab的CI工作流有关的改造，如修改ci测试脚本等，但这个通常只有committer或Collaborator才允许去修改。
chore: 杂项，如更新测试用例的快照等等其他难分类的工作

当检出分支之后，我们就可以正式开始本次的开发了。

更新文档与示例

很多时候，我们不仅仅是要修改相关的代码，在修改完代码之后，我们最好能够提供一下相关的一些文档描述，比如说你新增了一个新组件，这个组件都有哪一些新特性，用来干什么的，都有哪些属性，怎么调用等等，同时需要提供一些能够说明新增特性特点的一些demo。

单元测试

代码和文档都完成了之后。我们接下来就需要对我们的项目进行单元测试，检测一下本次的修改是否会导致已有的一些逻辑和组件的测试用例不通过。原则上来说，我们如果新增了新的特性或者修改了bug,如果发现这些代码没有被已有的测试用例覆盖到，我们都应该主动的为这些代码增加相关的测试用例，用以保证我们代码的可靠性，以及后续有其他人修改代码时，不会导致一些关键功能的异常。

拿ProComponents这个项目来举个例子吧：

我们之前新增了一个ProFormMoney组件了之后，就需要在相关的测试用例目录上，为我们这个新的组件的核心功能添加上尽可能完善的单元测试，很多项目都对代码的测试用例覆盖率有一定的要求，如果达不到要求，该项目将拒绝这一次的PR。因此，学会为我们们新增的代码编写相关的测试用例，也是极为重要的一件事情。

本人认为，一个优秀的开源项目，他的测试用例就是该项目最好的开发文档了，因为你可以在测试用例当中看到各种你在开发文档当中根本就看不到的一些细节和边界情况的测试，这能够让你更加了解这个项目。

代码格式化与检测分包依赖

测试用例都写完了，并且确定了已有的所有测试用例都通过后，我们就可以进入提交前的最后一步准备了。有一些项目，并没有添加pre-commit钩子，在我们提交代码之前用统一的规范格式化项目代码，那么，我们可能就需要自己按照当前项目的格式化规范，格式化一下项目代码，以免因为格式原因导致其他人检出代码时出现冲突。

除此之外，目前很多大型的前端开源项目都是采用分包管理的模式进行开发，一个github项目下面可能涉及到多个分包，我们在提交之前，也需要人工或者是通过脚本的形式（脚本方式参考：检测依赖脚本），检查一下本次更改时新增的一些依赖有没有装错地方（有时我们的依赖或许被装到了项目的根目录，但我们这个依赖实际实在A分包当中使用的，如果我们没有在A分包的package.json的依赖列表当中添加该依赖的信息，就会导致其他人安装该项目的时候，该依赖没有被自动安装上而导致异常）。

提交规范

已经完成了所有的准备工作了，接下来我们就可以提交代码了。不同的项目，都有各自不同的一些提交规范，不过，目前绝大多数的项目的提交规范都是参考Angular的代码提交规范，相信大家平时开发时也都差不多，这边就不再赘述了，不了解的同学可以去这个网址看一下。Angular代码规范。

创建一个新的PR

好了，我们的代码提交到我们自己fork下来的仓库之后，接下来就可以准备向目标项目提PR了。

当代码推送到了你自己fork的远程仓库之后，我们再次打开fork下来的项目首页，就可以看到这边有一个提示，我们直接点击按钮就可以开始提PR了。

通常，大部分的项目都会创建一些PR的模版文件，我们一打开这个页面就会把模版回填进去。当然有一些项目可能没有，那么就需要你为你这一次的PR进行较为详细的描述了，需要注意的大概有这几点：

PR标题：这边建议标题采用的格式为：type(模块名称，如table): 本次修改的简要英文描述（为什么不用中文呢？我们不得不承认，在计算机领域来说，国外的发展还是相对领先的，而开源项目是面向全球用户的，如果你参与的是一个大型的国际化的项目，建议还是用英文描述会好一点，当然，如果你所参与的项目绝大部分的用户都是国内用户，那么用中文也是可以的）
PR内容：
1. 标注本次PR的类型，究竟是新特性、bug修复、还是文档修改
2. 关联issue，如果本次修改是在修复某个issue的问题或者完成某个issue的功能，需要在内容中关联一下
3. 写一下你大概的实现思路与想法，方便项目维护者理解你的意图
检查你所提交的文件是否正确，有没有漏提交的，或者是哪里写错的。

最后，我们点击按钮提交，你人生中第一个PR就这么产生了。

检查CI执行结果及review反馈

已经提交了人生中第一个PR是不是觉得很开心呀，不过不要高兴得太早哟。

当提交PR之后，github会自动触发相关的CI任务对项目的一些关键环节进行检查，比如运行测试命令，看一下有没有不通过的，运行一下代码覆盖率测试脚本，看看覆盖率达不达标，运行检测changelog脚本，检测你是否有提供changelog等等。只有当这些CI脚本都通过了（或者是没有出现因为本次PR而造成的CI脚本失败的情况），才算是一个准备好让其他人review的PR。

目前我们仅仅只是给项目维护者发送了拉取请求，但至于收不收，还得看你的代码质量以及他们是不是想要你这个功能。所以，在提交完PR之后，我们在几天内，需要密切关注一下自己github中所绑定的邮箱，是否有收到github发过来的项目维护者或合作者的review结果。我们需要及时的回复review的时候提出的问题，不然我们的PR很可能被直接关闭掉哟。

合并至目标分支完成PR

经过了review之后如果没什么问题，项目维护者或合作者就会将你的PR合并到目标分支上去

查看社区贡献的数据

如果我们想去看一下自己为这个项目总共贡献了多少个PR的话，可以访问上述链接："项目github首页的路径/commits?author=你的github id"。如：https://github.com/ant-design/pro-components/commits?author=kiner-tang

或者通过目标项目右下角的Contributors进去查看，不过这边最多只显示贡献排名前100的用户信息。

视频录播传送门

结语

至此，我们已经介绍了完成一个PR所需要做的所有流程了，不知道各位同学有没有蠢蠢欲动，想要参与进开源社区的开源贡献当中呢？那就行动起来吧。开源之所以强大，就是因为社区接收不分身份、年龄、性别、种族、信仰、区域的数之不尽的社区贡献者的优秀贡献，众人拾柴火焰高，这可不是单单某一个企业能比的。