.. _jp_process_submitting_patches: パッチの投稿: カーネルにコードを入れるための必須ガイド ====================================================== .. note:: このドキュメントは :ref:`Documentation/process/submitting-patches.rst ` の日本語訳です。 免責事項: :ref:`translations_ja_JP_disclaimer` .. warning:: **UNDER CONSTRUCTION!!** この文書は翻訳更新の作業中です。最新の内容は原文を参照してください。 Linux カーネルへ変更を投稿したい個人や企業にとって、もし「仕組み」に 慣れていなければ、そのプロセスは時に気後れするものでしょう。 このテキストは、あなたの変更が受け入れられる可能性を大きく高めるための 提案を集めたものです。 この文書には、比較的簡潔な形式で多数の提案が含まれています。 カーネル開発プロセスの仕組みに関する詳細は Documentation/process/development-process.rst を参照してください。 また、コードを投稿する前に確認すべき項目の一覧として Documentation/process/submit-checklist.rst を読んでください。 デバイスツリーバインディングのパッチについては、 Documentation/devicetree/bindings/submitting-patches.rst を読んでください。 この文書は、パッチ作成に ``git`` を使う前提で書かれています。 もし ``git`` に不慣れであれば、使い方を学ぶことを強く勧めます。 それにより、カーネル開発者として、また一般的にも、あなたの作業は ずっと楽になるでしょう。 いくつかのサブシステムやメンテナツリーには、各々のワークフローや 期待事項に関する追加情報があります。次を参照してください: Documentation/process/maintainer-handbooks.rst. 現在のソースツリーを入手する ---------------------------- もし手元に最新のカーネルソースのリポジトリがなければ、``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`` の「コミットログ」 としてそのまま取り込める形で書かれていれば、メンテナは助かります。 詳細は原文の該当節 ("The canonical patch format") を参照してください。 .. TODO: Convert to file-local cross-reference when the destination is translated. 1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり 始めたら、それはパッチを分割すべきサインです。 詳細は原文の該当節 ("Separate your changes") を参照してください。 .. TODO: Convert to file-local cross-reference when the destination is translated. パッチまたはパッチシリーズを投稿／再投稿する際は、その完全な 説明と、それを正当化する理由を含めてください。単に「これはパッチ （シリーズ）のバージョン N です」とだけ書くのは避けてください。 サブシステムメンテナが以前のパッチバージョンや参照先 URL をさかのぼって パッチ記述を探し、それをパッチに補うことを期待してはいけません。 つまり、パッチ（シリーズ）とその説明は、それだけで完結しているべき です。これはメンテナとレビューアの双方に有益です。レビューアの 中には、以前のパッチバージョンを受け取っていない人もいるでしょう。 変更内容は、あたかもコードベースに対してその振る舞いを変えるように 命令するかの如く、（訳補: 英語の）命令形で記述してください。たとえば、 "[This patch] makes xyzzy do frotz" や "[I] changed xyzzy to do frotz" のような言い回しを避け、 "make xyzzy 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")