开发者上手指南

欢迎来到Alluxio社区,我们热烈欢迎你参与到我们的社区和对社区进行贡献。本页面提供了如何参与到Alluxio开源项目社区并成为其中一员的指导。

系统需要

最基本的需要是一台安装了Mac OS X或者Linux的电脑,目前版本的Alluxio尚未对Windows系统提供支持。

软件和相关账户准备

在向Alluxio贡献源码之前,还需要准备一些软件以及账户。

在下面的视频部分观看我们的”Alluxio新贡献者”视频!

Java 7或者8

开发Alluxio需要Java 7或者8,如果你不确定你系统上的Java版本,可以运行以下命令确认:

$ java -version

如果你还未安装Java,从Java SDK下载并安装。

Maven

Alluxio项目使用Maven来管理构建,如果你还未安装,可以先在这里下载Maven,并按照 Maven官方文档进行安装。

Git

Alluxio使用Git分布式版本控制系统来管理源码,因此需要安装Git。

如果你还未安装git,请先进行安装

GitHub账户

Alluxio源码托管在GitHub上,仓库地址为Alluxio repository

你需要一个GitHub账户来贡献源码,如果还没有,请先注册一个GitHub账户

另外你还需要知道你的GitHub账户绑定了哪个邮箱

Jira账户

Alluxio开源项目使用JIRA来跟踪特性、bug以及问题。请创建一个Alluxio JIRA账户,从而能够新建、跟踪以及修复ticket。

创建一个Alluxio JIRA账户来新建tickets,跟踪tickets以及为tickets提供修复。如果不能通过上述链接建立JIRA账户,请按下述格式发送邮件至jira-admin@alluxio.org:

Subject: JIRA Account Request
Body:
	Email Address: example@example.com
	Username: JohnS
	Full Name: John Smith

Fork Alluxio源代码库

在向Alluxio贡献源码之前,你首先需要fork Alluxio源代码库。如果你还未这么做,先进入Alluxio仓库,再点击页面右上角的Fork按钮, 之后你便有了Alluxio源代码库的fork了。

在fork Alluxio源代码库后,你需要从该fork创建一个本地的副本,这会将该fork里的文件拷贝到你的本地电脑。使用以下命令创建副本:

$ git clone https://github.com/YOUR-USERNAME/alluxio.git
$ cd alluxio

这会将副本拷贝在alluxio/目录下。

为了将远程的Alluxio源码改动更新到你本地的副本中,你需要创建一个指向远程Alluxio源代码库的源。在刚拷贝的副本的目录下,运行:

$ git remote add upstream https://github.com/Alluxio/alluxio.git

运行以下命令可以查看远程仓库的url:

$ git remote -v

这会显示origin(你的fork)以及upstream(Alluxio仓库)的url。

配置Git邮箱

在向Alluxio提交commit之前,你需要先确认你的Git邮箱设置正确,请参考该邮箱设置指南

编译Alluxio

既然你已经有了Alluxio源码的一个本地副本,那现在就可以编译Alluxio啦!

在本地副本目录下,运行以下命令编译Alluxio:

$ mvn clean install

该命令会编译整个Alluxio,并且运行所有测试,这可能会花费几分钟。

如果你仅仅只需要重新编译,而不需要运行检查和测试,可以运行:

$ mvn -T 2C clean install -DskipTests -Dmaven.javadoc.skip -Dfindbugs.skip -Dcheckstyle.skip -Dlicense.skip

这应该用不到一分钟。

这里有更多编译Alluxio的细节

领取一个New Contributor JIRA Ticket

Alluxio的ticket中有许多不同的等级,它们分别是:New ContributorBeginnerIntermediateAdvanced。新的开发者应该在进行更高级的任务之前先完成两个New Contributor任务。New Contributor任务非常容易,不需要了解过多的关于代码的细节;Beginner任务通常只需要修改一个文件;Intermediate任务通常需要修改多个文件,但都在同一个包下;Advanced任务通常需要修改多个包下的多个文件。

我们鼓励所有新的代码贡献者在进行更难的任务之前先完成两个New Contributor任务,这是帮助你熟悉向Alluxio贡献源码的整个流程的好方法。

请浏览任何的未关闭的New Contributor Alluxio Tasks并找到一个还未被他人领取的任务,你可以点击Assign to me链接来领取该ticket。另外你应该在你开始进行该任务之前先领取它,从而其他人知道你在完成这个ticket。

