Debian Codegraph @

Documentation/translations/ja_JP/process/submitting-patches.rst

raw
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")