とりあえず、誤訳もあるだろうが、読んでみたので、掲載しておく。

http://wiki.qemu.org/Contribute/SubmitAPatch

Edition: 22:04, 8 October 2015 Jsnow
Licensed under GNU Free Documentation License 1.2.

貢献/パッチを提出する

QEMUは(バグの修正であれ新しい機能の追加であれ)コードの貢献を歓迎しています。しかし、私たちはたくさんのパッチを受け取っており、パッチを提出するためのガイドラインを用意しています。これらに従うことによって、私たちのコードレビューを容易にし、より早くあなたのパッチがコミットされることになります。

全てのQEMUへの貢献は、qemu-develメーリングリストに「パッチとして送られ」なくてはいけません。パッチの貢献は、バグトラッカーにポストしたり、フォーラムにポストしたり、外部にホストしてそのリンクを送ったりしてはいけません。

メーリングリストにポストするのに、購読する必要はありません(メーリングリストのポリシーとして、CCを全て保持し、購読していない人が始めたスレッドに入り続けられるように、全員に返信することになっています)。購読するならば、配信されてくる電子メールが非常に多いのを覚悟してください。一週間に100通を越えることがよくあります。メーリングリストはモデレートされています。ある電子メールアドレスからの最初のポストは(購読しているにしろ、していないにしろ)、モデレーターがあなたの電子メールアドレスをホワイトリストに追加するまでしばらく時間がかかります。

パッチの書き方

英語を使う

正しい英語であれば助かります。もし不安があるならば、codespell等のプログラムを、コードと文書の中の最も一般的な綴りの間違いを見つけるのに使ってください;

QEMUのコーディングスタイルを使う

私たちのコーディングスタイルに従っているか確認するために、提出する前に、「scripts/checkpatch.pl <パッチファイル>」を実行してください。特にCプリプロセッサーが絡む場合には、checkpatch.plが絶対正しいと言うことはありません。常識も使ってください。

以下も参照してください。

長いパッチは分割する

長いパッチは、論理的に正しいコードの変更からなるパッチ連続として分割してください。それぞれの変更は、コンパイルでき、実行できなくてはなりません。例えば、1つ目のパッチでMakefileにファイルを追加し、2つ目のパッチでそのファイル自体を追加すると言った形式は認められません(このルールは、後ほどgit bisectのようなツールを使う場合に、あるバグを追っている時に、そのバグ以外の問題でQEMUが動かないと言うことがないようにするためです)。文書は最初にしてください。最後にしてはいけません。と言うのは、誰かが一連のパッチを読む際に、文書をクリーンルームで評価し、コードと文書が一致しているかを確認することができるようにするためです。コミットメッセージで「Also, ...」と書かれているのであれば、複数のパッチに分割できると考えてください。適切に分割されたパッチと、良いコミットメッセージを書くことについてのアドバイスとしては、OpenStackのアドバイスを参照してください。

コードの移動を伴うパッチはレビューしやすくする

一連のパッチが大規模なコードの移動を必要とする場合には、そのリファクタリングのレビューを簡単にするコツがあります。意味が変わる変更(あるいは、関数の名称変更も)は、本来の別の一つのパッチにし、コードの移動の部分とは分けておきます。一時的に、git config diff.renames true; git config diff.algorithm patienceを使ってください。「diff.renames」プロパティーにより、ファイル名変更のパッチは、古いファイルを削除して新しいファイルを追加するのではなく、ファイル名変更に特化したコンパクトな表現になります。また、「diff.algorithm」プロパティーにより、元のファイルの}の行を別の変更された塊であるとして扱うことにより、連続しない一部分を古いファイルから新しいファイルに移す際に分かりにくさを低減させることができます。

コードの移動のパッチは以下のようにしてレビューに回されるのが理想的です。

git format-patch --stdout -1 > patch;
diff -u <(sed -n 's/^-//p' patch) <(sed -n 's/^\+//p' patch)

これにより、大規模なコードの移動ではない一部の変更に着目することができます。

無関係な変更を含まない

特に伝えておきたいこととして、体裁を整えたり、コーディングスタイルを変更したり、ホワイトスペースの変更を、パッチが変更しないコードについて変更しないでください(あなたの変更しているコードのコーディングスタイルの問題を数行修正するのは問題ありません)。もし、ある程度の大きさ部分のコードが本当に字下げを変更されたり、大規模なスタイルの修正されたりする必要があるのであれば、意味の変更のない変更として、別のパッチの形で提出してください。

