1 NOTE:
2 This is a version of Documentation/process/sub
3 This document is maintained by Keiichi KII <k-k
4 and the JF Project team <http://www.linux.or.j
5 If you find any difference between this docume
6 or a problem with the translation,
7 please contact the maintainer of this file or
8
9 Please also note that the purpose of this file
10 for non English (read: Japanese) speakers and
11 fork. So if you have any comments or updates o
12 to update the original English file first.
13
14 Last Updated: 2011/06/09
15
16 ==================================
17 これは、
18 linux-2.6.39/Documentation/process/submitting-
19 です。
20 翻訳団体： JF プロジェクト < http:/
21 翻訳日： 2011/06/09
22 翻訳者： Keiichi Kii <k-keiichi at bx dot
23 校正者： Masanari Kobayashi さん <zap032
24 Matsukura さん <nbh--mats at nifty
25 Takeshi Hamasaki さん <hmatrjp at u
26 ==================================
27
28 Linux カーネルに変更を加え
29 又は
30 かの Linus Torvalds の取り扱い
31
32 Linux カーネルに変更を加えたいと
33 チの投稿に関連した仕組みに慣れ
34 おじけづかせることもあります。
35 てもらえやすくする提案を集めた
36
37 コードを投稿する前に、Documentation
38 を通してチェックしてください。
39
40 --------------------------------------------
41 セクション1 パッチの作り方と送
42 --------------------------------------------
43
44 1) 「 diff -up 」
45 ------------
46
47 パッチの作成には「 diff -up 」又は
48
49 Linux カーネルに対する全ての変更
50 生成してください。パッチを作成
51 数を指定して、unified 形式のパッ
52 変更がどの C 関数で行われたのか
53 この引数は生成した差分をずっと
54 カーネルソースの中のサブディレ
55 ディレクトリを基準にしないとい
56
57 1個のファイルについてのパッチを
58 以下の作業を行えば十分です。
59
60 SRCTREE=linux-2.6
61 MYFILE=drivers/net/mydriver.c
62
63 cd $SRCTREE
64 cp $MYFILE $MYFILE.orig
65 vi $MYFILE # make your change
66 cd ..
67 diff -up $SRCTREE/$MYFILE{.orig,} > /t
68
69 複数のファイルについてのパッチ
70 なわち変更を加えてない Linux カー
71 ソースとの差分を生成しないとい
72
73 MYSRC=/devel/linux-2.6
74
75 tar xvfz linux-2.6.12.tar.gz
76 mv linux-2.6.12 linux-2.6.12-vanilla
77 diff -uprN -X linux-2.6.12-vanilla/Doc
78 linux-2.6.12-vanilla $MYSRC >
79
80 dontdiff ファイルには Linux カーネル
81 ファイルの一覧がのっています。
82 コマンドで無視されるべきです。d
83 ンの Linux カーネルソースツリーに
84
85 投稿するパッチの中に関係のない
86 認してください。diff(1) コマンド
87 りのものであることを確認してく
88
89 もしあなたのパッチが多くの差分
90 を意味のあるひとまとまりごとに
91 これは他のカーネル開発者にとっ
92 パッチを受け入れてもらうために
93 る多くのスクリプトがあります。
94
95 Quilt:
96 http://savannah.nongnu.org/projects/quilt
97
98 2) パッチに対する説明
99
100 パッチの中の変更点に対する技術
101
102 説明はできる限り具体的に。もっ
103 「ドライバー X に対するバグフィ
104 テム X に対する更新を含んでいま
105
106 パッチの説明を Linux カーネルのソ
107 コミットログとして簡単に引用で
108 以下の #15 を見てください。
109
110 説明が長くなりだしたのであれば
111 という兆候です。次の #3 を見てく
112
113 パッチ(シリーズ)を(再)投稿する時
114 パッチに含めてください。ただ「
115 書かないでください。そして、パ
116 パッチに追記させるため、過去の
117 手間をかけさせないでください。
118 つまり、パッチシリーズとその説
119 人、レビューする人、どちらのた
120 過去のバージョンのパッチを受け
121
122 登録済みのバグエントリを修正す
123 や URL を明記してください。
124
125 特定のコミットを参照したい場合
126 も含めてください。それにより、
127 人にわかりやすくなります。
128 例 (英文のママ):
129
130 Commit e21d2170f36602ae2708 ("video: re
131 platform_set_drvdata()") removed the un
132 platform_set_drvdata(), but left the va
133 delete it.
134
135
136 3) パッチの分割
137
138 意味のあるひとまとまりごとに変
139
140 例えば、もし1つのドライバーに対
141 化の両方の変更を含んでいるので
142 けてください。もし変更箇所に API
143 ドライバーが含まれているなら、2
144
145 一方で、もしあなたが多数のファ
146 るのであれば、その変更を1つのパ
147 意味的に同じ1つの変更は1つのパ
148
149 あるパッチが変更を完結させるた
150 それは問題ありません。パッチの
151 している」と簡単に注意書きをつ
152
153 もしパッチをより小さなパッチの
154 15かそこらのパッチを送り、その
155
156 4) パッチのスタイルチェック
157
158 あなたのパッチが基本的な( Linux
159 ていないかをチェックして下さい
160 見つけることができます。コーデ
161 時間を無駄にするだけなので、恐
162 拒否されるでしょう。
163
164 あなたはパッチを投稿する前に最
165 ( scripts/checkpatch.pl )を利用してパッ
166 もしパッチに違反がのこっている
167 理由を示せるようにしておく必要
168
169 5) 電子メールの宛先の選び方
170
171 MAINTAINERS ファイルとソースコード
172 更がメンテナのいる特定のサブシ
173 れば、その人に電子メールを送っ
174 ./scripts/get_maintainers.pl のスクリプ
175
176 もし、メンテナが載っていなかっ
177 LKML ( linux-kernel@vger.kernel.org )へパッ
178 のカーネル開発者はこのメーリン
179 コメントを得ることができます。
180
181 15個より多くのパッチを同時に vger
182 いでください!!!
183
184 Linus Torvalds は Linux カーネルに入る
185 です。電子メールアドレスは torval
186 多くの電子メールを受け取ってい
187 避けるべきです。
188
189 バグフィックスであったり、自明
190 必要としないパッチは Linus へ電子
191 話し合いを必要としたり、明確な
192 は LKML へ送られるべきです。パッ
193 Linus へ送るべきです。
194
195 6) CC (カーボンコピー)先の選び方
196
197 特に理由がないなら、LKML にも CC
198
199 Linus 以外のカーネル開発者は変更
200 の変更に対してコメントをくれた
201 るかもしれません。LKML とは Linux
202 リングリストです。USB やフレーム
203 ムなどの特定のサブシステムに関
204 の変更に、はっきりと関連のある
205 MAINTAINERS ファイルを参照してくだ
206
207 VGER.KERNEL.ORG でホスティングされて
208 サイトに載っています。
209 <http://vger.kernel.org/vger-lists.html>
210
211 もし、変更がユーザランドのカー
212 るのであれば、MAN-PAGES のメンテナ
213 があります)に man ページのパッチ
214 情報がマニュアルページの中に入
215 通知を送ってください。
216
217 たとえ、メンテナが #5 で反応がな
218 加えたときには、いつもメンテナ
219
220
221 7) MIME やリンクや圧縮ファイルや
222
223 Linus や他のカーネル開発者はあな
224 る必要があります。カーネル開発
225 部分にコメントをするために、標
226 できることは重要です。
227
228 上記の理由で、すべてのパッチは
229 れるべきです。警告：あなたがパ
230 チを改悪するエディターの折り返
231
232 パッチを圧縮の有無に関わらず MIM
233 ピュラーな電子メールクライアン
234 キストとして送信するとは限らな
235 イアントがコードに対するコメン
236 MIME 形式の添付ファイルは Linus に
237 受け入れてもらう可能性が低くな
238
239 例外：お使いの電子メールクライ
240 あれば、誰かが MIME 形式のパッチ
241
242 余計な変更を加えずにあなたのパ
243 のヒントについては Documentation/proc
244
245 8) 電子メールのサイズ
246
247 パッチを Linus へ送るときは常に #7
248
249 大きなパッチはメーリングリスト
250 未圧縮で 300KB を超えるようである
251 サーバに保存し、保存場所を示す
252
253 9) カーネルバージョンの明記
254
255 パッチが対象とするカーネルのバ
256 サブジェクトに付けることが重要
257
258 パッチが最新バージョンのカーネ
259 そのパッチを採用しないでしょう
260
261 10) がっかりせず再投稿
262
263 パッチを投稿した後は、辛抱強く
264 チを気に入って採用すれば、Linus
265 の中で姿を見せるでしょう。
266
267 しかし、パッチが次のバージョン
268 理由があるのでしょう。その原因
269 したパッチを投稿するのはあなた
270
271 Linus があなたのパッチに対して何
272 て普通のことです。それは自然な
273 け取っていないのであれば、以下
274 * パッチが最新バージョンの Linux
275 * パッチが LKML で十分に議論され
276 * スタイルの問題(セクション2を参
277 * 電子メールフォーマットの問題(
278 * パッチに対する技術的な問題
279 * Linus はたくさんの電子メールを
280 失った
281 * 不愉快にさせている
282
283 判断できない場合は、LKML にコメ
284
285 11) サブジェクトに「 PATCH 」
286
287 Linus や LKML への大量の電子メール
288 「 [PATCH] 」を付けることが慣習と
289 カーネル開発者がパッチであるの
290 かをより簡単に識別できます。
291
292 12) パッチへの署名
293
294 誰が何をしたのかを追いかけやす
295 メンテナを経て最終的に Linux カー
296 メールでやり取りされるパッチに
297 ました。
298
299 「 sign-off 」とは、パッチがあなた
300 あなたがそのパッチをオープンソ
301 という証明をパッチの説明の末尾
302 ルールはとても単純です。以下の
303
304 原作者の証明書( DCO ) 1.1
305
306 このプロジェクトに寄与す
307
308 (a) 本寄与は私が全体又は一
309 ル中に明示されたオープ
310 を持っている。もしくは
311
312 (b) 本寄与は、私が知る限り
313 ーされている既存の作品
314 ンスの下で、私が全体又
315 される同一のオープンソ
316 投稿することが許可され
317 いる。もしくは、
318
319 (c) 本寄与は(a)、(b)、(c)を証
320 ものであり、私はそれに
321
322 (d) 私はこのプロジェクトと
323 る。同時に、関与した記
324 含む)が無期限に保全され
325 オープンソースライセン
326 同意する。
327
328 もしこれに同意できるなら、以下
329
330 Signed-off-by: Random J Developer <rand
331
332 実名を使ってください。(残念です
333
334 人によっては sign-off の近くに追加
335 無視されますが、あなたはそのタ
336 な情報を示したりすることができ
337
338 あなたがサブシステムまたはブラ
339 ツリーにマージするために、わず
340 あなたのツリーの中のコードと投
341 もし、あなたが厳密に上記ルール(
342 とるよう依頼すべきです。しかし
343 ことになります。ルール(b)はあな
344 しかし、投稿者のコードを修正し
345 ことはとても失礼なことです。こ
346 Signed-off-by とあなたがその末尾に
347 加えたことを示す1行を追加するこ
348 (その1行の書き方に)決まりはあり
349 と修正内容を記載するやり方は目
350 あることを明確にするのに十分な
351
352 Signed-off-by: Random J Developer <rand
353 [lucky@maintainer.example.org: struct
354 Signed-off-by: Lucky K Maintainer <luck
355
356 あなたが安定版のブランチを管理
357 修正のマージ、と同時に苦情から
358 有用となります。いかなる事情が
359 アイデンティティ情報(From ヘッダ)
360
361 バックポートする人のための特別
362 メッセージのトップ(サブジェクト
363 ことは一般的で有用な慣習です。
364
365 Date: Tue May 13 19:10:30 2008 +0000
366
367 SCSI: libiscsi regression in 2.6.25: f
368
369 commit 4cf1043593db6a337f10e006c23c69e
370
371 そして、これは 2.4 ツリーでの一
372
373 Date: Tue May 13 22:12:27 2008 +0200
374
375 wireless, airo: waitbusy() won't delay
376
377 [backport of 2.6 commit b7acbdfbd1f277
378
379 どんな形式であれ、この情報はあ
380 解決しようとしている人にとって
381
382 13) いつ Acked-by: と Cc: を使うのか
383
384 「 Signed-off-by: 」タグはその署名者
385 の伝播パスにいたことを示してい
386
387 ある人が直接パッチの準備や作成
388 る承認を記録し、示したいとしま
389 えます。Acked-by: はパッチのチェン
390
391 パッチの影響を受けるコードのメ
392 の伝播パスにいなかった時にも、
393
394 Acked-by: は Signed-off-by: のように公
395 少なくともパッチをレビューし、
396 ことからパッチをマージする人が
397 Acked-by: へ置き換えることがありま
398
399 Acked-by: が必ずしもパッチ全体の承
400 あるパッチが複数のサブシステム
401 のメンテナからの Acked-by: を持っ
402 そのメンテナのコードに影響を与
403 この点は、ご自分で判断してくだ
404 メーリングリストアーカイブの中
405
406 パッチにコメントする機会を持っ
407 その人を指す「Cc:」タグを任意で
408 明確なアクションなしに付与でき
409 このタグはパッチに関心があると
410 を明文化します。
411
412 14) Reported-by:, Tested-by:, Reviewed-by: お
413
414 他の誰かによって報告された問題
415 クレジットするために、Reported-by:
416 こまめにバグ報告者をクレジット
417 コミュニティの力となってくれる
418 ただし、報告者の許可無くこのタ
419 問題が公の場で報告されていなか
420
421 Tested-by: タグはタグで指定された
422 していることを示します。このタ
423 知らせ、将来の関連パッチのテス
424 対するクレジットを保証します。
425
426 Reviewed-by: タグは、それとは異なり
427 受け入れ可能とみなされたパッチ
428
429 レビューアによる監督宣言
430
431 私は Reviewed-by: タグを提示す
432
433 (a) 私はメインラインカーネ
434 (訳注)」を検証し、技術
435
436 訳注:
437 「即応性」の原文は "readiness
438 パッチが十分な品質を持っ
439 行うことができる状態であ
440 している。
441
442 (b) パッチに関するあらゆる
443 である。私はそれらのコ
444
445 (c) 投稿に伴い改良されるコ
446 カーネルにとって価値の
447 議論になり得るような問
448
449 (d) 私はパッチをレビューし
450 状況においてその宣言し
451 いかなる保証もしない(特
452
453 Reviewed-by タグはそのパッチがカー
454 問題を残していないという意見の
455 作業を終えたら)パッチに対して Re
456 レビューアの寄与をクレジットす
457 知らせる働きを持ちます。そのパ
458 レビューを実施したレビューアに
459 パッチをカーネルにマージする可
460
461 Suggested-by: タグは、パッチのアイ
462 ことを示し、アイデアの提供をク
463 ない場合、特にそのアイデアが公
464 タグをつけないように注意してく
465 クレジットしていけば、望むらく
466 なってくれるかもしれません。
467
468 15) 標準的なパッチのフォーマット
469
470 標準的なパッチのサブジェクトは
471
472 Subject: [PATCH 001/123] subsystem: summar
473
474 標準的なパッチの、電子メールの
475
476 - パッチの作成者を明記する「 fr
477
478 - 空行
479
480 - 説明本体。これはこのパッチを
481 (変更履歴)にコピーされます。
482
483 - 上述した「 Signed-off-by: 」行。
484 ジログ内にコピーされます。
485
486 - マーカー行は単純に「 --- 」で
487
488 - 余計なコメントは、チェンジロ
489
490 - 実際のパッチ(差分出力)
491
492 サブジェクト行のフォーマットは
493 ソートしやすいものになっていま
494 はソートをサポートしています)パ
495 るため、数字でのソートとアルフ
496
497 電子メールのサブジェクト内のサ
498 分野またはサブシステムを識別で
499
500 電子メールのサブジェクトの「summ
501 に表現しなければなりません。「s
502 けません。パッチシリーズ中でそ
503 使ってはいけません(「パッチシリ
504 パッチ群です)。
505
506 あなたの電子メールの「summary phras
507 なるように心がけてください。「s
508 ずっと伝播していきます。「summary
509 ために議論の中で利用するかもし
510 人々はそのパッチに関連した議論
511 検索したがるでしょう。それはま
512 「git log --oneline」のようなツール
513 唯一目にとまる情報となるでしょ
514
515 これらの理由のため、「summary phras
516 変更するかの2つの情報をせいぜい
517 「summary phrase」は簡潔であり説明
518 まとめられている概要となるべき
519
520 「summary phrase」は「Subject: [PATCH tag]
521 大括弧で閉じられたタグを接頭辞
522 「summary phrase」の一部とは考えま
523 表現します。
524 一般的には「v1, v2, v3」のようなバ
525 コメントを反映するために複数の
526 「RFC」のようなコメントを要求す
527 パッチがあれば、個々のパッチに
528 かまいません。これは開発者がパ
529 そして、開発者がパッチシリーズ
530 適用するのを保証するためです。
531
532 サブジェクトの例を二つ
533
534 Subject: [patch 2/5] ext2: improve scalabi
535 Subject: [PATCHv2 001/207] x86: fix eflags
536
537 「 from 」行は電子メールのボディ
538 その形式は以下のとおりです。
539
540 From: Original Author <author@example.c
541
542 「 from 」行はチェンジログの中で
543 ている人を特定するものです。「
544 ダーの「 From: 」が、チェンジログ
545 れるでしょう。
546
547 説明本体は無期限のソースのチェ
548 本体はそのパッチに至った議論の
549 がその詳細を思い出すことができ
550 障害の症状(カーネルログメッセー
551 対処可能なパッチを求めてコミッ
552 パッチがコンパイル問題を解決す
553 ことができる情報だけで十分であ
554 ありません。「summary phrase」と同
555
556 「 --- 」マーカー行はパッチ処理
557 部分を認識させるという重要な役
558
559 「 --- 」マーカー行の後の追加コ
560 があります。diffstat コマンドとは
561 追加され何行消されたかを示すも
562 おいて役立ちます。その時点でだ
563 は無期限に保存されるチェンジロ
564 ようなコメントもマーカー行の後
565 このようなコメントの良い例とし
566 表す「パッチの変更履歴」が挙げ
567
568 「 --- 」マーカー行の後に diffstat
569 名はカーネルソースツリーのトッ
570 のスペースをとり過ぎないように
571 を指定してください(インデントを
572
573 適切なパッチのフォーマットの詳
574 ください。
575
576 16) 「git pull」要求の送り方(Linus の
577
578 間違ったブランチから引っ張るの
579 ブランチ名を同じ行に1行で記載し
580 で全て選択できます。
581
582 正しい形式は下記の通りです。
583
584 "Please pull from
585
586 git://jdelvare.pck.nerim.net/j
587
588 to get these changes:"
589
590 その結果、アドレスを自分自身で
591 何度か間違ったブランチから引っ
592 検証して間違っていることに気づ
593 「探したり」、正しいブランチ名
594 なくなればより快適になるでしょ
595
596 diffstat の結果を生成するために「
597 ください。-M オプションはファイ
598 新規ファイル、削除されたファイ
599
600 -M オプション(ファイル名の変更検
601 異なってきます。git は大規模な変
602 判断するためです。
603
604 ------------------------------------
605 セクション2 - ヒントとTIPSと小技
606 ------------------------------------
607
608 このセクションは Linux カーネルに
609 「お約束」の多くを載せています
610 し例外を適用するには、本当に妥
611 セクションを Linus のコンピュータ
612
613 1) Documentation/process/coding-style.rstを
614
615 言うまでもなく、あなたのコード
616 も逸脱していると、レビューやコ
617 れません。
618
619 特筆すべき例外は、コードをある
620 するときです。この場合、コード
621 に関して移動以外の変更を一切加
622 コードの移動とあなたが行ったコ
623 ります。これは実際に何が変更さ
624 なるとともに、ツールにコードの
625
626 投稿するより前にパッチのスタイ
627 あなたのパッチをチェックしてく
628 論としてではなく、指標としてみ
629 はしているが修正するより良く見
630 のがベストです。
631
632 スタイルチェッカーによる3段階の
633 - エラー: 間違っている可能性が
634 - 警告：注意してレビューする必
635 - チェック：考慮する必要がある
636
637 あなたはパッチに残っている全て
638 理由を示せるようにしておく必要
639
640 2) #ifdefは見苦しい
641
642 ifdef が散乱したコードは、読むの
643 で ifdef を使わないでください。代
644 条件付きで、コードの中で使われ
645 てください。後はコンパイラが、
646 しょう。
647
648 まずいコードの簡単な例
649
650 dev = alloc_etherdev (sizeof(struct fu
651 if (!dev)
652 return -ENODEV;
653 #ifdef CONFIG_NET_FUNKINESS
654 init_funky_net(dev);
655 #endif
656
657 クリーンアップしたコードの例
658
659 (in header)
660 #ifndef CONFIG_NET_FUNKINESS
661 static inline void init_funky_net (str
662 #endif
663
664 (in the code itself)
665 dev = alloc_etherdev (sizeof(struct fu
666 if (!dev)
667 return -ENODEV;
668 init_funky_net(dev);
669
670 3) マクロより「 static inline 」を推
671
672 「 static inline 」関数はマクロより
673 型安全性があり、長さにも制限が
674 gcc においては、マクロと同じくら
675
676 マクロは「 static inline 」が明らか
677 いくつかの特定のケース)や「 stati
678 場所(マクロの引数の文字列連結の
679
680 「 static inline 」は「 static __inline__
681 「 extern __inline__ 」よりも適切です
682
683 4) 設計に凝りすぎるな
684
685 それが有用になるかどうか分から
686 をしないでください。「できる限
687 ないような設計をしてください。
688
689 ----------------------
690 セクション3 参考文献
691 ----------------------
692
693 Andrew Morton, "The perfect patch" (tpp).
694 <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
695
696 Jeff Garzik, "Linux kernel patch submission fo
697 <https://web.archive.org/web/20180829112450/
698
699 Greg Kroah-Hartman, "How to piss off a kernel
700 <http://www.kroah.com/log/linux/maintainer.h
701 <http://www.kroah.com/log/linux/maintainer-0
702 <http://www.kroah.com/log/linux/maintainer-0
703 <http://www.kroah.com/log/linux/maintainer-0
704 <http://www.kroah.com/log/linux/maintainer-0
705
706 NO!!!! No more huge patch bombs to linux-kerne
707 <https://lore.kernel.org/r/20050711.125305.08
708
709 Kernel Documentation/process/coding-style.rst:
710 <http://users.sosdg.org/~qiyong/lxr/source/D
711
712 Linus Torvalds's mail on the canonical patch f
713 <https://lore.kernel.org/r/Pine.LNX.4.58.0504
714
715 Andi Kleen, "On submitting kernel patches"
716 Some strategies to get difficult or controve
717 http://halobates.de/on-submitting-patches.pd
718
719 --
720
721
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.