Apache Flink はボランティアのコードの貢献によって、維持、改善および拡張されます。Apache Flink コミュニティは皆のソースコードの貢献を推奨します。貢献者とレビュワーに好ましい体験を保証するためにと、コードベースの高品質を保つために、このドキュメントで説明される貢献プロセスに従います。
このドキュメントはApache Flinkへの貢献についてあなたが知らなければならないすべてのことを含んでいます。それは、貢献を準備、テストおよびサブミットする方法を説明し、コーディングガイドラインとFlinkのコードベースのコードスタイルを説明し、そして開発環境をセットアップするための手順を与えます。
重要: コードへの貢献の取り組みを始める前に注意深くこのドキュメントを読んでください。以下で説明される方法とガイドラインに従うことが重要です。そうでなければ、あなたのプルリクエストは受け付けられず、大量のやり直しが必要になるかもしれません。特に、新しい機能を実装するプルリクエストをオープンする前に、jiraチケットをオープンして、コミュニティにこの機能が必要とされるかどうかについて同意を取る必要があります。
… あなたの貢献に対応するJIRA issueがあるようにしてください。これは、些細なホットフィクスを例外として、バグフィックス、改良、あるいは新しい機能を含む全てのコードの貢献のためにFlinkコミュニティが従う 一般的なルール です。発見したバグの修正をしたい場合や、Flinkに新しい機能や改善を追加したい場合は、実装を開始する前にFlinkのJIRA内にissueを開くためにバグレポートを提出する あるいは 改善や新しい機能を提案する ガイドラインに従ってください。
Jira issueの説明がその解決方法がコードベースの繊細な部分に触れる、十分に複雑である、あるいは著しい量の新しいコードを追加することを示す場合、Flinkコミュニティは設計ドキュメントを要求するかも知れません (ほとんどの貢献は設計ドキュメントを必要としないでしょう)。このドキュメントの目的は、問題を解決するための全体の方法が目的に適ったものでコミュニティによって同意されることを確実にすることです。設計ドキュメントを必要とする JIRA issues は requires-design-doc ラベルが付けられます。設計ドキュメントが必要だと思ったコミュニティメンバーが、そのラベルを付けることができます。良い説明はJira issueが設計ドキュメントを必要とするかどうかを決めるのに役立ちます。設計ドキュメントはJira issueに追加、添付、あるいはリンクされている必要があり、以下の受け入れ条件を満たしていなければなりません:
設計ドキュメントは、issueの報告者あるいはそれに取り掛かっている人を含む誰でも追加することができます。
設計ドキュメントを必要とするJira issueに関する貢献は、設計ドキュメントがコミュニティによって緩い同意を持って受け付けられる前にFlinkのコードベースへ追加されないでしょう。コードを書き始める前に設計ドキュメントが必要とされていないか調べてください。
… 以下のルールを尊重してください:
いつでも気軽に質問してください。 dev メーリングリストにメールを送信、あるいはJiraのissueにコメントしてください。
以下の説明は開発環境をセットアップするのに役立つでしょう。
貢献をサブミットする前に変更の同意を確かめることはとても重要です。以下のものが含まれます:
以下を呼び出すことで、コードをビルドし、テストを実行し、そしてコードスタイル(の一部)を調べることができます。
mvn clean verify
Flinkのコードベース内のいくつかのテストはひどく変わっていて、失敗するかも知れないことに注意してください。. Flink コミュニティはこれらのテストの改善に一生懸命に取り組んでいますが、時にはこれはできないことがあります。たとえば、テストが外部の依存を含む場合。ひどく変わっていると知られている全てのテストをJiraで保持し、test-stability ラベルを付けます。変更に関係しないと思われるテストの失敗に遭遇した場合は、このひどく変わっているテストのリストをチェック(および拡張)してください。
あなたの貢献を検証するために、私たちは異なる Java, Scala, および Hadoop バージョンについて追加のビルドプロファイルを実行することに注意してください。変更をプッシュする度にリポジトリ内のコードを自動的にテストする継続的インテグレーションサービスを使うことをあらゆる貢献者にお勧めします。ベスト プラクティス ガイドは、Githubリポジトリを使ってTravisを統合する方法を説明します。
自動化テストに加えて、変更のdiffをチェックして、不必要な再整形などのような関係しない全ての変更を削除してください。
変更を簡単にマージできるように、それらをメインリポジトリのマスターブランチの最新バージョンにrebaseしてください。コミット メッセージのガイドラインを尊重し、コミット履歴の掃除、およびあなたのコミットを適切なセットに押し込めるようにもしてください。rebaseした後でもう一度あなたの貢献を検証し、上で説明したようにコミットを押し込めるようにしてください。
FlinkプロジェクトはGitHub ミラーを使ってプルリクエストの形でコードの貢献を受け付けます。プルリクエストは、変更を含むコードブランチへのポインタを提供することで、パッチを提供する一番簡単な方法です。
プルリクエストを開くには、貢献をあなたのFlinkリポジトリのフォークへ先送りしてください。
git push origin myBranch
リポジトリのフォークのwebサイト (https://github.com/<your-user-name>/flink) に行き、プルリクエストの作成を開始するために "Create Pull Request" ボタンを使います。基本のフォークは apache/flink master で、headフォークがあなたの変更のブランチを選択するようにしてください。プルリクエストに意味のある説明を付け、それを送信します。
JIRA issue にパッチを添付することも可能です。
PRごとに一つの変更。1つのプルリクエストの中に様々な関係しない変更を組み合わせないでください。むしろ、各PRがJIRA issue を参照する複数の個々のプルリクエストを開きます。これにより、プルリクエストが トピックに関連し、もっと簡単にマージすることができ、そして一般的にトピック固有のマージの衝突だけになるようになります。
WIP プルリクエストをしない。We consider pull requests as requests to merge the referenced code as is into the current stable master branch. 従って、プルリクエストは"進行中"であってはなりません。問題なく現在のマスターブランチへマージすることができると確信できた場合は、プルリクエストを開いてください。コードにコメントを追加したい場合は、作業中のブランチへリンクを投稿してください。
コミット メッセージ. プルリクエストはJIRA issueへ関連づける必要があります; 変更したいものに対しての変更が無い場合はissueを作成してください。最新のコミットメッセージはそのissueを参照しなければなりません。例のコミットメッセージとして [FLINK-633] Fix NullPointerException for empty UDF parameters があります。そのようにして、プルリクエストは自動的にそれが何であるかの説明を与えます。例えばどのようなバグをどうやって修正したか。
レビューコメントの追加。変更を求めてるプルリクエストへのコメントがあった場合は、それらの変更に対してコメントを追加します。それらをrebaseおよび一つにまとめてはいけません。それにより人々が独立して片付け作業をレビューすることができます。そうでなければ、レビュワーは再びdiffのセット全体を見なければならなくなります。
例外の飲み込み。例外を飲み込みしないで、スタックトレースを出力してください。そうではなく、似たクラスでどうやって例外を処理しているかを調べてください。
意味のあるエラーメッセージ。意味のある例外メッセージを与えてください。Try to imagine why an exception could be thrown (what a user did wrong) and give a message that will help a user to resolve the problem.
Tests need to pass. Any pull request where the tests do not pass or which does not compile will not undergo any further review. We recommend to connect your private GitHub accounts with Travis CI (like the Flink GitHub repository). Travis will run tests for all tested environments whenever you push something into your Github repository. Please note the previous comment about flaky tests.
Tests for new features are required. All new features need to be backed by tests, strictly. It is very easy that a later merge accidentally throws out a feature or breaks it. This will not be caught if the feature is not guarded by tests. Anything not covered by a test is considered cosmetic.
Use appropriate test mechanisms. Please use unit tests to test isolated functionality, such as methods. Unit tests should execute in subseconds and should be preferred whenever possible. The name of unit test classes have to on *Test. Use integration tests to implement long-running tests. Flink offers test utilities for end-to-end tests that start a Flink instance and run a job. These tests are pretty heavy and can significantly increase build time. Hence, they should be added with care. The name of unit test classes have to on *ITCase.
Documentation Updates. Many changes in the system will also affect the documentation (both JavaDocs and the user documentation in the docs/ directory.). Pull requests and patches are required to update the documentation accordingly, otherwise the change can not be accepted to the source code. See the Contribute documentation guide for how to update the documentation.
Javadocs for public methods. All public methods and classes need to have JavaDocs. Please write meaningful docs. Good docs are concise and informative. Please do also update JavaDocs if you change the signature or behavior of a documented method.
Blocks. All statements after if, for, while, do, … must always be encapsulated in a block with curly braces (even if the block contains one statement):
for (...) {
...
}If you are wondering why, recall the famous goto bug in Apple’s SSL library.
Comments. Add comments to your code. What is it doing? Add JavaDocs or inherit them by not adding any comments to the methods. Do not automatically generate comments and avoid unnecessary comments like:
i++; // increment by oneflink repository on Travis.Apache Flink’s source code is stored in a git repository which is mirrored to Github. The common way to exchange code on Github is to fork a the repository into your personal Github account. For that, you need to have a Github account or create one for free. Forking a repository means that Github creates a copy of the forked repository for you. This is done by clicking on the fork button on the upper right of the repository website. Once you have a fork of Flink’s repository in your personal account, you can clone that repository to your local machine.
git clone https://github.com/<your-user-name>/flink.git
The code is downloaded into a directory called flink.
If you are behind a firewall you may need to provide Proxy settings to Maven and your IDE.
For example, the WikipediaEditsSourceTest communicates over IRC and need a SOCKS proxy server to pass.
The Flink committers use IntelliJ IDEA and Eclipse IDE to develop the Flink code base.
Minimal requirements for an IDE are:
The IntelliJ IDE supports Maven out of the box and offers a plugin for Scala development.
Check out our Setting up IntelliJ guide for details.
For Eclipse users, we recommend using Scala IDE 3.0.3, based on Eclipse Kepler. While this is a slightly older version, we found it to be the version that works most robustly for a complex project like Flink.
Further details, and a guide to newer Scala IDE versions can be found in the How to setup Eclipse docs.
Note: Before following this setup, make sure to run the build from the command line once
(mvn clean install -DskipTests, see above)
Apache Flink uses Apache Maven as build tool. Most IDE are capable of importing Maven projects.
To build Flink from source code, open a terminal, navigate to the root directory of the Flink source code, and call
mvn clean package
This will build Flink and run all tests. Flink is now installed in build-target.
To build Flink without executing the tests you can call
mvn -DskipTests clean package
Only the infrastructure team of the ASF has administrative access to the GitHub mirror. Therefore, comitters have to push changes to the git repository at the ASF.
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
注意: FlnkはOracle JDK 6 を使ってビルドしません。Oracle JDK 6 で動作します。
If you want to build for Hadoop 1, activate the build profile via mvn clean package -DskipTests -Dhadoop.profile=1.
Apache Flink 1.1-SNAPSHOT is our latest development version.
You can download a packaged version of our nightly builds, which include the most recent development code. You can use them if you need a feature before its release. Only builds that pass all tests are published here.
Add the Apache Snapshot repository to your Maven pom.xml:
<repositories>
<repository>
<id>apache.snapshots</id>
<name>Apache Development Snapshot Repository</name>
<url>https://repository.apache.org/content/repositories/snapshots/</url>
<releases><enabled>false</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>You can now include Apache Flink as a Maven dependency (see above) with version 1.1-SNAPSHOT (or 1.1-SNAPSHOT-hadoop1 for compatibility with old Hadoop 1.x versions).