================================== これは、 linux-2.6.39/Documentation/SubmittingPatches の和訳です。翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > 翻訳日： 2011/06/09 翻訳者： Keiichi Kii 校正者： Masanari Kobayashi さん Matsukura さん Takeshi Hamasaki さん ================================== Linux カーネルに変更を加えるための Howto 又はかの Linus Torvalds の取り扱い説明書 Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッチの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんをおじけづかせることもあります。この文章はあなたの変更を大いに受け入れてもらえやすくする提案を集めたものです。コードを投稿する前に、Documentation/SubmitChecklist の項目リストに目を通してチェックしてください。もしあなたがドライバーを投稿しようとしているなら、Documentation/SubmittingDrivers にも目を通してください。 -------------------------------------------- セクション1 パッチの作り方と送り方 -------------------------------------------- 1) 「 diff -up 」 ------------ パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。 Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引数を指定して、unified 形式のパッチを作成することを確認してください。また、変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルートディレクトリを基準にしないといけません。 1個のファイルについてのパッチを作成するためには、ほとんどの場合、以下の作業を行えば十分です。 SRCTREE= linux-2.6 MYFILE= drivers/net/mydriver.c cd $SRCTREE cp $MYFILE $MYFILE.orig vi $MYFILE # make your change cd .. diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch 複数のファイルについてのパッチを作成するためには、素の( vanilla )、すなわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネルソースとの差分を生成しないといけません。例えば、 MYSRC= /devel/linux-2.6 tar xvfz linux-2.6.12.tar.gz mv linux-2.6.12 linux-2.6.12-vanilla diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ linux-2.6.12-vanilla $MYSRC > /tmp/patch dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成されたファイルの一覧がのっています。そして、それらはパッチを生成する diff(1) コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョンの Linux カーネルソースツリーに含まれています。それより前のバージョンの Linux カーネルソースツリーに対する dontdiff ファイルは、から取得することができます。投稿するパッチの中に関係のない余分なファイルが含まれていないことを確認してください。diff(1) コマンドで生成したパッチがあなたの意図したとおりのものであることを確認してください。もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチを意味のあるひとまとまりごとに分けたいと思うかもしれません。これは他のカーネル開発者にとってレビューしやすくなるので、あなたのパッチを受け入れてもらうためにはとても重要なことです。これを補助できる多くのスクリプトがあります。 Quilt: http://savannah.nongnu.org/projects/quilt Andrew Morton's patch scripts: http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz このリンクの先のスクリプトの代わりとして、quilt がパッチマネジメントツールとして推奨されています(上のリンクを見てください)。 2) パッチに対する説明パッチの中の変更点に対する技術的な詳細について説明してください。説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシステム X に対する更新を含んでいます。どうか取り入れてください。」などです。パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」のコミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。以下の #15 を見てください。説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要があるという兆候です。次の #3 を見てください。パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由をパッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ書かないでください。そして、パッチをマージする人にパッチの説明を探させそれをパッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する手間をかけさせないでください。つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく過去のバージョンのパッチを受け取ってもいない人がいます。登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID や URL を明記してください。 3) パッチの分割意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分けてください。もし変更箇所に API の更新と、その新しい API を使う新たなドライバーが含まれているなら、2つのパッチに分けてください。一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加えるのであれば、その変更を1つのパッチにまとめてください。言いかえると、意味的に同じ1つの変更は1つのパッチの中に含まれます。あるパッチが変更を完結させるために他のパッチに依存していたとしても、それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存している」と簡単に注意書きをつけてください。もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは 15かそこらのパッチを送り、そのレビューと統合を待って下さい。 4) パッチのスタイルチェックあなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反していないかをチェックして下さい。その詳細を Documentation/CodingStyle で見つけることができます。コーディングスタイルの違反はレビューする人の時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく拒否されるでしょう。あなたはパッチを投稿する前に最低限パッチスタイルチェッカー ( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な理由を示せるようにしておく必要があります。 5) 電子メールの宛先の選び方 MAINTAINERS ファイルとソースコードに目を通してください。そして、その変更がメンテナのいる特定のサブシステムに加えられるものであることが分かれば、その人に電子メールを送ってください。もし、メンテナが載っていなかったり、メンテナからの応答がないなら、 LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんどのカーネル開発者はこのメーリングリストに目を通しており、変更に対してコメントを得ることができます。 15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らないでください!!! Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者です。電子メールアドレスは torvalds@linux-foundation.org になります。彼は多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは避けるべきです。バグフィックスであったり、自明な変更であったり、話し合いをほとんど必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まずは LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを Linus へ送るべきです。 6) CC (カーボンコピー)先の選び方特に理由がないなら、LKML にも CC してください。 Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはその変更に対してコメントをくれたり、コードに対してレビューや提案をくれるかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメーリングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステムなどの特定のサブシステムに関するメーリングリストもあります。あなたの変更に、はっきりと関連のあるメーリングリストについて知りたければ MAINTAINERS ファイルを参照してください。 VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記のサイトに載っています。もし、変更がユーザランドのカーネルインタフェースに影響を与えるのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧があります)に man ページのパッチを送ってください。少なくとも情報がマニュアルページの中に入ってくるように、変更が起きたという通知を送ってください。たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を加えたときには、いつもメンテナに CC するのを忘れないようにしてください。小さなパッチであれば、Trivial Patch Monkey(ちょっとしたパッチを集めている) に CC してもいいです。その現管理者については MAINTAINERS ファイルを見てください。ちょっとしたパッチとは以下のルールのどれか1つを満たしていなければなりません。・ドキュメントのスペルミスの修正・grep(1) コマンドによる検索を困難にしているスペルの修正・コンパイル時の警告の修正(無駄な警告が散乱することは好ましくないためです) ・コンパイル問題の修正(それらの修正が本当に正しい場合に限る) ・実行時の問題の修正(それらの修正が本当に問題を修正している場合に限る) ・廃止予定の関数やマクロを使用しているコードの除去(例 check_region ) ・問い合わせ先やドキュメントの修正・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲であればアーキテクチャ特有のことでも他の人がコピーできます) ・作者やメンテナによる修正(すなわち patch monkey の再転送モード) 7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントできる必要があります。カーネル開発者にとって、あなたが書いたコードの特定の部分にコメントをするために、標準的な電子メールクライアントで変更が引用できることは重要です。上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿されるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッチを改悪するエディターの折り返し機能に注意してください。パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテキストとして送信するとは限らないでしょう。そうなると、電子メールクライアントがコードに対するコメントを付けることをできなくします。また、 MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を受け入れてもらう可能性が低くなってしまいます。例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするのであれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定のヒントについては Documentation/email-clients.txt を参照してください。 8) 電子メールのサイズパッチを Linus へ送るときは常に #7 の手順に従ってください。大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能なサーバに保存し、保存場所を示す URL を伝えるほうが適切です。 9) カーネルバージョンの明記パッチが対象とするカーネルのバージョンをパッチの概要か電子メールのサブジェクトに付けることが重要です。パッチが最新バージョンのカーネルに正しく適用できなければ、Linus はそのパッチを採用しないでしょう。 10) がっかりせず再投稿パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッチを気に入って採用すれば、Linus がリリースする次のバージョンのカーネルの中で姿を見せるでしょう。しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新したパッチを投稿するのはあなたの仕事です。 Linus があなたのパッチに対して何のコメントもなく不採用にすることは極めて普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受け取っていないのであれば、以下の理由が考えられます。 * パッチが最新バージョンの Linux カーネルにきちんと適用できなかった * パッチが LKML で十分に議論されていなかった * スタイルの問題(セクション2を参照) * 電子メールフォーマットの問題(このセクションを参照) * パッチに対する技術的な問題 * Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見失った * 不愉快にさせている判断できない場合は、LKML にコメントを頼んでください。 11) サブジェクトに「 PATCH 」 Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他のカーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるのかをより簡単に識別できます。 12) パッチへの署名誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かのメンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入しました。「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、あなたがそのパッチをオープンソースとして提供する権利を保持している、という証明をパッチの説明の末尾に一行記載するというものです。ルールはとても単純です。以下の項目を確認して下さい。原作者の証明書( DCO ) 1.1 このプロジェクトに寄与するものとして、以下のことを証明する。 (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイル中に明示されたオープンソースライセンスの下で公開する権利を持っている。もしくは、 (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバーされている既存の作品を元にしている。同時に、私はそのライセンスの下で、私が全体又は一部作成した修正物を、ファイル中で示される同一のオープンソースライセンスで(異なるライセンスの下で投稿することが許可されている場合を除いて)投稿する権利を持っている。もしくは、 (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供されたものであり、私はそれに変更を加えていない。私はこのプロジェクトと本寄与が公のものであることに理解及び同意する。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を含む)が無期限に保全されることと、当該プロジェクト又は関連するオープンソースライセンスに沿った形で再配布されることに理解及び同意する。もしこれに同意できるなら、以下のような1行を追加してください。 Signed-off-by: Random J Developer 実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。) 人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別な情報を示したりすることができます。あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身のツリーにマージするために、わずかに変更が必要となる場合があります。なぜならあなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分をとるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費することになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまうことはとても失礼なことです。この問題を解決するために、末尾の投稿者の Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を加えたことを示す1行を追加することが推奨されています。 (その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたにあることを明確にするのに十分な方法のようです。例えば、 Signed-off-by: Random J Developer [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] Signed-off-by: Lucky K Maintainer あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に有用となります。いかなる事情があってもチェンジログに出てくる作成者のアイデンティティ情報(From ヘッダ)は変更できないことに注意してください。バックポートする人のための特別な注意事項。追跡を容易に行うために、コミットメッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述することは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。 Date: Tue May 13 19:10:30 2008 +0000 SCSI: libiscsi regression in 2.6.25: fix nop timer handling commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream そして、これは 2.4 ツリーでの一例です。 Date: Tue May 13 22:12:27 2008 +0200 wireless, airo: waitbusy() won't delay [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを解決しようとしている人にとって価値のある支援となります。 13) いつ Acked-by: と Cc: を使うのか「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチの伝播パスにいたことを示しています。ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対する承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使えます。Acked-by: はパッチのチェンジログにも追加されます。パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチの伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。 Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが少なくともパッチをレビューし、同意を示しているという記録です。そのようなことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を Acked-by: へ置き換えることがあります。 Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステムのメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、メーリングリストアーカイブの中の大元の議論を参照すべきです。パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの明確なアクションなしに付与できる唯一のタグです。このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたことを明文化します。 14) Reported-by と Tested-by: と Reviewed-by: の利用他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与をクレジットするために、Reported-by: タグを追加することを検討してください。こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再びコミュニティの力となってくれるでしょう。ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、問題が公の場で報告されていなかったのであれば。 Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功していることを示します。このタグはメンテナにテストが実施済みであることを知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に対するクレジットを保証します。 Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、受け入れ可能とみなされたパッチであることを示します。レビューアによる監督宣言私は Reviewed-by: タグを提示することによって、以下のことを明言する。 (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性(訳注)」を検証し、技術的側面からパッチをレビュー済みである。訳注: 「即応性」の原文は "readiness"。パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に行うことができる状態であるかどうかを "readiness" という単語で表現している。 (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済みである。私はそれらのコメントに対する投稿者の返答に満足している。 (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それがカーネルにとって価値のある変更であること、そして、(2)統合に際して議論になり得るような問題はないものと確信している。 (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる状況においてその宣言した目的や機能が正しく実現することに関して、いかなる保証もしない (特にどこかで明示しない限り)。 Reviewd-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグはレビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとしたレビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたのパッチをカーネルにマージする可能性を高めるでしょう。 15) 標準的なパッチのフォーマット標準的なパッチのサブジェクトは以下のとおりです。 Subject: [PATCH 001/123] subsystem: summary phrase 標準的なパッチの、電子メールのボディは以下の項目を含んでいます。 - パッチの作成者を明記する「 from 」行 - 空行 - 説明本体。これはこのパッチを説明するために無期限のチェンジログ (変更履歴)にコピーされます。上述した「 Signed-off-by: 」行。これも説明本体と同じくチェンジログ内にコピーされます。 - マーカー行は単純に「 --- 」です。 - 余計なコメントは、チェンジログには不適切です。 - 実際のパッチ(差分出力) サブジェクト行のフォーマットは、アルファベット順で電子メールをとてもソートしやすいものになっています。(ほとんどの電子メールクライアントはソートをサポートしています)パッチのサブジェクトの連番は0詰めであるため、数字でのソートとアルファベットでのソートは同じ結果になります。電子メールのサブジェクト内のサブシステム表記は、パッチが適用される分野またはサブシステムを識別できるようにすべきです。電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確に表現しなければなりません。「summary phrase」をファイル名にしてはいけません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数のパッチ群です)。あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子になるように心がけてください。「summary phrase」は git のチェンジログの中へずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照するために議論の中で利用するかもしれません。人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、唯一目にとまる情報となるでしょう。これらの理由のため、「summary phrase」はなぜパッチが必要であるか、パッチが何を変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまくまとめられている概要となるべきです。「summary phrase」は「Subject: [PATCH tag]

