submittingpatches

linux 内核源代码

標準的なパッチの、電子メールのボディは以下の項目を含んでいます。

  - パッチの作成者を明記する「 from 」行

  - 空行

  - 説明本体。これはこのパッチを説明するために無期限のチェンジログ
    (変更履歴)にコピーされます。

  - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン
    ジログ内にコピーされます。

  - マーカー行は単純に「 --- 」です。

  - 余計なコメントは、チェンジログには不適切です。

  - 実際のパッチ(差分出力)

サブジェクト行のフォーマットは、アルファベット順で電子メールをとても
ソートしやすいものになっています。(ほとんどの電子メールクライアント
はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ
るため、数字でのソートとアルファベットでのソートは同じ結果になります。

電子メールのサブジェクト内のサブシステム表記は、パッチが適用される
分野またはサブシステムを識別できるようにすべきです。

電子メールのサブジェクトの「概要の言い回し」はそのパッチの概要を正確
に表現しなければなりません。「概要の言い回し」をファイル名にしてはい
けません。一連のパッチ中でそれぞれのパッチは同じ「概要の言い回し」を
使ってはいけません(「一連のパッチ」とは順序付けられた関連のある複数の
パッチ群です)。

あなたの電子メールの「概要の言い回し」がそのパッチにとって世界で唯
一の識別子になるように心がけてください。「概要の言い回し」は git の
チェンジログの中へずっと伝播していきます。「概要の言い回し」は、開
発者が後でパッチを参照するために議論の中で利用するかもしれません。
人々はそのパッチに関連した議論を読むために「概要の言い回し」を使って
google で検索したがるでしょう。

サブジェクトの例を二つ

    Subject: [patch 2/5] ext2: improve scalability of bitmap searching
    Subject: [PATCHv2 001/207] x86: fix eflags tracking

「 from 」行は電子メールのボディの一番最初の行でなければなりません。
その形式は以下のとおりです。

        From: Original Author <[e-mail]>

「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ
ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ
ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ
れるでしょう。

説明本体は無期限のソースのチェンジログにコミットされます。なので、説明
本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人
がその詳細を思い出すことができるものでなければなりません。

「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端
部分を認識させるという重要な役目を果たします。

「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド
があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行
追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに
おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント
は無期限に保存されるチェンジログにとって適切ではありません。そのため、この
ようなコメントもマーカー行の後に書かれるべきです。ファイル名はカーネルソー
スツリーのトップディレクトリからの表記でリストされるため、横方向のスペース
をとり過ぎないように、diffstat コマンドにオプション「  -p 1 -w 70 」を指定し
てください(インデントを含めてちょうど80列に合うでしょう)。

適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して
ください。

------------------------------------
セクション2 - ヒントとTIPSと小技
------------------------------------

このセクションは Linux カーネルに変更を適用することに関係のある一般的な
「お約束」の多くを載せています。物事には例外というものがあります。しか
し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。

1) Documentation/CodingStyleを参照

言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
れません。

唯一の特筆すべき例外は、コードをあるファイルから別のファイルに移動
するときです。この場合、コードを移動するパッチでは、移動されるコード
に関して移動以外の変更を一切加えるべきではありません。これにより、
コードの移動とあなたが行ったコードの修正を明確に区別できるようにな
ります。これは実際に何が変更されたかをレビューする際の大きな助けに
なるとともに、ツールにコードの履歴を追跡させることも容易になります。

投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で
あなたのパッチをチェックしてください。このスタイルチェッカーは最終結
論としてではなく、指標としてみるべきです。もし、あなたのコードが違反
はしているが修正するより良く見えるのであれば、おそらくそのままにする
のがベストです。

スタイルチェッカーによる3段階のレポート:
 - エラー: 間違っている可能性が高い
 - 警告：注意してレビューする必要がある
 - チェック：考慮する必要がある

あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な
理由を示せるようにしておく必要があります。

2) #ifdefは見苦しい

ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中
で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、
条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し
てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
しょう。

まずいコードの簡単な例

	dev = alloc_etherdev (sizeof(struct funky_private));
	if (!dev)
		return -ENODEV;
	#ifdef CONFIG_NET_FUNKINESS
	init_funky_net(dev);
	#endif

クリーンアップしたコードの例

(in header)
	#ifndef CONFIG_NET_FUNKINESS
	static inline void init_funky_net (struct net_device *d) {}
	#endif

(in the code itself)
	dev = alloc_etherdev (sizeof(struct funky_private));
	if (!dev)
		return -ENODEV;
	init_funky_net(dev);

3) マクロより「 static inline 」を推奨

「 static inline 」関数はマクロよりもずっと推奨されています。それらは、
型安全性があり、長さにも制限が無く、フォーマットの制限もありません。
gcc においては、マクロと同じくらい軽いです。

マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの
いくつかの特定のケース)や「 static inline 」関数を使うことができないような
場所(マクロの引数の文字列連結のような)にだけ使われるべきです。

「 static inline 」は「 static __inline__ 」や「 extern inline 」や
「 extern __inline__ 」よりも適切です。

4) 設計に凝りすぎるな

それが有用になるかどうか分からないような不明瞭な将来を見越した設計
をしないでください。「できる限り簡単に、そして、それ以上簡単になら
ないような設計をしてください。」

----------------------
セクション3 参考文献
----------------------

Andrew Morton, "The perfect patch" (tpp).
  <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt>

Jeff Garzik, "Linux kernel patch submission format".
  <http://linux.yyz.us/patch-format.html>

Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
  <http://www.kroah.com/log/2005/03/31/>
  <http://www.kroah.com/log/2005/07/08/>
  <http://www.kroah.com/log/2005/10/19/>
  <http://www.kroah.com/log/2006/01/11/>

NO!!!! No more huge patch bombs to [e-mail] people!
  <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2>

Kernel Documentation/CodingStyle:
  <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle>

Linus Torvalds's mail on the canonical patch format:
  <http://lkml.org/lkml/2005/4/7/183>
--