开发指南

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

系统需要

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

软件和相关账户准备

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

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

Java 8

开发Alluxio需要Java 8，如果你不确定你系统上的Java版本，可以运行以下命令确认：

$ java -version

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

Maven

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

Git

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

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

GitHub账户

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

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

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

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任务

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

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

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

注意所有Github Issue都有一个对应的数字。当你创建一个pull request的时候， 请在该Issue的描述中加入 “Fixes Alluxio/new-contributor-tasks#123”，”Fixed Alluxio/new-contributor-tasks#123”， “Fix Alluxio/new-contributor-tasks#123”，”Closes Alluxio/new-contributor-tasks#123”， “Closed Alluxio/new-contributor-tasks#123” 或者 “Close Alluxio/new-contributor-tasks#123”。

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

在领取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

这会创建该分支，并且切换到该分支下。现在，你可以修改相应的代码来完成该任务啦！

提交本地commit

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

$ git add <file to stage>

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

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

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

提交一个Pull Request

在你完成了该Issue的所有修改后，就马上要向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的标题，它应该像Awesome Feature这样（在标题里面，请用和你的request相关的信息替换掉 Awesome Feature，例如，”Fix format in error message”或者”Improve java doc of method Foo”）。

If this pull request is addressing a Github issue, please add a link back to the issue in the first line of the description box. For example, if this pull request aims to solve Github Issue 1234 include “Fixes #1234”, “Fixed #1234”, “Fix #1234”, “Closes #1234”, “Closed #1234”, or “Close #1234” in your pull request message. If the issue is from new contributor tasks, prefix the number “#1234” with repository name “Alluxio/new-contributor-tasks”.

如果这个pull request是解决某一个Github Issue， 在描述框的第一行，请添加一个该Issue的链接，例如 “Fixes #1234”，”Fixed #1234”，”Fix #1234”，”Closes #1234”， “Closed #1234”或者”Close #1234”。 如果这个Issue是从新手任务仓库中选出的, 在issue的数字比如”#1234”前加上该仓库的名称 “Alluxio/new-contributor-tasks”.

完成以上步骤后，点击下方的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贡献了源码！非常感谢你加入到我们的社区中！！

视频

下一步

新开发者可以通过以下资料和教程来进一步熟悉并贡献Alluxio:

1. 本地运行Alluxio
2. 集群上运行Alluxio
3. 阅读配置文档和命令行相关操作
4. 阅读示范代码
5. 编译Alluxio源代码
6. Fork Alluxio源代码库，为一两个文件添加单元测试或者javadoc，并提交一个pr。您也可以在我们的Github Issues中寻找待解决的问题。以下是未分配的新贡献者任务列表，我们不建议每个新开发者完成超过两个初学者任务，在尝试完初学者任务后，欢迎参与贡献初级/中级任务。您可以在google网上论坛Alluixo Users上讨论或询问问题。相关教程请参阅GitHub指南fork代码库和提交Pull Request

欢迎加入Alluxio社区！