」のように、大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを表現します。一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対するコメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つのパッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けてもかまいません。これは開発者がパッチを適用する順番を確実に把握するためです。そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは適用するのを保証するためです。サブジェクトの例を二つ Subject: [patch 2/5] ext2: improve scalability of bitmap searching Subject: [PATCHv2 001/207] x86: fix eflags tracking 「 from 」行は電子メールのボディの一番最初の行でなければなりません。その形式は以下のとおりです。 From: Original Author 「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされている人を特定するものです。「 from 」行がかけていると、電子メールのヘッダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使われるでしょう。説明本体は無期限のソースのチェンジログにコミットされます。なので、説明本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人がその詳細を思い出すことができるものでなければなりません。パッチが対処する障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つけることができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要はありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端部分を認識させるという重要な役目を果たします。「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンドがあります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチにおいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメントは無期限に保存されるチェンジログにとって適切ではありません。そのため、このようなコメントもマーカー行の後に書かれるべきです。このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを表す「パッチの変更履歴」が挙げられます。「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」を指定してください(インデントを含めてちょうど80列に合うでしょう)。適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照してください。 16) 「git pull」要求の送り方(Linus の電子メールから) 間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスとブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリックで全て選択できます。正しい形式は下記の通りです。 "Please pull from git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus to get these changes:" その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要がなくなればより快適になるでしょう)。 diffstat の結果を生成するために「 git diff -M --stat --summary 」を使ってください。-M オプションはファイル名の変更を検知でき、--summary オプションは新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。 -M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と判断するためです。 ------------------------------------ セクション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). Jeff Garzik, "Linux kernel patch submission format". Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! Kernel Documentation/CodingStyle: Linus Torvalds's mail on the canonical patch format: Andi Kleen, "On submitting kernel patches" Some strategies to get difficult or controversial changes in. http://halobates.de/on-submitting-patches.pdf --