Flink资料（8） -- Flink代码贡献的指导及准则

本文翻译自Contributing Code

-----------------------------------------

Apache Flink是由自愿的代码贡献者维护、优化及扩展的。Apache Flink社区鼓励任何人贡献源代码。为了使得代码贡献者及复查者之便利，以及保存高质量的代码基础，咱们遵循着一个贡献代码的过程，该过程将在本文档中详细描述。

 

本文包括有关向Flink贡献代码所需知晓的全部事宜，描述了从前期准备，测试以及代码提交的过程，同时解释了代码编写的准则以及Flink基础代码的代码风格，此外给出了部署开发环境的教程。

 

重要：请在进行代码贡献以前仔细阅读该文档，遵循下述的过程及准则十分重要。不然，你的 pull request可能不会被接受或须要大量返工。特别地，在开始一个实现新特性的 pull request时，你须要打开一个JIRA ticket，而且与开发社区在有关是否须要该特性达成一致。

1、贡献代码的过程

1.1 前期准备

请肯定你的贡献与一个JIRA的issue相关，这是Flink社区贡献代码时遵循的一个广泛规定，除了修复琐碎bug（trivial hot fixes），该规定覆盖了包括bug修正、优化或新特性等等状况。若是你想要修复找到的bug，或是想要添加新特性，或是想优化Flink，请遵循Flie a bug report和Propose an improvement or a new feature准则，在实现以前，打开一个Flink的JIRA的issue。

 

若是JIRA的issue的描述代表其解决方案会涉及到基础代码的敏感部分、它足够复杂或是会添加大量新代码，Flink社区可能须要一份设计文档（大多数贡献的代码都不须要设计文档）。该文档的目的在于保证issue的总体解决方法是合理且经由社区赞成的。须要文档的JIRA的issue将打上requires-design-doc的标签，该标签能够由任何以为文档是必要的社区成员添加上去。一个好的issue描述能够帮助人们决定该issue是否须要一份设计文档。设计文档必须添加或连接到JIRA的issue中，且须要知足如下几个方面：

1. 整体方法的概述

2. API改变的列表（改变的接口，新的或过时的配置参数，改变的行为等等）

3. 涉及到的主体组件（ main component）和类

4. 该方法已知的缺陷

 

任何人均可以添加设计文档，包括issue的提出者和解决者

 

JIRA issue的代码贡献中，那些须要文档的贡献须要其文档被社区以lazy consensus的方式接受后才能够添加到Flink的基础代码中。请在编写代码以前检查并确认是否须要设计文档。

 

1.2 代码编写准则

请尽量遵循如下规则：

1. 请重视JIRA的issue中记录归档的讨论或需求。

2. 若是须要设计文档，则尽量遵循该文档的设计。若是你的实现和文档设计误差过大，请实时更新文档并与社区达成一致。少许的误差是容许的，不过在提交代码时请指出这些变更之处。

3. 严格遵循coding guidelines and the code style。

4. 不要在一次代码贡献中混淆入其余不相关的issue

 

请随时随意提问，不论发送邮件给dev mailing list仍是在JIRA issue中评论均可。

 

有关部署开发环境，见下面第四部分所述。

 

1.3 验证代码的合规性（compliance）

提交前验证代码的合规性十分重要，主要验证如下几点：

1. 保证代码能够编译

2. 验证经过全部已存在的新的测试

3. 检查代码风格不违规

4. 保证没有不相关或没必要要的格式上的变更

你能够经过如下命令编译代码、运行并测试、检查部分代码风格：

mvn clean verify

 

请注意，有些Flink的基础代码的测试比较奇诡（flaky）并可能意外地失败，Flink社区正在努力提高这些测试的质量，但有的测试没法继续优化，如包括外部依赖的测试等。咱们将全部奇诡的测试维护在JIRA中，并加上了test-stability标签。若是你遇到彷佛与你的改变无关的测试失败的状况，请查看或扩展已知奇诡测试的列表。

 

