开发指南

Slack Docker Pulls GitHub edit source

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

软件要求

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

我们建议您先按照基于源码编译Alluxio 指南克隆并编译Alluxio源代码

软件要求

  • 所需软件:
    • Java 8
    • Maven 3.3.9+
    • Git

帐户准备

Github帐户

您需要有一个GitHub帐户才能向Alluxio代码仓库贡献代码。

您需要知道您的GitHub电子邮件地址才能进行贡献。 您可以在个人资料电子邮件设置中找到你的邮件地址。

配置您的Git电子邮件

在向Alluxio提交代码之前,您应该确认你的Git电子邮件设置正确。 请访问有关设置电子邮件的说明。.

分叉Alluxio代码仓库

为了向Alluxio贡献代码,您先需要分叉Alluxio代码仓库。 如果您还没分叉代码仓库,您可以访问Alluxio代码仓库并按页面右上角的Fork按钮。 之后,您将拥有自己的Alluxio代码仓库分支。

分叉Alluxio代码仓库之后,应创建分叉代码仓库的本地克隆。 这会将您分叉的文件复制到您的计算机上。 您可以使用以下命令克隆您的分叉:

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

这将在alluxio/目录下创建克隆。

要将更改从开源Alluxio原始代码库提取到克隆中,您需要创建一个指向Alluxio原始代码库的新远程代码存储库。 要添加新的远程代码存储库,请在新创建的克隆目录中运行:

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

这将创建一个称为upstream的远程代码仓库指向Alluxio原始代码仓库。 您可以用以下命令查看远程代码仓库的URL:

$ git remote -v

这会显示远程代码仓库的URL,包括origin(您的分叉)和upstream(Alluxio原始代码仓库)。

编译Alluxio

您现在可以编译Alluxio!

在本地克隆目录中,使用以下命令编译Alluxio:

$ mvn clean install

这将编译所有的Alluxio,并运行所有测试。取决于您的硬件,这可能需要几分钟到半小时才能完成。

如果您想重新编译而不运行所有检查和测试,运行:

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

此编译所花时间应少于1分钟。

这里有更多 编译Alluxio源代码的细节

领取一个New Contributor任务

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

我们建议所有新的贡献者在执行更高级的任务之前,先解决两个New Contributor任务。这是使自己熟悉为Alluxio项目做贡献的整个过程的好方法。

看一些在”Open”状态的“新的Contributor Alluxio任务”,然后找一个没分配的任务。为了自我分配或接收调查表,请在问题中留下评论,例如/assign @yourUserName,以表明您正在处理该问题。 在开始解决问题单之前,您应该将问题单分配给自己,以便社区中的其他人知道您正在处理和完成问题单。

注意所有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”。

在克隆中创建分支

找到一个任务后,回到终端并转到本地克隆的目录下。 您可以开始解决问题了!

为了提交更改给Alluxio,最佳实践是在一个单独分支中完成对您针对一个问题的所有更改。以下内容介绍如何创建分支。

首先,确保您在您克隆的master分支中。运行以下命令切换到master分支:

$ git checkout master

然后,您应确保您的master分支与不断发展的Alluxio原始代码库中的最新更改保持同步。运行以下命令来提取项目中所有最新更改:

$ git pull upstream master

这将会从upstream仓库的master分支中获取到所有的更新,并合并到你的本地master分支里。

现在,您可以创建一个新分支来处理您之前领取的New Contributor任务。创建分支名称为awesome_features,运行:

$ git checkout -b awesome_feature

这将创建分支,并切换到该分支。您可以修改必要的代码以解决该问题。

创建本地提交

在你处理该任务时,您可以创建代码的本地提交。 当您完成一部分很明确的阶段性修改后,这将很有用。 运行以下命令将一个文件标记为准备提交阶段:

$ git add <file to stage>

在所有合适的文件都准备好提交之后,可以运行以下命令提交包含这些修改的一个commit:

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

请阅读Alluxio编码惯例以获取更多详细信息和有关如何更新Alluxio源代码的提示。

如果您想要更多有关创建提交的信息,请访问有关如何创建提交的说明

提交一个Pull Request (PR)

完成所有解决问题所需修改后,您可以向Alluxio项目提交Pull Request了!这是有关提交Pull Request的详细说明,但是以下是通常做法。

创建所有必要的本地提交后,可以将所有提交推送到你在GitHub中的代码仓库中。针对您的awesome_feature分支,可以使用以下命令推送到GitHub:

$ git push origin awesome_feature

这会将您在本地分支awesome_feature中的所有新commit,推送到您的Alluxio分支中的GitHub中的awesome_feature分支中。

将所有更改推送到分支后,请访问您的Alluxio的GitHub分支。通常,Github会显示您的哪个分支最近已更新,但如果未更新,直接选择要提交Pull Request的分支(在本示例中为awesome_feature),然后按新Pull Request按钮。

在提交新Pull Request页面中,基础分支应为Alluxio/alluxio,基础分支应为master。头分支将是您的分支,而compare分支应是您要提交Pull Request的分支(在此示例中为awesome_feature)。

Pull Request标题

