Flink资料（8） -- Flink代码贡献的指导及准则
本文翻译自Contributing Code
-----------------------------------------
Apache Flink是由自愿的代码贡献者维护、优化及扩展的。Apache Flink社区鼓励任何人贡献源代码。为了使得代码贡献者及复查者之便利，以及保存高质量的代码基础，我们遵循着一个贡献代码的过程，该过程将在本文档中详细描述。
本文包括有关向Flink贡献代码所需知晓的所有事宜，描述了从前期准备，测试以及代码提交的过程，同时解释了代码编写的准则以及Flink基础代码的代码风格，此外给出了部署开发环境的教程。
重要：请在进行代码贡献之前仔细阅读该文档，遵循下述的过程及准则十分重要。否则，你的 pull request可能不会被接受或需要大量返工。特别地，在开始一个实现新特性的 pull request时，你需要打开一个JIRA ticket，并且与开发社区在有关是否需要该特性达成一致。
一、贡献代码的过程
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.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
三、代码风格
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"这样无用的注释
四、练习
1. Travis：Flink已经预先针对Travis CI做了配置，使其可以很方便地在你的私人fork的仓库中启用（它使用GitHub来进行身份认证，所以你不需要另一个账号来进行验证）。可以简单地添加Travis CI的hook到你的仓库（settings -> webhooks & services -> add service），并启用Travis上对flink仓库的测试。
五、部署开发环境
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"
六、提交者如何使用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。
七、快照版本（每夜构建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依赖中了。