请注意，为了验证你贡献的代码，咱们针对Java，Scala，Hadoop不一样版本的组合形式运行不一样的编译profile。咱们鼓励每一个贡献者使用continuous integration服务，它将在你每次push一个change时自动测试代码。Best practices一文中有如何将Travis集成到你的Github仓库的教程。

 

除了自动测试以外，请检查你的修改，并移除诸如没必要要的格式修改等无关的修改。

 

1.4准备和提交你的贡献

为了使得merge更加方便，请将这些新的修改rebase到主仓库master分支的最新版本。也请遵循下文代码编写引导（本文2.1），清除你的commit历史，且将你的全部提交 squash到一个合适的集合中。请在rebase以及commit squash后对你的代码进行屡次验证。

 

Flink工程经过GitHub Mirror，以Pull request的形式接受代码贡献。Pull request是一个提供补丁的简单方法，它经过提供一个代码分支的指针的方式来包含修改。

 

经过将咱们的贡献push回到咱们fork的Flink仓库来启用一个pull request

git push origin myBrance

 

进入你的fork仓库网址（https://github.com/<your-user-name>/flink），而且使用"Create Pull Request"按钮来建立一个pull request。确保base fork是 apache/flink master而且head fork包括了你的修改的分支。给你的pull request一个有意义的描述而且发送过来。

 

固然，你也能够经过JIRA issue来添加一个补丁。

 

2、代码编写引导

2.1 Pull request和commit信息

1. 每一个pull request仅负责一个修改。请不要将不一样的无关改变混合到一个pull request中。相反地，请用多个独立pull request对应JIRA issue。这保证pull request是topic相关的，从而能够更加方便地merge，而且一般只会引发与该topic有关的冲突。

2. 不要再pull request中包含WIP（仍在开发中）。咱们认为pull request是要不作会任何改进地merge到当前稳定主分支上去的。所以，一个pull request不该当为“work in progress”的。仅在你确信该pull request能够顺利merge到当前主branch中时才开始一个pull request。而若是你想要对你的代码的意见，请发布你的工做分支的连接。

3. Commit信息。一个pull request必须与一个JIRA issue相关；若是你想解决一个JIRA上没有的问题，请建立一个issue。最新的commit信息应当引用该issue，例如，"[FLINK-633] Fix NullPointerException for empty UDF parameters"。如此，该pull request会自动给它的内容加上描述，如以何种方式修复了什么bug

4. 复核commit。若是你在pull request上获得要求修改的评论，commit这些修改。不要rebase以及squash这些commit。这样才能让他人独立查看cleanup的部分。不然复查者就须要再一次从新复查整个集合。

 

2.2 异常和错误信息

1. Exception swallowing。不要swallow异常并打印堆栈轨迹，而应该查看相似的类是如何处理异常的并加以模仿。

2. 错误信息要有意义。给出的错误信息要有意义，试着猜想异常为什么被抛出而且给出能够帮助到用户解决问题的信息。

 

2.3 测试

1. 须要经过全部测试。任何没法经过测试或没法编译的pull request不会再进一步进行审查。咱们建议将你的GitHub私人帐号与Travis CI链接（像Flink的Github仓库）。请注意以前有关奇诡测试的说明。

2. 须要测试新特性。全部新特性都须要由测试来严格保证。在接下来的merge中抛出或是破坏某特性。若是没有该特性没有测试来保证，这些问题将没法被意识到。全部未被测试覆盖的东西都是浮于表面的。

3. 使用合适的测试机制。请使用单元测试来孤立测试功能，例如方法等。单元测试应当以亚秒级执行而且应当考虑全部状况。类的单元测试的名字应当是"*Test"。使用继承测试来实现long-running测试。

 

2.4 文档

1. 文档更新。许多系统中的改变一样会影响到文档（JavaDocs文档和在目录docs/下的用户文档）。 pull request和补丁须要更新对应的文档，不然提交的改变将不会被源码接受。有关如何更新文档见于贡献文档指导一文。