使用有效的Pull Request标题很重要。这里有一些非常好的PR标题的提示和惯例。这些提示和窍门是从现有非常好的 提交信息规则中改编而成的。

  • 标题不能太长(<〜50个字符),也不能太短(描述清楚)
  • 标题应以祈使动词开头
  • 标题的第一个单词应大写(英文)
  • 标题不应以句号结尾

这些规则有一些例外。 标题开头前可以加前缀。 前缀全大写,并与标题的其余部分用一个空格隔开。 下面是一些可用前缀。

  • [DOCFIX]: 这是为更新文档的PRs
    • 例子:‘[DOCFIX]更新入门指南’,‘[DOCFIX]添加GCS文档‘
  • [SMALLFIX]:用于很小不会更改任何逻辑的PRs修改,例如拼写错误
    • 示例:‘[SMALLFIX]修复AlluxioProcess中的错字’,‘[SMALLFIX]改进GlusterFSUnderFileSystem中的注释格式’

Pull Request说明

写一个好的PR描述也很重要。 以下是有关非常好的PR描述的一些提示和惯例,这些提示和窍门是从现有非常好的 提交信息规则中改编而成的

  • 描述此PR更改的内容以及更改原因
  • 描述应包括此更改的任何正面和负面影响
  • 描述中的各段应以空白行分隔
  • 如果此Pull Request解决一个Github问题,请在描述框的最后一行添加指回该问题的链接。
    • 如果此PR解决了Github问题#1234,则在Pull Request描述的最后包括’Fixes#1234’,’Fixed#1234’,’Fix#1234’,’Closes#1234’,’Closed#1234’或’Close#1234’。
    • 如果问题来自New Contributor任务,请在版本号#1234之前添加代码仓名称’Alluxio / new-contributor-tasks’,例如’Fixes Alluxio / new-contributor-tasks#1234。’

完成所有操作后,单击“创建Pull Request”按钮。 恭喜你! 您对Alluxio的第一个Pull Request已提交!

审阅Pull Request

Pull Request提交后,您可以在Alluxio代码仓库的Pull Request页面上找到它。

提交后,社区中的其他开发人员将审核您的Pull Request。 其他人可能会在您的Pull Request中添加评论或问题。

在代码审阅期间,请回复审阅者留下的所有评论,以便审阅者知道已解决了哪些评论以及每个评论是如何解决的。

在此过程中,有些人可能会要求修改部分Pull Request。 为此,您只需要在用于该Pull Request的分支中进行更改,创建一个新的本地提交,推送到您的远程分支,该Pull Request将自动更新。 详细步骤:

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

在Pull Request处理和解决了所有评论和问题后,审阅者将为您的Pull RequestLGTM回复并批准Pull Request。 在至少一个批准后,一个维护人员将把您的Pull Request合并到Alluxio代码库中。

恭喜你! 您已成功为Alluxio做出了贡献! 感谢您加入社区!

Video

提交新特性

如果您有一个非常好的关于新的Alluxio特性想法,我们强烈建议您实施并贡献到Alluxio代码仓库。

  1. Alluxio代码仓库中创建有关您的特性的Github问题。
  2. 在Github问题中遵循这个模板附加特性设计文档。设计文档应遵循模板,并提供有关每个部分的信息。我们建议使用公开的Google文档,以进行更有效的协作和讨论。如果您不希望使用Google文档,则可以选择附加Markdown文件或PDF文件设计文档。
  3. 标记您的问题为’type-feature’。 Alluxio成员定期检查所有未解决的问题,并将分配审阅者们来审阅设计文档。社区用户无权在Alluxio代码仓库中分配问题。因此,如果您想启动审阅过程,则可以创建一个占位Pull Request,链接到该问题,附加特性设计文档,并在那里向Alluxio成员请求审阅。
  4. 审阅者(相应的Github问题的责任人或Pull Request的审阅者)将审阅特性设计文档,并提供反馈或迭代修改请求。如果您不确定特定的设计决策,请随时提出问题并寻求审阅者和社区成员的帮助。还请列出该特性的可能选项以及相应的利弊。
  5. 在对设计文档进行几次迭代修改之后,审阅者将为设计文档提供LGTM。此功能就可以进入实施阶段。
  6. 如上一节所述,创建一个Fork Alluxio代码仓库,实现您的特性并创建一个Pull Request。另请在您的Pull Request中链接到问题和设计文档。在Pull Request中,您还应该将有关特性的文档添加到Alluxio文档中
  7. 在您的Pull Request被审核且合并后,您已向Alluxio提供了新特性。干杯祝贺!

下一步

新的贡献者可以通过以下一些资源来进一步熟悉Alluxio:

  1. 本地运行Alluxio
  2. 在集群上运行Alluxio
  3. 配置设置和命令行界面命令行界面
  4. 代码示例
  5. 从源代码编译Alluxio
  6. 分叉存储库,为一个或两个文件添加单元测试或javadoc,提交Pull Request。也欢迎您在我们的Github问题中解决问题。这里是尚未分配的新贡献者任务的列表。每个New Contributer请限制在2个任务。然后,尝试一些Beginner/Intermediate任务,或在用户邮件论坛中询问。相关教程,请参阅有关分叉代码仓发送Pull Request的GitHub指南

欢迎来到Alluxio社区!