52.5 GNU Emacsへのパッチの送付

GNU Emacsを改善するためにバグfixを書きたいなら、それはとても助けになります。変更を送るとき、メンテナーがそれらを使うのが簡単になるように、どうか以下のガイドラインにしたがってください。これらのガイドラインにしたがわない場合でも、あなたの情報はまだ有用でしょうが、それを使用するのに余分な作業が必要になります。GNU Emacsの保守は最良の状況でも多くの作業を要すので、わたしたちを助けるのにあなたがベストをすくさなければ、わたしたちはそれを維持できないのです。

各パッチは、わたしたちがそれを正しく評価するために、簡単な情報をもたなければなりません。

そのような情報がすべてあるなら、それらをメールメッセージにまとめて、開発者に送ってください。推奨される送信先は、bug-gnu-emacs@gnu.orgです(これはバグおよび機能のためのリストです)。なぜなら、このリストにはパッチを簡単に確認するための追跡システム(tracking system)があるからです。そのパッチが完全ではなく、さらに議論が必要だと思うときは、かわりにそれをemacs-devel@gnu.orgに送りたいと思うかもしれません。パッチを改訂したら、それを最初のトピックにたいするfollowupとして送ってください。

わたしたちはそのパッチをプレーンテキストとして受けとるのを好みます。それはインライン(メールクライアントが行ブレークを変更しないように注意してください)、またはMIMEアタッチメントのどちらでも構いません。

• そのパッチがどんな問題をfixするのか、またはどんな改善をもたらすのか、あなたの変更にたいする説明を含めてください。
  • 既存のバグにたいするfixについては、‘bug-gnu-emacs’リストの関連するディスカッションか、https://debbugs.gnu.orgのGNU Bug Trackerのバグエントリーに返信するのが最善でしょう。その変更が、なぜバグをfixするのか説明してください。
  • 新しい機能については、その機能と実装についての説明を含めてください。
  • 新しいバグにたいしては、あなたがfixしたと思っている問題にたいする、正しいバグレポートを含めてください。それを採用する前に、わたしたちはその変更が正しいと、私たち自身に納得させる必要があります。もしそれが正しくても、問題を再現する方法がない場合、それを理解する妨げになるでしょう。
• 将来このソースを読む人の理解を助けとなるように、なぜこの変更が必要なのか、適切なコメントを含めてください。
• 異なる理由にたいする変更を一緒に混ぜないでください。それらを個別に送ってください。

  異なる理由にたいして2つの変更を行なった場合、わたしたちをそれを一緒に採用したいとは思わないでしょう。1つだけを採用したいと思うかもしれません。それらを合わせて1つのdiffにして送った場合、それらを区別するために — 変更のどの部分がどの目的のためかを理解するために — 余計な作業を行なう必要があります。これを行なう時間がない場合、わたしたちは変更全体を無視する必要があるかもしれません。

  1つの変更を記述したら、その変更の説明と一緒にそれをすぐに送れば、2つの変更は混ざることはなくなり、それらを区別する余計な作業なしに、わたしたちはそれぞれを正しく判断することができます。

• 1つの変更を終えたら、それをすぐに送ってください。ときどき人は多くの変更を累積して、すべて一緒に送るのがわたしたちの助けとなると考えます。上述したように、それは正にあなたにできる最悪のことです。

  変更は個別に送るべきなので、すぐに送ることができるでしょう。これは、その変更が重要なものなら、それをすぐに採用するオプションをわたしたちに与えます。

• パッチそのもの

  diffを作成するために、‘diff -u’を使用してください。コンテキストなしのdiffは確実に採用が困難です。それ以上に調べるのが難しくなります。わたしたちは変更の採用を望ましいか判断するために、つねにパッチを調べなければなりません。Contextフォーマットはコンテキストなしのdiffより優れていますが、好ましいのはUnifiedフォーマットです。

  GNU diffがある場合、Cコードのdiffの作成には‘diff -u -F'^[_a-zA-Z0-9$]\+ *('’を使用してください。これは変更のある関数名を表示します。

  Emacsリポジトリーを使用している場合、あなたのコピーが(たとえばgit pullなどにより)最新であることを確認してください。あなたの変更をプライベートのブランチにコミットして、git format-patch masterを使用することにより、マスターバージョンからパッチを生成できます。または変更をコミットせずに、git diffを使用することもできます。

• どちらが古いバージョンで、どちらが新しいバージョンか、あいまいになるのを避けてください。どうかdiffの第1引数に古いバージョン、2番目の引数に新しいバージョンを指定してください。そして一方のバージョンにたいして、それが古いバージョンなのか、変更した新しいバージョンなのかを示す名前をつけてください。
• あなたの変更にたいする、変更ログ(ChangeLog)のエントリーを記述してください。それにより、わたしたちがそれを記述するために余計な作業をしなくてすみ、あなたが行なった変更をわたしたちが理解する助けにもなります。

  変更された場所を示すのが、変更ログの目的です。したがって変更した関数について、具体的である必要があります。大きな関数では、関数のどこを変更したか示すのが、助けになる場合が多々あります。

  それとは逆に、変更箇所を示せば、変更ログで変更目的の説明をする必要はありません。したがって、新しい関数を追加した場合、必要なのはそれが新しいということを示すだけです。変更目的の説明が必要だと感じたら、多分その通りなのでしょう、がコードのコメントにその説明を記述してください。変更目的はそこに記述されているほうが、より有用です。

  どのような種類の情報を記述するかを見るために、最近のコミットにたいする変更ログエントリーを見て、わたしたちが使用しているスタイルを学んでください。他のプロジェクトとは異なり、たとえばTexinfoファイルのような、ドキュメントにたいする変更ログも必要です。Change Log、および Change Log Concepts in GNU Coding Standardsを参照してください。

• fixを記述するときは、わたしたちが他のシステムを壊すような変更は採用できないということを、念頭に置いてください。あなたの変更が、ほかのタイプのシステムでコンパイルされた場合の影響について、考えてください。

  一般的には改善となるかもしれないが、そう確信するのは難しいようなfixを送る人が、ときどきいます。そのような変更を採用するのは、わたしたちがそれをとても慎重に調べなければならないので、難しくなります。もちろん、その変更が正しい理由の説明は、わたしたちを納得させる助けになります。

  一番安全な変更は、特定の機種の設定ファイルにたいする変更です。これらの変更は、新しいバグを他の機種に作成しないので、安全です。

  インストールの安全性が明確な形式でパッチをデザインして、わたしたちの作業量を、良い状態に保つ助けとなってください。