§開発者 & コントリビュータ向けガイドライン

§一般的なワークフロー

これは master にコミットする手順です。もちろん、例えばコメントやドキュメントのちょっとした変更や、壊れたビルドの修正、その他など、これらのルールに対する例外もあります。

1. Typesafe CLA にサインしていることを確認して、まだサインしていない場合は、オンラインでサインしてください。
2. 機能や修正について作業を始める前に、以下について確認しなければなりません:
   1. プロジェクトの issue トラッカーにその作業用のチケットがあること。もしチケットが無い場合は、まずチケットを作成してください。
   2. そのチケットが現在のマイルストーン内に計画されていること。
   3. そのチケットがチームによって検討されていること。
   4. そのチケットがチームによって議論され、優先順位づけされていること。
3. 常に Git の機能ブランチで作業を行うべきです。ブランチは、その意図を説明する、分かり易い名前を与えられるべきです。
4. 機能や修正が完了したら、GitHub 上で プルリクエスト を実行してください。
5. プルリクエストは、(実現性があり/現実的な限り多くの) 他のメンテナーによってレビューされるべきです。メンテナーは、Play チーム内外いずれも含めて、外部のコントリビュータによって構成され得ることに留意してください。レビュープロセスは閉じたものではなく、外部のコントリビュータはレビューに参加することが奨励されています。
6. レビュー後、必要に応じて (新しいレビューその他について新しいコミットを push しながら) 課題を修正し、レビュア―が「いいね！」と言うまでくり返します。
7. レビューを通過したら、そのプルリクエストは master ブランチにマージされます。

§開発者グループと議論

機能、提案、そしてプルリクエストの議論には、専用の https://groups.google.com/forum/#!forum/play-framework-dev グループを使います。

§プルリクエスト要件

プルリクエストがきちんと検討されるためには、これらの要件を満たす必要があります:

1. 現在のコーディング標準に沿っていること:

• DRY に違反しない
• Boy Scout Rule を適用する

1. そのコードが新機能を導入するものか、あるいはバグやリグレッションを修正するものかに関わらず、包括的なテストが必要です
2. コードは Play 標準のドキュメントフォーマット (下記の ‘ドキュメント’ の段落を参照してください) に従って充分に説明されていなければいけません。あらゆる API の変更には関連するドキュメントの変更も必要です。
3. 実装面では、以下に示すことを可能な限り避けるべきです:
   • 大域的な状態
   • 外部から変更可能な状態
   • 暗黙的変換
   • ThreadLocal
   • ロック
   • 型キャスト
   • 巨大なモジュール依存性の新規追加
4. Play の API 設計ルールは以下の通りです:

• Play は Java、Scala 向けのフレームワークです。変更された API が Java、Scala どちらでも動作するようにしましょう
• Java API は framework/play/src/main/java ディレクトリに配置し、パッケージ構成は play.myapipackage.xxxx にしましょう
• Scala API は framework/play/src/main/scala ディレクトリに配置し、パッケージ構成は play.api.myapipackage にしましょう
• Java および Scala API は次のように実装しましょう:
  • コア API を Scala で実装します（play.api.xxx）
  • API の内部コンポーネントがライフサイクル管理が必要であったり、置き換え可能である必要がある場合は、プラグインとして作成しましょう。該当しない場合は、このステップは飛ばしてください
  • コア API を Scala ユーザ向けにラップします (サンプル)
  • Scala API を　Java ユーザ向けにラップします (サンプル)
• 機能追加には限りがありません。その新機能はフレームワークのコアに必要か、プラグインとして実装すべきか、ということを常に考えましょう

これらの要件が満たされない場合は、そのコードがどれだけ優れていても、またはどれだけ重要であっても、master にマージされることが あり得ない どころか、レビューすらされません。例外はありません。

§ドキュメント

markdown 形式のドキュメントが documentation/manual ディレクトリにあります。Play のブランチごとに、各バージョンのドキュメントがあります。

§進行中の作業

GitHub リポジトリの公開されたフィーチャーブランチで作業することは問題ありません。早い段階でのフィードバックその他、いろいろなことに便利なときがあるでしょう。この場合、ブランチに 進行中の作業 (Work In Progress) であることを示す wip- という接頭辞を付けるか、wip/.., feature/.. あるいは topic/.. のような階層的な名前を付けることがより望ましくなります。いずれの方法でも、それが進行中の作業であり、マージする準備が整っていないことを明確にしている限り問題ありません。この作業は一時的に基準を下げて行うこともできますが、master にマージされるには、上記に要点を説明したプルリクエストやレビュー、その他の標準的なプロセスに従う必要があります。

実際の作業ときれいに整形されたコミットメッセージの組み合わせを促進するために、wip や feature/topic の識別子にもまた、特別な意味を持たせます。wip というラベルの付いたブランチは、いずれも “git-unstable”と見なされ、リベースして履歴を変更される場合があります。feature/topic という名前の付いたブランチは、ある機能についてグループで作業している場合、依存するのに十分なほど ”stable”であると見なされます。

§コミットとコミットメッセージ

公開されたコミットを行い、コミットメッセージを書く場合は、以下のガイドラインに従ってください。

1. 複数のローカルコミットにまたがって作業している (例えば、フィーチャーブランチでの作業中に安全な区切りとして何度かコミットしたり、またはあるブランチにおいて何度かマージ/リベースを行いながら長い間作業している) 場合は、これらを全てコミットするのではなく、ひとつの大きなコミットに squash して履歴を書き換えた上で、このコミットにふさわしい (以下の段落で説明されているような) コミットメッセージを書いてコミットしてください。より詳しくは、この記事: Git Workflow を読んでください。すべてのコミットは独立して cherry-pick やその他に利用できるべきです。
2. 最初の行は、そのコミットが何をしているかわかりやすい文章であるべきです。この一行を読むだけで、そのコミットが何をするのかを完全に理解できなければなりません。チケット番号のリストや、“小規模な修正” 、またはこれに似たメッセージをタイプするだけでは 十分ではありません 。
   最初の行の末尾に、＃ で始まるチケット番号への参照を含めてください。そのコミットが小規模な修正であれば、これで完了です。そうでない場合は、3 に進みます。
3. 一行目の説明の後は、その後にコミットの詳細一覧が列挙される空行であるべきです。
4. コミットに関するキーワードを追加します (自動化されている度合に応じて、このリストは都度変更される場合があります):
   • Review by @gituser - チームの誰かに通知したい場合。指名したひと以外もレビューできますし、参加することが推奨されます。
   • Fix/Fixing/Fixes/Close/Closing/Refs #ticket - issue トラッカー内のチケットを修正済みにしたい場合 (Assembla がこれを理解する場合) 。
   • backport to _branch name_ - この修正が (2.9.x, 2.10.x, その他のような) 別のブランチに cherry-pick される必要がある場合。

例:

機能に API をひとつ追加。Fixes #2731

  * 詳細 1
  * 詳細 2
  * 詳細 3

このドキュメントの翻訳は Play チームによってメンテナンスされているものではありません。 間違いを見つけた場合、このページのソースコードを ここ で確認することができます。 ドキュメントガイドライン を読んで、お気軽にプルリクエストを送ってください。