QEMUのあまり変更されない部分についての小さなパッチは、重要ではないパッチのためのプロセスを使うことを検討してください。

意味のあるコミットメッセージを書く

コミットメッセージは意味があるように書かれるべきであり、歴史的な記録として、なぜどのあなたの変更が必要であるか、あるいは、有用かを明示するようにしてください。

QEMUは、一般的なgitのコミットメッセージの標準に従っています。つまり、1行目(これは、電子メールの件名になります)は、「サブシステム: 変更の1行でのまとめ」とします。「変更の1行でのまとめ」は、大文字で始め、再度には「.(ピリオド)」を付けません。 git short-log 30を見て、例として件名はどのようになっているか確認してください。 2行目は空行です。3行目からはパッチの詳細についての説明を記載し、空行を挟んで、Signed-off-by:の行を記載します。コミットメッセージの本文には、あなたの変更が重要である理由を記載してください。コメントには、「これはこのバグを修正するものである」に類することは書かないでください(こういう内容は、電子メールの「---」の行以下に記載してください。その部分は最終的なコミットメッセージには含まれません)。コミットメッセージの本文は、読む人の電子メールクライアントが件名を離して表示させたとしても分かるように、独立した文章にしてください(つまり、「... so that」のように件名から文章が続いているのはいけません)。

パッチを提出する

適切なメンテナーをCCに入れる

パッチはTo:メーリングリストとCC:あなたの修正したファイルのメンテナーで送ってください。 MAINTAINERSファイルで、誰がメンテナーを確認できます。また、scripts/get_maintainer.plを使うことで、あなたの修正したファイルを最も良く変更しているコミッターが分かります。

例えば、

 ~/src/qemu/scripts/get_maintainer.pl -f hw/ide/core.c

添付ファイルとして送らない

パッチは本文中に記載し、レビューコメントを返信しやすいようにしてください。添付ファイルとして送ってはいけません。

git format-patchを使う

正しい差分の形式を使ってください。 git format-patchは、正しい形式のパッチを含んだ電子メールを生成します(どのように動くのか文書を確認してください)。 git send-emailでメーリングリストに送る前にカバーレターを変更することができます。 (私たちはgit send-emailを使うことを勧めています。なぜかと言うと、電子メールクライアントは、長い行を折り返したり、空白を削除したりすることがあるからです。ディストリビューションによっては、send-emailをデフォルトではインストールしていないことがあります。追加でダウンロードしなくてはいけない場合があります。例えば、Fedoraベースのシステムでは、git-emailをインストールします) 一連のパッチにはカバーレターが必要です。カバーレターは、スレッドの浅い部分になくてはなりません(全ての一連のパッチは、カバーレターへの返信であり、パッチ間の返信であってはなりません)。一つの独立したパッチは、カバーレターを必要としません(あえてカバーレターを使う場合には、--numberedを使い、カバーレターとパッチを件名で見分けられるようにしてください)。パッチは見付けやすいように新しくトップレベルのスレッドで送信してください。他の既存のスレッドに返信して、埋もれさせてはいけません。

パッチの電子メールはSigned-off-by:行を含まなくてはならない

詳しくは、SubmittingPatch 1.12を参照してください。これは必須であって、これがなければあなたのパッチを受け入れることはできません。別名や頭文字ではなく、本名を使うようにしてください。

意味のあるカバーレターを含める

レビュアーはレビューを始めた段階ではあなたのゴールを分かっていません。まだ文脈を十分に共有していないのです。一連のパッチの最後を見るまで、意味のある変更であると理解できないかもしれません。ゴールが不明確である一覧のパッチは、レビュアーが十分に考えられないため、レビューと修正のサイクルの数を増加させる恐れがあります。レビュアーとあなたの両方の利益のため、ゴールをカバーレターで説明するのです。そうすることで、パッチはよりスムースにレビューされ、より早くマージされます。カバーレターには、一連のパッチと通してのdiffstatを含めるのを忘れないでください。レビューをしようとする人があなたのカバーレターをチェックすることで、レビュアーが関心を持っているファイルを一連のパッチが変更しているかどうかを確認することができます。