注意所有的Alluxio JIRA ticket都名为ALLUXIO-####,其中####是一个数字。当你创建一个pull request的时候,这个名称就非常重要了,这个pull request的标题应该像[ALLUXIO-XXXX] Awesome Feature这样。

在本地副本中创建一个新的分支

在领取ticket之后,切换到终端下,进入本地副本的目录,现在,我们开始动手修复吧!

要向Alluxio提交一个修改,最好是为每一个ticket单独建一个分支,并且在该分支下进行修改。以下命令将展示如何创建一个新的分支。

首先,确保你在本地副本的master分支下,运行以下命令切换到master分支:

$ git checkout master

接着,你应当确保你的master分支里的代码与最新的Alluxio源码同步,可以通过以下命令获取所有的代码更新:

$ git pull upstream master

这将会获取到Alluxio项目中所有的更新,并合并到你的本地master分支里。

现在,你可以新建一个分支来进行之前领取的New Contributor啦!运行以下命令创建一个名为awesome_feature的分支:

$ git checkout -b awesome_feature

这会创建该分支,并且切换到该分支下。现在,你可以修改相应的代码来处理该JIRA ticket啦!

提交本地commit

在你处理该ticket任务时,可以为修改的代码提交本地的commit,这在你完成了一个阶段性的修改时特别有用。运行以下命令将一个文件标记为准备提交阶段:

$ git add <file to stage>

一旦所有需要的文件都进入准备提交阶段后,可以运行以下命令提交包含这些修改的一个commit:

$ git commit -m "<concise but descriptive commit message>"

如果想了解更多信息,请参考该commit提交指南

提交一个Pull Request

在你完成了修复该JIRA ticket的所有修改后,就马上要向Alluxio项目提交一个pull request啦!这里是一个提交一个pull request的详细指南,不过以下是通常的做法。

在你提交了所有需要的本地commit后,你可以将这些commit推送到你的GitHub源代码库中。对于awesome_feature分支,运行以下命令推送到GitHub上:

$ git push origin awesome_feature

这将会把你本地的awesome_feature分支下的所有commit推送到你的GitHub上Alluxio fork的awesome_feature分支中。

一旦将所有的修改推送到了fork中后,访问该fork页面,通常上面会显示最近的修改分支,如果没有,进入你想提交pull request的那个分支上,再点击New Pull Request按钮。

在新打开的Open a pull request页面中,base fork应该显示为Alluxio/alluxio,并且base branch应该为master,head fork为你的fork,并且compare branch应该是你想提交pull request的那个分支。

对于这个pull request的标题,它应该以这个JIRA ticket名称为前缀,因此,这个标题应该像[ALLUXIO-1234] Awesome Feature这样(在标题里面,请用和你的request相关的信息替换掉 Awesome Feature,例如,”Fix format in error message”或者”Improve java doc of method Foo”)。

在描述框的第一行,请添加一个该JIRA ticket的链接,该链接像https://alluxio.atlassian.net/browse/ALLUXIO-####这样。

完成以上步骤后,点击下方的Create pull request按钮。恭喜!你向Alluxio的第一个pull request成功提交啦!!

审阅Pull Request

在pull request成功提交后,可以在Alluxio源代码库的pull request页面看到它。

在提交后,社区里的其他开发者会审阅你的pull request,并且可能会添加评论或者问题。

在该过程中,某些开发者可能会请求你修改某些部分。要进行修改的话,只需简单地在该pull request对应的本地分支下进行修改,接着提交本地commit,接着推送到对应的远程分支,然后这个pull request就会自动更新了。详细操作步骤如下:

$ git add <modified files>
$ git commit -m "<another commit message>"
$ git push origin awesome_feature

在该pull request中的所有评论和问题都被处理完成后,审查者们会回复一个LGTM。在至少有两个LGTM后,一个管理员将会将你的pull request合并到Alluxio源码中。

祝贺!你成功地向Alluxio贡献了源码!非常感谢你加入到我们的社区中!!

视频

挑战更高级的任务

在你完成两个New Contributor任务之后,就可以尝试完成一些Beginner Alluxio tickets了。

欢迎加入Alluxio社区!

Need help? Ask a Question