どのような種類のソフトウェアにとっても良いドキュメントは重要です。Apache Flinkのような分散データ処理エンジンのような洗練されたソフトウェアシステムにとって特にそれが当てはまります。Apache Flinkのコミュニティは完結、正確、そして完全なドキュメントを提供しようと狙っており、Apache Flinkのドキュメントを改善するどのような貢献も歓迎します。
Apache Flinkのドキュメントはコードベースと同じgit リポジトリで維持されます。これはコードとドキュメントが簡単に同期できるようにするためです。
ドキュメントに貢献する一番簡単な方法は、右上のforkボタンをクリックすることで、Github上のFlinkのミラーされたリポジトリを自身のGithubアカウントにフォークすることです。Githubアカウントを持っていない場合は、無料で作成することができます。
次に、フォークをローカルマシーンにクローンします。
git clone https://github.com/<your-user-name>/flink.git
ドキュメントはFlinkのコードベースのdocs/ サブディレクトリ内に配置されます。
… 貢献に対応するJIRA issue が存在するように必ずしてください。タイポのような些細な修正を除いて、全てのドキュメントの変更がJIRA issueを参照することを要求します。
FlinkのドキュメントはMarkdownで書かれています。Markdown はHTMLに翻訳することができる軽量マークアップ言語です。
ドキュメントを更新あるいは拡張するためには、Markdown (.md) ファイルを修正する必要があります。プレビューモードでビルドスクリプトを開始することで、変更を検証してください。
cd docs
./build_docs.sh -p
スクリプトはMarkdownファイルを静的なHMTLページにコンパイルし、ローカルwebサーバを開始します。変更を含むコンパイルされたドキュメントを見るために、ブラウザで http://localhost:4000を開きます。Markdownファイルを修正し保存してブラウザを更新すると、提供されるドキュメントは自動的に再コンパイルされ更新されます。
どのような質問でも気軽に開発者メーリングリストに聞いてください。
Flink プロジェクトはGitHub Mirror を通じて Pull Requestsとしてのドキュメントの貢献を受け付けます。プルリクエストは、変更を含むコードブランチへのポインタを提供することで、パッチを提供する一番簡単な方法です。
プルリクエストを準備しサブミットするには、以下のステップに従います。
変更をローカルのgitリポジトリにコミットします。コミットメッセージは[FLINK-XXXX]から開始することで、対応するJIRA issueを示さなければなりません。
コミットされた貢献をGithubのあなたのフォークのFlinkのリポジトリにプッシュします。
git push origin myBranch
リポジトリのフォークのwebサイト (https://github.com/<your-user-name>/flink) に行き、プルリクエストの作成を開始するために "Create Pull Request" ボタンを使います。基本のフォークは >apache/flink master で、headフォークがあなたの変更のブランチを選択するようにしてください。プルリクエストに意味のある説明を付け、それをサブミットします。
JIRA issue にパッチを添付することも可能です。