必要であればRFCタグを使う

例えば、「[PATCH RFC v2]」のようにします。 git format-patch --subject-prefix=RFCが便利です。

「RFC」は、「Request For Comments(コメントを希望)」を意味し、あなたのパッチがmasterにそのまま適用されることを意図していないが、レビューして欲しいと言うことを示しています。

このようなことをする理由には以下のようなものがあります:

そのパッチが一旦保留されているOSのカーネルの変更に依存しているので、まだQEMUには取り入れて欲しくないが、レビューをする意味はある場合
パッチはまだ完成していないが(全ての使用事例を網羅していないとか、全てのターゲットで完了していないとか)、影響の大きいAPIの変更や設計について、先に勧める前にレビューを受けたい場合

この場合、一般的に、レビューされた内容はそのままコミットされないので、以下のようであるのが最良です:

慎重に使用する
カバーレターでなぜパッチがRFCなのか、どの分野でレビューして欲しいのか、レビュアーがなぜレビューすべきかのかを明確にする

コードレビューに参加する

全てのQEMUプロジェクトに提出されたパッチは、受け入れられる前に必ずレビューのプロセスを通過します。良くメンテナンスされている分野のコードは、速やかにレビューされますが、あまりメンテナンスされていない分野では遅れがちです。

コードレビューで発覚した問題を修正し続ける

そのままでQEMUに取り込まれるパッチは多くはありません。開発者がバグを発見したり、より明確なアプローチを示唆されたり、コードスタイルの問題を指摘されたり、コミットメッセージの誤字脱字を指摘されると言ったとこてぁ、極めてよくあることです。あなたは、このような指摘に応える必要があります。そして、問題を修正した第2版のパッチを送る必要があります。これは、あなたの側の時間と苦労を伴いますが、これをしなくては、QEMUにあなたの変更が取り込まれることは決してありません。これは、礼儀正しくあるということでもあります。あなたのコードをレビューし、改善を示唆するのに時間を費した開発者は、あなたがそれ以上に何かをしないのであれば、時間を浪費したと言うことになり、たいへんがっかりさせられます。

あなたのパッチへのコメントに返信する際には、全員に返信し送信者のみに返信しないようにしてください。全ての議論をメーリングリストに残しておくことで、全員がその内容を参照することができます。

レビューコメントに注意を払う

誰かがその時間をあなたのコードを。レビューするのに使ってくれたのです。その努力には敬意を払うべきです。以前にもらったレビューの内容を反映させることなく一連のパッチを投稿し続けることは、レビュアーを遠退かせ、あなたのパッチが行き詰まることを意味します。レビュアーは常に完璧であるとは限りません。ですので、レビュアーによる要求を全て盲目的に受け入れるのではなく、あなたのコードが正しいと主張することができます。一方で、誰かがレビューの過程であなたのコードに潜んでいる問題を指摘したが、結局あなたのコードが正しかったとします。そのような場合には、コミットメッセージや。コメントを修正し、なぜあなたのコードが正しいか説明するようにしてください。

もしレビューの過程で浮かび上がった問題を修正したら、それを修正した1つのパッチを投稿するのではなく、一連の全てのパッチを再送信するようにしてください。これによりメンテナーは手動でどのパッチが適切であるかを判別することなく、簡単に修正された一連のパッチを適用させることができます。新しいバージョンは完全に新しい電子メールあるいは一連の電子メールで送ってください。バージョン1に返信しようとするのは止めてください(こうすることにより、自動化されたパッチ電子メール取り扱いツールがv1とv2の電子メールを判別できるのを助けます)。

パッチを再送信する場合にはバージョンタグを付加する

最初のバージョン以外の全てのパッチはバージョンタグを含む必要があります。例えば、「[PATCH v2]」のようにします。これにより、誰もが最新バージョンを簡単に見分けることができるようになります。 (最初のバージョンは「v1」を付ける必要はありません。「[PATCH]」で十分です。) 一連のパッチにおいては、バージョンは一連のパッチの全てに付加される必要があります。一つのパッチのみが変更されたとしても、全てのパッチに「v2」を付加して再送信する必要があります。 1つの一連のパッチで違ったバージョンを付けようとしないでください。 git format-patchとgit send-emailのいずれも-v2オプションを使うことで、これらを簡単に実施することができます。新しいバージョンをそれぞれ新しいトップレベルのスレッドとして送信してください。以前のバージョンに返信して、埋もれさせてはいけません。多くのレビュアーがスレッドに深く潜らないと新しいパッチを見付けられないようではいけません。

