---

54.5 GNU Emacsへのパッチの送付

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

各パッチは、わたしたちがそれを正しく評価するために、簡単な情報をもたなければなりません。これらの情報については以下で説明します。

それらの情報がすべて揃ったら、M-x submit-emacs-patchコマンドを使ってパッチを送信してください。このコマンドはそのパッチの件名とパッチファイルの入力を求めます。それからパッチファイルが添付されたMessageモードのバッファーを作成、表示してそのパッチに関するより詳細な説明、それから以下で求めるようなその他の情報を追加できるようにします。それらが終わったらC-c C-cをタイプして、電子メールで開発者にパッチを送信してください。そのメールはhttps://debbugs.gnu.orgにある、GNU Bug Trackerに送信されるでしょう。Trackerはバグレポートに行うように、あなたの投稿に番号を割り当てます。通常だと開発者が返信することになるので(さらなる詳細や追加の情報を求めるためかもしれません)、必ず有効な返信用のメールアドレスを含めるようにしてください。

パッチの投稿の一部としてわたしたちが提供して欲しいのは以下の情報です:

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

  異なる理由にたいして2つの変更を行なった場合、わたしたちをそれを一緒に採用したいとは思わないでしょう。1つだけを採用したいと思うかもしれないし、それぞれを異なるバージョンのEmacsにインストールしたいと思うかもしれません。それらを合わせて1つのdiffにして送った場合、それらを区別するために(変更のどの部分がどの目的のためかを理解するために)、余計な作業を行なう必要があります。それを行なう時間がない場合には、わたしたちはそのパッチの組み込みを長期間先延ばしする必要が生じるかもしれません。

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

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

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

• パッチそのもの。これは以下のいずれかの方法によって生成できます:
  • - Emacsレポジトリを使用している場合、あなたのコピーが(たとえばgit pullなどにより)最新であることを確認してください。あなたの変更をプライベートのブランチにコミットして、git format-patch masterを使用することにより、マスターバージョンからパッチを生成できます(パッチの適用が容易になるので、これが推奨する方法)。または以下で述べるように変更をコミットせずに、git diffを使用することもできます。
  • - diff の作成にはdiff -uを使用してください。GNU diffがある場合、Cコードのdiffの作成にはdiff -u -F'^[_a-zA-Z0-9$]\\+ *('を使用してください。これは変更のある関数名を表示します。

    diffを作成する際にはどちらが古いバージョンで、どちらが新しいバージョンか、あいまいになるのを避けてください。どうかdiffの第1引数に古いバージョン、2番目の引数に新しいバージョンを指定してください。そして一方のバージョンにたいして、それが古いバージョンなのか、変更した新しいバージョンなのかを示す名前をつけてください。

• あなたの変更にたいする、コミットログのエントリーを記述してください。それにより、わたしたちがそれを記述するために余計な作業をしなくてすみ、あなたが行なった変更をわたしたちが理解する助けにもなります。

  コミットログはその変更の根拠、あなたのパッチが修整を試みる問題を変更後のコードがどのように解決するかを説明して、更に人々がその変更をどこで見つけられるかを示すことが目的です。したがって変更した関数とその理由を具体的に記す必要があります。適切なコミットログメッセージにたいするわたしたちのスタイルと要件については、どうかEmacsソースツリーにあるファイルCONTRIBUTEのセクション“Commit messages”を参照してください。

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

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

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

  もっとも安全な変更は、特定の機種やシステムで使用されるファイルやファイルの一部にたいする変更です。これらの変更は、新しいバグを他の機種やシステムに作成しないので安全です。

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