パッチの投稿: カーネルにコードを入れるための必須ガイド¶
Warning
UNDER CONSTRUCTION!!
この文書は翻訳更新の作業中です。最新の内容は原文を参照してください。
Linux カーネルへ変更を投稿したい個人や企業にとって、もし「仕組み」に 慣れていなければ、そのプロセスは時に気後れするものでしょう。 このテキストは、あなたの変更が受け入れられる可能性を大きく高めるための 提案を集めたものです。
この文書には、比較的簡潔な形式で多数の提案が含まれています。 カーネル開発プロセスの仕組みに関する詳細は A guide to the Kernel Development Process を参照してください。 また、コードを投稿する前に確認すべき項目の一覧として Linux Kernel patch submission checklist を読んでください。 デバイスツリーバインディングのパッチについては、 Submitting Devicetree (DT) binding patches を読んでください。
この文書は、パッチ作成に git を使う前提で書かれています。
もし git に不慣れであれば、使い方を学ぶことを強く勧めます。
それにより、カーネル開発者として、また一般的にも、あなたの作業は
ずっと楽になるでしょう。
いくつかのサブシステムやメンテナツリーには、各々のワークフローや 期待事項に関する追加情報があります。次を参照してください: Subsystem and maintainer tree specific development process notes.
現在のソースツリーを入手する¶
もし手元に最新のカーネルソースのリポジトリがなければ、git を使って取得して
ください。まずは mainline のリポジトリから始めるのがよいでしょう。これは
次のようにして取得できます:
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
ただし、直接 mainline のツリーを対象に作業すればよいとは限らないことに注意 してください。多くのサブシステムのメンテナはそれぞれ独自のツリーを運用しており、 そのツリーに対して作成されたパッチを見たいと考えています。該当サブシステムの ツリーは MAINTAINERS ファイル内の T: エントリを参照して見つけてください。 そこに掲載されていない場合は、メンテナに問い合わせてください。
変更内容を記述する¶
問題を記述してください。あなたのパッチが 1 行のバグ修正であっても、 5000 行の新機能であっても、それを行う動機となった根本的な問題が 必ずあるはずです。修正すべき価値のある問題が存在し、レビューアが 最初の段落以降を読む意味があることを納得させてください。
ユーザーから見える影響を記述してください。クラッシュやロックアップは 分かりやすいですが、すべてのバグがそこまで露骨とは限りません。 たとえコードレビュー中に見つかった問題であっても、ユーザーに どのような影響があり得るかを記述してください。 Linux の多くの環境は、上流から特定のパッチだけを取り込む二次的な 安定版ツリーや、ベンダー／製品固有のツリーのカーネルで動いています。 したがって、変更を下流へ適切に流す助けになる情報（発生条件、dmesg の抜粋、クラッシュ内容、性能劣化、レイテンシのスパイク、 ロックアップ等）があれば記載してください。
最適化とトレードオフを定量的に示してください。パフォーマンス、 メモリ消費量、スタックフットプリント、バイナリサイズの改善を主張する 場合は、それを裏付ける数値を記載してください。 また、目に見えないコストについても記述してください。最適化は通常 無料ではなく、CPU・メモリ・可読性の間でのトレードオフになります。 ヒューリスティクスの場合は、異なるワークロード間でのトレードオフに なります。レビューアがコストとメリットを比較検討できるよう、 最適化によって予想されるデメリットも記述してください。
問題を明確にできたら、実際にどのような対策を講じているかを技術的に 詳しく記述してください。レビューアがコードが意図したとおりに動作して いるかを確認できるよう、変更内容を平易な言葉で書き下すことが重要です。
パッチ説明を Linux のソースコード管理システム git の
「コミットログ」としてそのまま取り込める形で書けば、メンテナは
助かります。詳細は原文の該当節を参照してください。
1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり 始めたら、パッチを分割すべきサインです。詳細は原文の該当節を参照 してください。
パッチまたはパッチシリーズを投稿／再投稿する際は、その完全な 説明と、それを正当化する理由を含めてください。単に、これが パッチ（シリーズ）のバージョン N であるとだけ書かないでください。 サブシステムメンテナが以前のパッチ版や参照先 URL をさかのぼって パッチ説明を探し、それをパッチに補うことを期待してはいけません。 つまり、パッチ（シリーズ）とその説明は、それだけで完結しているべき です。これはメンテナとレビューアの双方に有益です。レビューアの 中には、以前のパッチ版を受け取っていない人もいるでしょう。
変更内容は命令形で記述してください。たとえば、 「make xyzzy do frotz」とし、 「[This patch] makes xyzzy do frotz」や 「[I] changed xyzzy to do frotz」 のようには書かないでください。あたかもコードベースに対して、 その振る舞いを変えるよう命令しているかのように書いてください。
特定のコミットに言及したい場合は、コミットの SHA-1 ID だけを 書かないでください。レビューアがそれが何についてのものかを 把握しやすくなるよう、コミットの 1 行要約も含めてください。例:
Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary
platform_set_drvdata(), but left the variable "dev" unused,
delete it.
また、SHA-1 ID は少なくとも先頭 12 文字を使うようにしてください。 カーネルのリポジトリには非常に多くのオブジェクトがあるため、 それより短い ID では衝突が現実に起こり得ます。いま 6 文字の ID に 衝突がなくても、5 年後もそうだとは限らないことに注意してください。
変更に関連する議論や、その背景情報が Web 上で参照できる場合は、
それを指す Link: タグを追加してください。パッチが過去の
メーリングリストでの議論や、Web に記録された何かの結果であるなら、
それを示してください。
メーリングリストのアーカイブへリンクする場合は、できれば
lore.kernel.org のメッセージアーカイブサービスを使ってください。
リンク URL を作るには、そのメッセージの Message-ID ヘッダの内容
から、前後の山括弧を取り除いたものを使います。例:
Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI
実際にリンクが機能し、該当するメッセージを指していることを 確認してください。ただし、外部リソースを見なくても説明が理解できる ようにするよう努めてください。
メーリングリストのアーカイブやバグへの URL を示すだけでなく、 投稿されたパッチに至った議論の要点も要約してください。
パッチがバグを修正するものであれば、メーリングリストのアーカイブや
公開バグトラッカー上の報告を指す URL を付けて、Closes: タグを
使ってください。例:
Closes: https://example.com/issues/1234
このようなタグ付きのコミットが適用されたとき、自動的に issue を 閉じられるバグトラッカーもあります。メーリングリストを監視している ボットの中には、そのようなタグを追跡して一定の動作を行うものも あります。非公開のバグトラッカーや無効な URL は禁止です。
パッチが特定のコミットに含まれるバグを修正するものであれば、
たとえば git bisect で問題を見つけた場合には、SHA-1 ID の
先頭少なくとも 12 文字と 1 行要約を含めて、Fixes: タグを
使ってください。タグを複数行に分割してはいけません。タグは
解析スクリプトを単純にするため、「75 桁で折り返す」規則の
例外です。
例:
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
上の形式を git log や git show で出力しやすくするために、
次の git config 設定を使えます:
[core]
abbrev = 12
[pretty]
fixes = Fixes: %h ("%s")
呼び出し例:
$ git log -1 --pretty=fixes 54a4f0239f2e
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")