-
Notifications
You must be signed in to change notification settings - Fork 1
Submitting patches
(origin: erlang/otp/wiki/Submitting-patches/96aeadd, Translated at 2013-07-25 19:20 +09:00 JST)
パッチの送り方 (Submitting patches).
メーリングリスト を購読しておいてください.
パッチを送付する推奨される方法はこのページに記載されています. 基本的に, あなたの変更を git レポジトリに push してその公開 git レポジトリ及びブランチへのリファレンスをメールに記して送る形になります.
以下の手順に従っていれば, 1営業日以内に応答が返るでしょう.
この手順を辿ることで, Erlang/OTP チームはより生産的になり, 最終的にはすべての Erlang/OTP 利用者の利益となるでしょう.
若しここに記載さいれている手順と異なる方法でパッチを提出してきたのであれば, それは暗に Erlang/OTP チームにより多くの作業を負担させることを意味します. この場合私達は何も保証できません. そのパッチを手に取るかどうかは OTP のその部分のメンテナ次第でしょう.
そのパッチがErlang/OTP チームにとって重大なバグを修正する場合であればそれがどのように提出されたのかにかかわらず注意を払うでしょう. これにはシステムの起動に関するバグ, データの破損, VM をクラッシュされるバグが含まれます. 私達はパッチを検証することなしに適用することはありません, またオリジナルのパッチより適切な修正方法があればそちらで実装することもあります.
pull request は現在毎日のように処理されており, あなたの変更は OTP チームによって処理そしてレビューされる前に基本的なテストを経由するでしょう.
パッチを私達に送る前に, それがバグ修正なのか新機能なのかよく考えてみてください. もしそれが新機能であれば, あなたはより一層の情報を提示する必要があり, その手続きは幾分伸びることになるでしょう.
もし新機能ではなければこの節はもう読むのをやめて次のところまで飛ばしてしまっても構いません.
もし新機能であるならあなたはだいたい200語程度で EEPLight を作成し, 私達に送信するメールに同梱する必要があります. 興味深いその新機能に対する回答を受信するまでにかかる時間はおよそ一ヶ月程度見込まれるでしょう.
パッチを送付する前に一貫したユーザ情報で git を設定しておいてください. 出来ればあなたの実名及び仕事用のメールアドレスで(例えば erlang-patches メーリングリストで使用しているもの).
簡単なリファレンスとして, ここに関連する git コマンドを記載しておきます:
git config --global user.name "Your Name Comes Here" git config --global user.email [email protected]
私達の毎日のテストを簡単にするために, すべてのパッチは maint を基準にしていることを望みます. レビューの後, あなたの新機能が最終的に master ブランチに行き着くと判断されればパッチを master に rebase するよう要求されることもあるかもしれません.
では, maint (現行メジャーリリース用のメンテナスブランチ)から新しいブランチを作りましょう.
これは以下の手順で行えます (既に github アカウントを持っていてサインインしている前提で進めます):
- Erlang/OTP git プロジェクトのページ を開き, 自分用のフォークを作るために ‘fork’ というボタンをクリックします(これを行うのは一度だけにしてください).
- ‘hardcore forking action’ が完了したら, あなたの新しくできたフォークのコピーを ‘あなたの’ clone url からチェックアウトします:
git clone [email protected]:your_username/otp.git
- 新しく作成された ‘otp’ ディレクトリに cd します.
-
OTP レポジトリを指す remote を作成します.
git remote add upstream git://github.com/erlang/otp.git
- あなたの変更を保持するための新しいリモートブランチを作成します (あなたの行う特定の変更をよく説明している名前を使ってください):
git push origin origin:refs/heads/new_feature_name
- 新しいブランチを追跡するようにします (これは新しいブランチへのswitchも行われます):
git checkout --track -b new_feature_name origin/new_feature_name
- 全ての変更を otp remote にある
master及び/若しくはmaintのあなたの新しいブランチへ pull します:
git pull upstream master
- あなたの変更を施し, ガイドラインに沿ってそれらをコミットし, それから OTP team に fetch request を送ってください.
- 作業の完了までにしばらく時間がかかる若しくはブランチを切り出したのより新しい
masterの更新が必要であれば, あなたのブランチをmasterへ rebase してください. ブランチをチェックアウト後に以下のコマンド:
git fetch upstream
… そしてマージ衝突があれば修正します. 適切な新しい
git rebase upstream/mastermasterをベースにした真っ直ぐの chain を必要とするので,masterからのマージは行わないでください. - 誰か別の人のパッチを下にしたパッチを作成するのなら, あなたはまさに次のことを行うことになります: その誰かのブランチからブランチをつくりなさい (そのブランチは適切な新しい
masterから枝分かれしているでしょう).
各ブランチには論理的に関連したコミットが含まれているべきです (例えば1つの機能の実装), いろいろな変更の寄せ集めにはしないでください.
OTP チームのブランチを upstream とするために forking tips on GitHub を参照してください.
- 分離した変更は分離して提出します. あるコミットを一文で説明できないのなら, それは恐らく論理的に別個の変更であり複数のコミットに分かれているべきでしょう.
- パワフルな
git bisectコマンドを活用できるように, 各コミットはコンパイル及び動作可能なようにしてください.
- しっかりしたコミットメッセージを書きましょう にあるガイドラインに従ってください.
- コメントアウトされたコードや必要でないファイルをコミットしないでください.
- 不要な白空白が含まれていないかコミット前に
git diff --checkで調べてください.
提案された変更に対するフィードバックを希望するだけであれば以下の手順は必要ではありませんが, OTP に含まれるようにしたいのなら最終的に必須になります.
- 既存のテストケースが失敗しないようにしてください.
- パッチが全ての主なプラットフォーム上でビルド及び動作するようにしてください (私たちの受け取るパッチには Linux 上では動作しても Windows 上で動作しないものが多くあります).
- あなたのコーディング及びインデントスタイルがあなたの変更の周囲のそれに従っているようにしてください. (将来のどこかでこれはスタイルガイドとしてドキュメントに含まれるかウェブサイトのどこかにおかれるでしょう, けれども今のところ準備できていません.)
- ほとんどのコードにおいて (Erlang 及び C), インデントはタブ及びスペースを用いて4文字単位で行われています. タブ文字は常に8文字分です (もし Emacs を使っているのなら, Erlang-mode を使い, C コードが適切にインデントされるように
.emacsに(setq c-basic-offset 4)を追加してください.)
- もしバグを修正しているのならバグを修正する 前に テストケースを書いてください (つまりテストケースがバグを捕まえることになります). git レポジトリにおいてテストスイートを持たないアプリケーションであれば, コミットメッセージに小さなコード例を提供するか失敗を引き起こすモジュールをメールすると喜ばれるでしょう.
- もし新機能を実装しているのであれば, 新しいテストケース及び/若しくは test_SUITES を書いてください (注釈: テストケースを書く一番の理由は新機能が正しく動作することを検出するのではなく, 将来の変更 — 恐らくは関係ないコードでの — が機能を壊した時に気付けるようにするためです.
- もし新機能を実装しているところであれば, 機能を説明する ドキュメント も更新してください.
- パッチが後方互換を壊さないようにしてください. 一般的に, 私達は後方非互換が含まれるのはメジャーリリースでのみとしており, またそれがとても良い分別であり寒冷であることから最初にその機能を非推奨としてから１つか２つのリリースをおいてです.
- 一般的に, 言語の変更/拡張若しくは大幅な更新はメジャー更新
- In general, language changes/extensions or major updates to Kernel and STDLIB also require an EEP (Erlang Enhancement Proposal) to be written and apprloved before they can be included in OTP.
pull するべきあなたの github レポジトリ及びブランチ名へのリファレンス(及びそれが新機能であれば EEPLight ドキュメント)を書いたメールを [email protected] 宛に送ってください. 私たちがパッチの取り出しを本当に簡便にするためには, 完全な git コマンドを含めるようにしてください. 例えば:
git fetch git://github.com/bjorng/otp.git my-cool-updates
my-cool-updates はブランチの名前です.
加えて変更点を見るために以下の２つのリンクを含めてください:
https://github.com/mygithub/otp/compare/erlang:BASE...my-cool-updates https://github.com/mygithub/otp/compare/erlang:BASE...my-cool-updates.patch
BASE はベースにしたブランチ, maint 若しくは master です.
For the diff to be correct you need to make sure that the default branch configured on github is set to maint or master (which is the case when you fork) and is up-to-date (same as upstream/BRANCH).
(We also accept inline patches compatible with format generated by git format-patch, but please make sure your email client has not garbled the message.)
パッチが 新機能 か バグ修正 かに関わらず, 確認のメールが 1-3 営業日で届くでしょう.
パッチが 新機能 であれば以下の事が起こります:
- あなたが私達に(Erlang/OTP EEPLight ドキュメントと共に)パッチを送信します
- 私達はあなたのパッチを受信し, パッチを受信したことを確認(confirmation)するメールを送り返します. 想定期間: １営業日
- あなたの新機能パッチ提案を受信した後数日のうちにそれが受信されたことの承認を受け取るでしょう. その後にパッチは OTP 開発者によってレビューされます. このレビュープロセスにおいてその機能は優先付け(triage)されます. それはいつか私達のキューを通過しますが, 3-4週間で優先付けの回答をするつもりです:
- 青信号 – 新機能パッチ提案はよさげに見え, 提案された設計もよさげであった.
これは欲しい機能であり良く設計されている – 素晴らしいがまだいくつかの作業の目的があります:- 失敗するテストケース
- ドキュメントの不足
- いくつかのプラットフォームでの対応の不足 (Windows)
- 黄信号 – 新機能パッチ提案はよさげに見えるが, 提案された設計に不備若しくは不明確な点がある.
これは欲しい機能ではあるがその設計には不備がある若しくはセマンティクスの変更(semantic changes)がある.
これはあなたの提案はこのままでは受け入れることができないことも意味します.
以下の２つのいずれかが発生するでしょう:- あなたの提案は OTP 技術ボードによる追加のレビューが必要であり, これにはさらなる時間が必要になります
ボールは OTP 側にあります. - あなたの提案には別のアプローチが必要であり, 私達はなぜ現在のアプローチではまずいのかを説明します.
ボールはあなた側にあります.
- あなたの提案は OTP 技術ボードによる追加のレビューが必要であり, これにはさらなる時間が必要になります
- 赤信号 – 新機能パッチ提案は却下されました.
この場合には様々な理由で提案は却下されます.- その機能はシステムに対して重大すぎる影響をもたらします
- 追加による複雑さの増大が大きすぎます
- 互換性に変化が生じます
- また私達が問題若しくは必要ないとみなすその他の変更であった.
- 青信号 – 新機能パッチ提案はよさげに見え, 提案された設計もよさげであった.
- テストが実行され, パッチは詳細に検討されます. 想定期間: １営業日
- パッチは担当の開発者によってレビューされます. 想定期間: 1-3営業日
- パッチ及び Erlang/OTP のテスト及びビルドが動作すれば(原文:is positive)そしてその場合にのみパッチは適切な master 若しくは maint ブランチへとマージされます.
パッチが バグ修正 であれば以下の事が起こります:
- あなたが私達に(適切なリンクが記載された)パッチを送信します
- 私達はあなたのパッチを受信し, ざっくりと検討します. 想定期間: １営業日
- パッチは適切な ‘pu’ ブランチへとマージされます
- テストが実行され, パッチは詳細に検討されます. 想定期間: １営業日
- パッチは担当の開発者によってレビューされます. 想定期間: 1-3営業日
- パッチ及び Erlang/OTP のテスト及びビルドが動作すれば(原文:is positive)そしてその場合にのみパッチは適切な master 若しくは maint ブランチへとマージされます.
- そうではなく, もしパッチが明らかに間違っている若しくは適切ではないのであれば, あなたにそのように伝えるでしょう. 即時拒否となる原因には以下のものがあります(これらのみには限りません):
- 後方互換を露骨に破壊している.
- 明らかに安全でないコーディング手法を用いている若しくは強く非可搬的なコード.
- いくつかの異なる変更が入り交じっている及び/若しくは変更されていないコードに対する不必要な再インデント. 変更を複数のコミット及び/若しくはブランチに分け, 変更していない箇所のインデントを変更しないように回答します.
pu ブランチにあるどのブランチもそれをベースとするべきでは ありません, これはしょっちゅう現在の開発ブランチの頭を起点として1から再構成されます.
pu ブランチの自動テスト及びビルドを実行します.
もし pu に含まれるブランチがビルド上の問題を引き起こしたら, そのブランチはドロップされます. 訂正を受け取るとそれは最投入されます.
テストケースに失敗が生じた時もドロップされるでしょう.
別の方法でそのissueに取り組む場合にもドロップされるでしょう.
パッチは卒業若しくはドロップアウトするまで pu ブランチで"調理"されます.
パッチに対して以下の処理が(一度若しくは複数回)行われます:
- もしパッチが OTP準拠でないのなら, それは新しい若しくは拡張されたバージョンとしてオリジナルの作者若しくは他の誰かによって置き換えられます.
- もしいくつかのプラットフォームにおいてそれが
puに取り込まれる以前には見つからなかったビルド上の問題(若しくは多くのテストケースの失敗)が起きたのなら, その問題が修正されるまでpuからは取り除かれます.
- 誰でも批評, 改善の提案, 若しくはパッチが既存のアプリケーションを壊すといった報告を行えます. もし重大な問題が残っていて, そしてそれを修正するよう方法が見つからなかった場合, パッチはドロップされるでしょう.
- 長い間(数ヶ月)に渡ってアクティブにならない既知のissueに関するパッチはドロップされるでしょう.
通常パッチは OTP準拠基準をパスすると, maint 若しくは master ブランチへと卒業します. 通常問い合わせにあるアプリケーションのメンテナがパッチが卒業する時を決定します. 大きなパッチや後方互換を壊すかの境界にいるパッチに対しては OTP グループにいる幾人かの人々が決定に関与します.