如何在GitHub上向开源项目贡献代码

相信很多人都曾怀揣着参与开源项目的梦想,或为了简历好看,或为了其他理由,但是却苦于不知道如何去参与,终不能成行。

这篇博客主要介绍一下向开源项目贡献代码(水PR)的全流程。

如何寻找贡献点

想参与开源项目,但是淹没在代码的海洋里,不知从何处下手,这一点大概是难倒了一大半的人吧。

之前听说过一个笑话,每年一到最后一天,元旦伊始,总有人抢着去给知名开源项目提交PR,内容就是把Copyright里面的年份更新一下^_^。

其实很多开源项目都有参与指南,会告诉你可以从哪里开始。一般来说,会涉及到一些文档的修改,代码格式规范方面的内容。

对于一个开源项目,我们首先肯定需要去了解它是做什么的,不免就要去阅读文档,在阅读文档的过程中很可能就发现单词拼写错误、语法错误、表意不明等等错误。如果它有中文版文档的话那么难度进一步降低,仔细检查一下标点符号、翻译等等,也许会有意外的收获。如果这些都已经很好了,那么就去对比一下中英文的版本,看看中文版本是否还没有更新。

除了文档修改,还有一个办法就是去clone下来以后,用IDE的代码审查,看看有没有一些提示,比如java的lambda语法等等。不过不同的社区对这种修改的态度可能不同,可以去参考一下历史PR,也可能会有新的发现。

以下我以一个提升 Alluxio 项目中的中文文档可读性的PR为例,介绍提交 PR 的每一个步骤。

这是 PR链接

fork 到自己的账号

首先打开 Alluxio 的 GitHub 仓库页面,然后点击右上角的 Fork

fork alluxio

然后我们的账号下就会出现一个名为alluxio的仓库。

clone 到本地

1
git clone https://github.com/newnius/alluxio.git

把仓库名换成你自己的

我这里是选择了用命令行clone,然后再用 IDE 打开(IntelliJ),你也可以直接在 IDE clone,不过似乎有一些问题。

如果你的机器上没有配置maven的话需要配置一下,这里就不涉及了。

如果是用 IDE 打开的话,会自动下载很多的maven依赖,需要等待一段时间,让他后台下载就行。

新建 docfix 分支

对于一个多人参与的项目来说,在修改之前先新建自己的分支,然后合并到主分支是一个推荐的方式。

1
git checkout -b docfix

找到相应的文件进行修改

打开 docs/cn/FAQ.md 文件,然后修改相应的地方。

提交你的修改

在提交之前,首先检查一下你做了哪些改动(因为有时候IDE会不自觉的改动一些奇怪的文件)

1
git status

确认无误之后commit你的改动

1
2
3
git add . -A

git commit -am '[DOCFIX] Update Chinese document'

把你在本地做的修改提交到 git 中。

测试修改是否符合要求

为了避免不同人的代码格式和文档规范等等,一个成熟的项目通常会有着很较全的检查机制,审查代码风格、正确性等等。

1
mvn clean install

测试包括代码风格检查、样例检查等等,后者需要配置相关的环境而且会耗费较长的时间。

如果我们仅修改了文档,是肯定不会正确率方面的问题的,可以跳过样例测试只检查代码风格。

1
mvn clean install -DskipTests

不过这通常也会耗费一段时间,如果不是胸有成竹,不建议跳过。

同步远程分支

对于一个很活跃的项目来说,很有可能在你修改的时候原始文件发生了变化,所以需要先同步原始项目的修改并合并到本地。

1
2
3
4
5
git remote add upstream https://github.com/Alluxio/alluxio.git

git fetch upstream

git merge upstream/master

这步可以在测试之前,也可以在测试之后,不过如果是修改了代码逻辑什么的,建议合并之后再测试一遍。

push到GitHub远程仓库

1
git push origin docfix

创建Pull Request

打开你的远程仓库页面,会看到GitHub提示你的版本更新,然后点击 New pull request 按钮,

create pull request

然后就会跳转到 Alluxio 的官方仓库,选择目标分支和修改分支,前面是alluxio的分支,一般是master,后面是你自己新建的分支docfix,

create pull request

然后用力猛击 Create pull request,填写PR标题和内容,一般来说开源项目的PR有各种要求,建议先阅读一下,比如Alluxio就要求标题用 [DOCFIX][SMALLFIC]等开头,且后面第一个单词字母要大写。

create pull request

内容大概说一下你改了啥,然后确认Create pull request

于是你就创建了一个Pull Request。

签署协议

对于小项目来说,可能没有那么多麻烦,提交pr就结束了,但是大的开源项目会要求你去签署一个协议,大概内容就是允许遵循项目的开源协议、允许使用啥的(只用签署一次)。

刷新一下刚刚的pr页面,就会看到 alluxio-bot 自动加上了 cia-missing 标签,并提醒你还需要签署一个协议。

cia-missing

点一下给的链接,会跳到登陆页面,选择 Sign in with GitHub,在新的授权页面选择Authorize Alluxio确定授权登陆。(这里提示一下,不要随便授权)

sign in with GitHub

在新的页面填写你的名字和邮箱,然后确定

sign

提示有一封邮件已经发到了你的邮箱,

在邮箱里找到这封邮件,然后点击里面的 view document 链接

sign

拖到最下面(当然了,作为一个有良好法律意识的人,建议在签署任何文件之前先通读一遍,不然你可能就把自己给卖了,这是一个好习惯)

点击 Sign,会让你签字,可以选择自己手写一遍,不过他也提供了默认的格式,选择 adopt and sign 就行。

sign

下面再填上你的名字和头衔,再点击右上角的 finish ,接着点一下 continue, 签署就算是完事了。(你签署的协议副本也发送到了你的邮箱)

sign finished

再次打开 https://cla.alluxio.org/status 这个页面,就能看到下面的status变成了completed。

回到我们的pr页面,就会看到 alluxio-box 把cia-missing标签去掉了。

sign finished

等待

接下来就需要等待了,一般来说,成熟的开源项目会集成自动化测试,会自动对pr进行测试,
等待一段时间之后如果没有太大问题就会收到测试通过、已经分配维护者review的邮件了。

test passed

如果有提示错误,就需要根据错误信息修改一下,然后push到自己的仓库下docfix分支,GitHub会自动跟踪这个变化。

最后的等待 merge 就不贴图了,大概不久的将来状态就会变成 merged 吧。。。

总结

上述就是一个完成了向开源项目贡献代码的全流程。一般来说,分为寻找修改点、fork到自己账号下、修改并提交改动到自己的仓库smallfix分支下、创建pr、签署协议、等待merge这几个步骤。