Documentation

You are viewing the documentation for the 2.3.x release series. The latest stable release series is 2.4.x.

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

§一般的なワークフロー

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

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

§開発者グループと議論

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

§プルリクエスト要件

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

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

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

§ドキュメント

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

§進行中の作業

It is ok to work on a public feature branch in the GitHub repository. Something that can sometimes be useful for early feedback etc. If so then it is preferable to name the branch accordingly. This can be done by either prefix the name with wip- as in ‘Work In Progress’, or use hierarchical names like wip/.., feature/.. or topic/... Either way is fine as long as it is clear that it is work in progress and not ready for merge. This work can temporarily have a lower standard. However, to be merged into master it will have to go through the regular process outlined above, with Pull Request, review etc..

実際の作業ときれいに整形されたコミットメッセージの組み合わせを促進するために、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

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