开发指南
欢迎来到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 Contributor、Beginner、Intermediate、 Advanced。 新的开发者应该在进行更高级的任务之前先完成两个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个字符),也不能太短(描述清楚)
- 标题应以祈使动词开头
- 例子:修复Alluxio UI问题,重构Inode缓存逻辑
- 错误例子:
修复了Alluxio UI错误,~~ Inode缓存重构~~ - 标题允许的开始单词列表
- 标题的第一个单词应大写(英文)
- 标题不应以句号结尾
这些规则有一些例外。 标题开头前可以加前缀。 前缀全大写,并与标题的其余部分用一个空格隔开。 下面是一些可用前缀。
- [DOCFIX]: 这是为更新文档的PRs
- 例子:‘[DOCFIX]更新入门指南’,‘[DOCFIX]添加GCS文档‘
- [SMALLFIX]:用于很小不会更改任何逻辑的PRs修改,例如拼写错误
- 示例:‘[SMALLFIX]修复AlluxioProcess中的错字’
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代码仓库。
- 在Alluxio代码仓库中创建有关您的特性的Github问题。
- 在Github问题中遵循这个模板附加特性设计文档。设计文档应遵循模板,并提供有关每个部分的信息。我们建议使用公开的Google文档,以进行更有效的协作和讨论。如果您不希望使用Google文档,则可以选择附加Markdown文件或PDF文件设计文档。
- 标记您的问题为’type-feature’。 Alluxio成员定期检查所有未解决的问题,并将分配审阅者们来审阅设计文档。社区用户无权在Alluxio代码仓库中分配问题。因此,如果您想启动审阅过程,则可以创建一个占位Pull Request,链接到该问题,附加特性设计文档,并在那里向Alluxio成员请求审阅。
- 审阅者(相应的Github问题的责任人或Pull Request的审阅者)将审阅特性设计文档,并提供反馈或迭代修改请求。如果您不确定特定的设计决策,请随时提出问题并寻求审阅者和社区成员的帮助。还请列出该特性的可能选项以及相应的利弊。
- 在对设计文档进行几次迭代修改之后,审阅者将为设计文档提供LGTM。此功能就可以进入实施阶段。
- 如上一节所述,创建一个Fork Alluxio代码仓库,实现您的特性并创建一个Pull Request。另请在您的Pull Request中链接到问题和设计文档。在Pull Request中,您还应该将有关特性的文档添加到Alluxio文档中。
- 在您的Pull Request被审核且合并后,您已向Alluxio提供了新特性。干杯祝贺!
下一步
新的贡献者可以通过以下一些资源来进一步熟悉Alluxio:
- 本地运行Alluxio
- 在集群上运行Alluxio
- 读配置设置和命令行界面 和 命令行界面
- 读代码示例
- 从源代码编译Alluxio
- 分叉存储库,为一个或两个文件添加单元测试或javadoc,提交Pull Request。也欢迎您在我们的Github问题中解决问题。这里是尚未分配的新贡献者任务的列表。每个New Contributer请限制在2个任务。然后,尝试一些Beginner/Intermediate任务,或在用户邮件论坛中询问。相关教程,请参阅有关分叉代码仓和发送Pull Request的GitHub指南。