猫でもわかるWebプログラミングと副業

本業エンジニアリングマネージャー。副業Webエンジニア。Web開発のヒントや、副業、日常生活のことを書きます。

Play Framework の Contributor guidelines を読む

f:id:yoshiki_utakata:20181004212834j:plain

はじめに

https://github.com/playframework/playframework にプルリクエストを出そうとすると、「How to write the perfect pull request」と「Contributor guidelines」に目を通すように言われます。前者については OSSでプルリクを出すために、GitHubが出している「どうやって完璧なプルリクエストを書くか」を読む - WebエンジニアのLoL日記 で読みましたので、今回は playframeworkのContributor guidelinesについて読んでいきます。

Play contributor guidelines

issue立てるとき

  • ドキュメントの簡単な修正の場合はissueを立てずにすぐにプルリクエストを出してください。これが一番早いと思います。
  • バグかどうか100%の確信がない場合、Play Framework forum でたずねてください。新機能の議論についてはメーリングリストがよいです。issueはバグのためのもので質問のためのものではありません。
  • バグであると確信して初めてissueを立ててください。可能な限り詳細に書いてください。実際に問題が起こるサンプルコードと結果、スタックトレースなどを含めてください。Play, Java, OSの種類やバージョンなどの情報も含めてください。

コントリビュートする

はじめに

  • Lightbend CLA に登録してください(詳細は別ブログで書きます)。オンラインで登録できます。
  • あなたの変更が以下のガイドラインに適しているかを確認してください。
    • コーディング規約
    • 新機能かどうかや、バグ修正かどうかにかかわらず、全体テストを通してください。テストが無いコードを修正した場合もです。
    • 以下の実装は可能な限り避けてください
      • グローバルな状態管理・変数
      • publicかつmutableな状態管理や変数
      • implicit conversions(暗黙の型変換) *3
      • ThreadLocal
      • Locks
      • Casting
      • 新しく強い依存性を導入すること
    • Play API の設計ルール
    • PlayはJavaScalaフレームワークです。ScalaJavaの両方で同じ変更をするようにしてください
    • JavaAPIframework/play/src/main/java 以下にあり、パッケージ名は play.myapipackage.xxxx
    • ScalaAPIframework/play/src/main/scala 以下にあり、パッケージ名は play.api.myapipackage
    • 新機能がフレームワークのコア機能であるべきか、1モジュールとして実装されているべきか考えてください
    • コードがコーディング規約にのっとっていて、テストが通る必要があります
    • 新しいファイル
      • コピーライトを以下のように書く必要があります。 Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
      • @author タグは使わないでください
  • コミットはSquashしてください。詳細は https://www.playframework.com/documentation/ja/2.4.x/WorkingWithGit を読んでください。
  • プルリクエストを出してください

これらのガイドラインに沿ってない場合は、そのプルリクエストがどれだけ重要であったり、どれだけ良いプルリクエストだったとしても、レビューやマージはされません。

プルリクエストは https://www.playframework.com/community-process#Implementation-decisions の内容にそってレビューされます。

Backportingについて *4

基本的にすべてのプルリクエストはmasterブランチにマージされます。バックポートが許可されるのは以下の場合です。

  • ドキュメントだけに影響する変更
  • バックポートによって過去のバージョンにバグが出た場合の修正
  • フレームワークにとって重要なバグフィックスだった場合
  • そのた適切だと判断された場合

すべてのバックポートのためのコミットはガイドラインを満たす必要があります。ただし、脆弱性のような深刻な問題に対する変更の場合でかつAPIの互換性を保てない場合のみが例外になります。

*1:公式のドキュメントではリンク切れしているけど「Don't Repeat Yourself でぐぐれば出てくる

*2:簡単に言うとコードを散らかすなということ

*3:implicit conversions 参考: https://dwango.github.io/scala_text/implicit.html

*4:Backportingとは: セキュリティの問題などのため最新版以外のバージョンにもその変更を取り込むこと https://www.weblio.jp/content/%E3%83%90%E3%83%83%E3%82%AF%E3%83%9D%E3%83%BC%E3%83%88