| 1 |
.. _jp_process_submitting_patches: |
| 2 |
|
| 3 |
パッチの投稿: カーネルにコードを入れるための必須ガイド |
| 4 |
====================================================== |
| 5 |
|
| 6 |
.. note:: |
| 7 |
|
| 8 |
このドキュメントは :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` の日本語訳です。 |
| 9 |
|
| 10 |
免責事項: :ref:`translations_ja_JP_disclaimer` |
| 11 |
|
| 12 |
.. warning:: |
| 13 |
|
| 14 |
**UNDER CONSTRUCTION!!** |
| 15 |
|
| 16 |
この文書は翻訳更新の作業中です。最新の内容は原文を参照してください。 |
| 17 |
|
| 18 |
Linux カーネルへ変更を投稿したい個人や企業にとって、もし「仕組み」に |
| 19 |
慣れていなければ、そのプロセスは時に気後れするものでしょう。 |
| 20 |
このテキストは、あなたの変更が受け入れられる可能性を大きく高めるための |
| 21 |
提案を集めたものです。 |
| 22 |
|
| 23 |
この文書には、比較的簡潔な形式で多数の提案が含まれています。 |
| 24 |
カーネル開発プロセスの仕組みに関する詳細は |
| 25 |
Documentation/process/development-process.rst を参照してください。 |
| 26 |
また、コードを投稿する前に確認すべき項目の一覧として |
| 27 |
Documentation/process/submit-checklist.rst を読んでください。 |
| 28 |
デバイスツリーバインディングのパッチについては、 |
| 29 |
Documentation/devicetree/bindings/submitting-patches.rst を読んでください。 |
| 30 |
|
| 31 |
この文書は、パッチ作成に ``git`` を使う前提で書かれています。 |
| 32 |
もし ``git`` に不慣れであれば、使い方を学ぶことを強く勧めます。 |
| 33 |
それにより、カーネル開発者として、また一般的にも、あなたの作業は |
| 34 |
ずっと楽になるでしょう。 |
| 35 |
|
| 36 |
いくつかのサブシステムやメンテナツリーには、各々のワークフローや |
| 37 |
期待事項に関する追加情報があります。次を参照してください: |
| 38 |
Documentation/process/maintainer-handbooks.rst. |
| 39 |
|
| 40 |
現在のソースツリーを入手する |
| 41 |
---------------------------- |
| 42 |
|
| 43 |
もし手元に最新のカーネルソースのリポジトリがなければ、``git`` を使って取得して |
| 44 |
ください。まずは mainline のリポジトリから始めるのがよいでしょう。これは |
| 45 |
次のようにして取得できます:: |
| 46 |
|
| 47 |
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git |
| 48 |
|
| 49 |
ただし、直接 mainline のツリーを対象に作業すればよいとは限らないことに注意 |
| 50 |
してください。多くのサブシステムのメンテナはそれぞれ独自のツリーを運用しており、 |
| 51 |
そのツリーに対して作成されたパッチを見たいと考えています。該当サブシステムの |
| 52 |
ツリーは MAINTAINERS ファイル内の **T:** エントリを参照して見つけてください。 |
| 53 |
そこに掲載されていない場合は、メンテナに問い合わせてください。 |
| 54 |
|
| 55 |
変更内容を記述する |
| 56 |
------------------ |
| 57 |
|
| 58 |
まず問題点を記べてください。あなたのパッチが 1 行のバグ修正であっても、 |
| 59 |
5000 行の新機能であっても、それを行う動機となった根本的な問題が |
| 60 |
必ずあるはずです。レビューアが、修正すべき問題がたしかに存在し、冒頭の |
| 61 |
段落の続きを読むべきだと納得できるように書いてください。 |
| 62 |
|
| 63 |
次にユーザーから見える影響を記述してください。クラッシュやロックアップは |
| 64 |
分かりやすいですが、すべてのバグがそこまで露骨とは限りません。 |
| 65 |
たとえコードレビュー中に見つかった問題であっても、ユーザーに |
| 66 |
どのような影響があり得るかを記述してください。 |
| 67 |
Linux の多くの環境は、上流から特定のパッチだけを取り込む二次的な |
| 68 |
安定版ツリーや、ベンダー/製品固有のツリーのカーネルで動いています。 |
| 69 |
したがって、変更を適切に下流へ流す助けになる情報(発生条件、dmesg |
| 70 |
の抜粋、クラッシュ内容、性能劣化、レイテンシのスパイク、 |
| 71 |
ロックアップ等)があれば記載してください。 |
| 72 |
|
| 73 |
次に最適化とトレードオフを定量的に示してください。パフォーマンス、 |
| 74 |
メモリ消費量、スタックフットプリント、バイナリサイズの改善を主張する |
| 75 |
場合は、それを裏付ける数値を記載してください。 |
| 76 |
また、目に見えないコストについても記述してください。多くの場合、 |
| 77 |
最適化は CPU・メモリ・可読性の間でのトレードオフとなります。 |
| 78 |
ヒューリスティクスの場合は、異なるワークロード間でのトレードオフと |
| 79 |
なります。レビューアがコストとメリットを比較検討できるよう、 |
| 80 |
最適化に伴って想定されるデメリットも記述してください。 |
| 81 |
|
| 82 |
問題点の明確化が済んだら、実際にどのような対策を講じているかを技術的に |
| 83 |
詳しく説明してください。コードが意図したとおりに動作していることを |
| 84 |
レビューアが確認できるよう、変更内容を平易な言葉で書き下すことが重要です。 |
| 85 |
|
| 86 |
パッチの説明が Linux のソースコード管理システム ``git`` の「コミットログ」 |
| 87 |
としてそのまま取り込める形で書かれていれば、メンテナは助かります。 |
| 88 |
詳細は原文の該当節 ("The canonical patch format") を参照してください。 |
| 89 |
|
| 90 |
.. TODO: Convert to file-local cross-reference when the destination is |
| 91 |
translated. |
| 92 |
|
| 93 |
1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり |
| 94 |
始めたら、それはパッチを分割すべきサインです。 |
| 95 |
詳細は原文の該当節 ("Separate your changes") を参照してください。 |
| 96 |
|
| 97 |
.. TODO: Convert to file-local cross-reference when the destination is |
| 98 |
translated. |
| 99 |
|
| 100 |
パッチまたはパッチシリーズを投稿/再投稿する際は、その完全な |
| 101 |
説明と、それを正当化する理由を含めてください。単に「これはパッチ |
| 102 |
(シリーズ)のバージョン N です」とだけ書くのは避けてください。 |
| 103 |
サブシステムメンテナが以前のパッチバージョンや参照先 URL をさかのぼって |
| 104 |
パッチ記述を探し、それをパッチに補うことを期待してはいけません。 |
| 105 |
つまり、パッチ(シリーズ)とその説明は、それだけで完結しているべき |
| 106 |
です。これはメンテナとレビューアの双方に有益です。レビューアの |
| 107 |
中には、以前のパッチバージョンを受け取っていない人もいるでしょう。 |
| 108 |
|
| 109 |
変更内容は、あたかもコードベースに対してその振る舞いを変えるように |
| 110 |
命令するかの如く、(訳補: 英語の)命令形で記述してください。たとえば、 |
| 111 |
"[This patch] makes xyzzy do frotz" や |
| 112 |
"[I] changed xyzzy to do frotz" のような言い回しを避け、 |
| 113 |
"make xyzzy do frotz" のように書いてください。 |
| 114 |
|
| 115 |
特定のコミットに言及したい場合に、コミットの SHA-1 ID だけを |
| 116 |
書くのは避けてください。レビューアがそれが何についてのものかを |
| 117 |
把握しやすいよう、コミットの 1 行要約も含めてください。例:: |
| 118 |
|
| 119 |
Commit e21d2170f36602ae2708 ("video: remove unnecessary |
| 120 |
platform_set_drvdata()") removed the unnecessary |
| 121 |
platform_set_drvdata(), but left the variable "dev" unused, |
| 122 |
delete it. |
| 123 |
|
| 124 |
また、SHA-1 ID は少なくとも先頭 12 文字を使うようにしてください。 |
| 125 |
カーネルのリポジトリには\ **非常に多くの**\ オブジェクトがあるため、 |
| 126 |
それより短い ID では衝突が現実問題となります。6 文字の ID が今現在 |
| 127 |
衝突しないからといって、5 年後もそうであるとは限らないことを念頭に |
| 128 |
置いてください。 |
| 129 |
|
| 130 |
変更に関連する議論や、その背景情報が Web 上で参照できる場合は、 |
| 131 |
それを指す 'Link:' タグを追加してください。過去のメーリングリスト |
| 132 |
での議論や、Web に記録された何かに由来するパッチならば、 |
| 133 |
それを示してください。 |
| 134 |
|
| 135 |
メーリングリストのアーカイブへリンクする場合は、できれば lore.kernel.org |
| 136 |
のメッセージアーカイブサービスを使ってください。リンク URL を作るには、 |
| 137 |
そのメッセージの ``Message-ID`` ヘッダの内容から、前後の山括弧を取り除いた |
| 138 |
ものを使います。例:: |
| 139 |
|
| 140 |
Link: https://lore.kernel.org/[email protected] |
| 141 |
|
| 142 |
実際にリンクが機能し、該当するメッセージを指していることを |
| 143 |
確認してください。 |
| 144 |
|
| 145 |
ただし、外部リソースを見なくても説明が理解できるようにするよう努めてください。 |
| 146 |
メーリングリストのアーカイブやバグへの URL を示すだけでなく、 |
| 147 |
投稿されたパッチに至った議論のポイントも要約してください。 |
| 148 |
|
| 149 |
パッチがバグを修正するものであれば、メーリングリストのアーカイブや |
| 150 |
公開バグトラッカー上の報告を指す URL を付けて、``Closes:`` タグを |
| 151 |
使ってください。例:: |
| 152 |
|
| 153 |
Closes: https://example.com/issues/1234 |
| 154 |
|
| 155 |
このようなタグ付きのコミットが適用されたとき、自動的に issue を |
| 156 |
閉じるバグトラッカーもあります。メーリングリストを監視している |
| 157 |
ボットの中には、そのようなタグを追跡して一定の動作を行うものも |
| 158 |
あります。ただし、非公開バグトラッカーの(訳補: 部外者が)閲覧できない |
| 159 |
URL は禁止です。 |
| 160 |
|
| 161 |
パッチが特定のコミットに含まれるバグを修正するもの、たとえば |
| 162 |
``git bisect`` で問題を見つけたものの場合には、SHA-1 ID の |
| 163 |
先頭少なくとも 12 文字と 1 行要約を含めて 'Fixes:' タグを |
| 164 |
使ってください。タグを複数行に分割してはいけません。タグは |
| 165 |
解析スクリプトを単純にするため、「75 桁で折り返す」規則の |
| 166 |
例外です。例:: |
| 167 |
|
| 168 |
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") |
| 169 |
|
| 170 |
``git log`` や ``git show`` の出力を上の形式で整形させるには、 |
| 171 |
次の ``git config`` 設定が使えます:: |
| 172 |
|
| 173 |
[core] |
| 174 |
abbrev = 12 |
| 175 |
[pretty] |
| 176 |
fixes = Fixes: %h ("%s") |
| 177 |
|
| 178 |
呼び出し例:: |
| 179 |
|
| 180 |
$ git log -1 --pretty=fixes 54a4f0239f2e |
| 181 |
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") |