2. 公共方法的Javadocs。全部公共方法和类须要JavaDoc。请填写有意义的文档，一个好的文档应当是简明扼要而富含信息的。若你改变了签名或是已有文档的方法的行为，请务必同时更新JavaDoc。

 

2.5 代码格式

1. 不要从新排版。请不要对源码文件从新排版，若你或你的IDE自动移除/替换了空白字符，从新排版代码或是自动注释后，代码差异（diff）将不可辨识。一样的，其余影响相同文件的补丁将没法进行merge操做。请配置您的IDE使其不会自动重排版。咱们可能会拒绝带有过多或没必要要的代码重排版的pull request

 

3、代码风格

1. Apache license header。确保你的源码文件中包含Apache License header，RAT插件将会在你编译代码时检查是否含有该header。

2. Tabs 或是 space。咱们使用tab（而不是space）做为缩进符号。这只是因为咱们开始时就使用tab，但不要将它们混用十分重要，不然会引起merge或diff时的冲突。

3. Block。全部if，for，while，do等语句必须包含在大括号封装的代码块中（即便只有一行代码，一样须要大括号包围代码块），以下代码所示，这将有效避免诸如Apple的SSL library的goto bug等问题。

for(…){
…
}

 

4. 不要在import语句中使用通配符。不要再核心文件中的import语句中使用通配符，它们会在adding到代码（adding to the code）甚至有时在重构（refactoring）期间产生一些问题。在导入operator和function时，异常将出如今Tuple类，与Tuple相关的支持类以及Flink user程序。测试则是user程序的特殊用例。

5. 不要留下没用的import语句。请移除全部没用的import语句。

6. 使用Guava检测。为了增长代码的同质性，请一导致用Guava方法checkNotNull和checkArgument来检测，而不是使用Apache Commons Validate

7. Supress warnings：若是它们suppress warning没法避免（如"unchecked"或"serial"等），请添加声明注解（annotation）。

8. 注释。请为代码添加有关逻辑的注释。能够经过添加JavaDoc，或是经过不对方法作任何注释而继承原来的注释等方法添加。不要自动生成注释，避免诸如"i++; // increment by one"这样无用的注释

 

4、练习

1. Travis：Flink已经预先针对Travis CI作了配置，使其能够很方便地在你的私人fork的仓库中启用（它使用GitHub来进行身份认证，因此你不须要另外一个帐号来进行验证）。能够简单地添加Travis CI的hook到你的仓库（settings -> webhooks & services -> add service），并启用Travis上对flink仓库的测试。

 

5、部署开发环境

5.1 开发和编译FLink的环境需求：

1. 类Unix环境（咱们使用Linux，Mac OS X, Cygwin）

2. git

3. Maven（至少为版本3.0.4）

4. Java 7或8

 

5.2 Clone仓库

Apache Flink的源代码存储在git仓库中，并镜像存储在Github。Github上交换代码通常讲仓库fork到你的私人Github帐户仓库。为此，你须要一个Github帐户或免费建立一个。Fork一个仓库意味着Github为你建立了一个仓库的副本，该操做能够经过点击仓库站点页面中右上角的fork按钮完成。一旦你将Flink仓库fork到你的私人帐户，你就能够将该仓库clone到你的本地设备上。经过如下命令，源码将会下载到名为flink的目录下。

git clone https://github.com/<your-user-name>/flink.git

 

5.3 代理设置

若是你处于防火墙保护之下，你可能须要为Maven和你的IDE提供代理设置。例如WikipediaEditsSourceTest经过IRC通讯，而且须要一个SOCKS proxy server来绕过。

 

5.4 部署IDE并导入源代码

Flink的提交者们使用IntelliJ IDEA和Eclipse IDE来开发Flink基础代码。

 

5.4.1 IDE的最低要求：

·     支持JAVA和Scala语言，同时支持两者的混合项目。

·     支持Java和Scala的Maven。

 

5.4.2 IntelliJ IDEA

IntelliJ IDE自带支持Maven，而且提供了Scala开发的插件