パッチ間の履歴を含める

第2版以降のパッチには、以前のバージョンからの変更のまとめを含めるようにしてください。しかし、コミットメッセージに含めてはいけません。パッチの電子メールにおいて、「---」の行より上のみがコミットメッセージになりますので、ここのみがコミットされた再にgitの変更履歴となります。この部分は、このバージョンのパッチが何をしているのかと言う自己完結的な説明でなくてはなりません。6カ月後に見直しても誰もが分かるように書かれなくてはなりません。「---」の下でパッチ自体の上の行は、(git format-patchはdiffstatをここに挿入しますが)パッチを読んでくれる人に向けての意見を記載するのに良い場所です。「以前のバージョンからの変更点」はここに記載します。 git-publishスクリプトは、各バージョン間のまとめを追うのに便利です。また、git-backport-diffスクリプトは、バージョン間の変更に着目しているレビュアーに役立ちます。

コツ

Reviewed-by:タグを適切に使うことでレビューを助ける

長い一連のパッチをレビューする時、レビュアーはいくつかのパッチにReviewed-byタグを付けて返信することができます。これは、そのパッチは独立して扱って良いことを示します(ホワイトスペースの変更のようなコードの文脈に影響しない重要でないクリーンアップなど)。そのような返信を受け取ったら、Reviewed-byタグを手動でコミットメッセージに含め、パッチを次のバージョンにし、レビュアーがどのパッチは既にレビュー済みであるかが分かるようにします。

逆に、以前にレビューを受けたパッチを大幅に変更した場合には、Reviewed-byタグをコミットメッセージから削除し、以前のバージョンからの変更点を記載します。これによって、あなたの変更にレビュアーが注意を簡単に払えるようにします。

あなたのパッチが無視されているような場合

もしあなたのパッチが何の返信ももらえない場合には1から2週間後に「ping」を送るべきです。これは、パッチの電子メールに返信して電子メールを送ることによって行ないます。内容は、「ping」とパッチへのpatchworkまたはGMANEのページへのリンクです。なぜ無視されているのかを再度見直すのも大切です(メンテナーをCCに入れていないとか、以前のバージョンのレビューコメントに返信していないとか)。ですが、あまりメンテナンスされていない分野では、単に見過されている可能性があります。 pingしても無視されたら、1週間後に再度pingします。あなたは、あなたのパッチが適用されることに対して最もやる気のある人です。粘り強くなくてはなりません。

私のパッチが適用される時

メーリングリストであなたのパッチが十分にレビューされた後、その分野のメンテナーはメーリングリストにあなたのパッチが特定の準備用のブランチに適用した旨の連絡をします。定期的に、メンテナーはqemu mainlineにトピックブランチを集約するためのプルリクエストを送ります。あなたがある分野のコードのメンテナーになるまで、プルリクエストを送る必要はありません。メンテナーは、あなたのコミットをさらに変更することがあります。単純なマージ時の競合を解決するものである場合や、レビュー中に指摘された重要でない誤字脱字の修正をする場合がありますが、Signed-off-by行があなたの行に追加されます。そのメンテナーのツリーを通じて取り入れられたことを示すためです。メンテナーのプルリクエストが難しいマージ時の競合に遭遇することがあります。このような場合には、リベースト問題の解決を手助けして欲しいと依頼されるかもしれません。あなたのパッチが最初に良い返事をもらってからqemu.gitに含まれるようになるまで、数週間は必要かもしれません。リリースサイクルフリーズに期間に重なると、もっと長くかかるでしょう。

敬意を返す

ピアレビューは全ての人がレビューに時間を割く場合のみ成立します。もし全員が自分のレビューするよりも多くのパッチを提出するとしたら、パッチは停滞します。良いゴールは、自分が提出したのと同じ数だけ他の人のパッチをレビューすると言うことです。メンテナーほどコードベースに詳しくないからと言って心配しないでください。あなたがコードにあまり親しんでいなことにより、レビューが弱いと言うのは、完全に許されています。

Diary

QEMU Contribute/SubmitAPatch