IntelliJ下载地址：https://www.jetbrains.com/idea/

IntelliJ Scala Plugin：http://plugins.jetbrains.com/plugin/?id=1347

有关IntelliJ的设置，请看Setting up IntelliJ一文指导

 

5.4.3 Eclipse Scala IDE

对于Eclipse用户，咱们建议基于Eclipse Kepler，使用Scala IDE 3.0.3。尽管该版本有些旧，但咱们发现这是Flink等复杂项目运行最为鲁棒的版本。

 

进一步细节以及更新的Scala IDE版本的指导在How to setup Eclipse文档中。

 

注意：在开始下列部署以前，确保经过使用该一次如下命令来运行编译程序（mvn clean install -DskipTests，详情见上文）

1. 下载Scala IDE（推荐）或是安装Eclipse Kepler的插件。下载连接和指令见于How to setup Eclipse

2. 向Scala编译器添加添加"macroparadise"编译器插件。打开"Winodw" -> "Preferences" -> "Scala" -> "Complier" -> "Advanced"，并添加"Xplugin"域和macroparadise的jar文件的路径（一般是"/home/-your-user-/.m2/repository/org/scalamacros/paradise_2.10.4/2.0.1/pardise_2.10.4-2.0.1.jar"）。注意：若是你没有jar文件，多是因为你没有运行命令行来编译生成。

3. 导入Flink Maven工程（"File" -> "Import" -> "Maven" -> "Existing Maven Projects"）

4. 在导入期间，Eclipse将会自动询问是否自动安装额外Maven build helper插件。

5. 关闭"flink-java8"工程，因为Eclipse Kepler不支持Java 8，你没法开发此工程

 

5.4.4 导入源码

Apache Flink使用Apache Maven做为编译工具，大多数IDE均可以导入Maven工程。

 

5.5 编译源码

为了从源码编译Flink，咱们能够打开一个终端，导航到Flink源码的根目录，并调用命令"mvn clean package"。该命令将编译Flink并运行全部测试，Flink最终将安装在目录build-target。

 

为了编译Flink时不运行测试，你能够调用命令"mvn -DskipTests clean package"

 

6、提交者如何使用Git

只有ASF的infrastructure team具备Github镜像的管理员访问权限，所以，提交者须要将修改push到ASF的git仓库。

 

Main source仓库

ASF writable：https://git-wip-us.apache.org/repos/asf/flink.git

ASF read-only：git://git.apache.org/repos/asf/flink.git

ASF read-only：https://github.com/apache/flink.git

 

注意：Flink不使用Oracle JDK 6编译，但它可使用Oracle JDK 6运行。

若是你想要为Hadoop1编译，经过命令"mvn clean package -DskipTests -Dhadoop.profile=1"来激活编译profile。

 

7、快照版本（每夜构建Nightly builds）

Apache Flink 1.1-SNAPSHOT是咱们最新的开发版本。

 

你能够下载咱们打包的每夜构建版本，它包括最新的开发代码，由此可使用还未发布的新特性。仅有经过全部测试的编译版本才会发布在此处。

· Hadoop 1: flink-1.1-SNAPSHOT-bin-hadoop1.tgz

· Hadoop 2 和YARN :flink-1.1-SNAPSHOT-bin-hadoop2.tgz

 

添加Apache Snapshot repository到你的Maven的pom.xml：

1 <repositories>
2 　　<repository>
3 　　　　<id>apache.snapshots</id>
4 　　　　<name>Apache Development Snapshot Repository</name>
5 　　　　<url>https://repository.apache.org/content/repositories/snapshots/</url>
6 　　<releases><enabled>false</enabled></releases>
7 　　<snapshots><enabled>true</enabled></snapshots>
8 　　</repository>
9 </repositories>

 

至此，你就能够将版本1.1-SNAPSHOT（或版本1.1-SNAPSHOT-hadoop1来兼容旧的1.x版本hadoop）的Apache Flink包括到一个Maven依赖中了。