Pull netlink into release branch
[linux-2.6] / Documentation / ja_JP / HOWTO
1 NOTE:
2 This is Japanese translated version of "Documentation/HOWTO".
3 This one is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
4 and JF Project team <www.linux.or.jp/JF>.
5 If you find difference with original file or problem in translation,
6 please contact maintainer of this file or JF project.
7
8 Please also note that purpose of this file is easier to read for non
9 English natives and not to be intended to fork. So, if you have any
10 comments or updates of this file, please try to update Original(English)
11 file at first.
12
13 Last Updated: 2007/06/04
14 ==================================
15 これは、
16 linux-2.6.21/Documentation/HOWTO
17 の和訳です。
18
19 翻訳団体: JF プロジェクト < http://www.linux.or.jp/JF/ >
20 翻訳日: 2007/06/04
21 翻訳者: Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com>
22 校正者: 松倉さん <nbh--mats at nifty dot com>
23          小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp>
24          武井伸光さん、<takei at webmasters dot gr dot jp>
25          かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp>
26          野口さん (Kenji Noguchi) <tokyo246 at gmail dot com>
27          河内さん (Takayoshi Kochi) <t-kochi at bq dot jp dot nec dot com>
28          岩本さん (iwamoto) <iwamoto.kn at ncos dot nec dot co dot jp>
29 ==================================
30
31 Linux カーネル開発のやり方
32 -------------------------------
33
34 これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した
35 ドキュメントです。ここには Linux カーネル開発者になるための方法と
36 Linux カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれて
37 います。カーネルプログラミングに関する技術的な項目に関することは何も含
38 めないようにしていますが、カーネル開発者となるための正しい方向に向かう
39 手助けになります。
40
41 もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン
42 トの最後にリストしたメンテナーにパッチを送ってください。
43
44 はじめに
45 ---------
46
47 あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか? そ
48 れともあなたは上司から「このデバイスの Linux ドライバを書くように」と
49 言われているのでしょうか? 
50 この文書の目的は、あなたが踏むべき手順と、コミュニティと一緒にうまく働
51 くヒントを書き下すことで、あなたが知るべき全てのことを教えることです。
52 また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も
53 説明しようと試みています。
54
55 カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている
56 以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー
57 ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの
58 でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり
59 ません。以下の本は、C 言語の十分な知識や何年もの経験に取って代わるもの
60 ではありませんが、少なくともリファレンスとしてはいい本です。
61  - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
62  -『プログラミング言語C第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
63  - "Practical C Programming" by Steve Oualline [O'Reilly]
64  - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン]
65  - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
66  - 『新・詳説 C 言語 H&S リファレンス』
67        (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]
68
69 カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル
70 は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って
71 います。カーネルは標準 C ライブラリとは関係がないといった、C 言語フリー
72 スタンディング環境です。そのため、C の標準で使えないものもあります。任
73 意の long long の除算や浮動小数点は使えません。
74 ときどき、カーネルがツールチェインや C 言語拡張に置いている前提がどう
75 なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ
76 レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を
77 みてください。
78
79 あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ
80 とに留意してください。そのコミュニティは、コーディング、スタイル、
81 開発手順について高度な標準を持つ、多様な人の集まりです。
82 地理的に分散した大規模なチームに対してもっともうまくいくとわかったこと
83 をベースにしながら、これらの標準は長い時間をかけて築かれてきました。
84 これらはきちんと文書化されていますから、事前にこれらの標準についてでき
85 るだけたくさん学んでください。また皆があなたやあなたの会社のやり方に合わ
86 せてくれると思わないでください。
87
88 法的問題
89 ------------
90
91 Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま
92 す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在
93 する、COPYING のファイルをみてください。もしライセンスについてさらに質
94 問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ
95 法律家に相談してください。メーリングリストの人達は法律家ではなく、法的
96 問題については彼らの声明はあてにするべきではありません。
97
98 GPL に関する共通の質問や回答については、以下を参照してください。
99         http://www.gnu.org/licenses/gpl-faq.html
100
101 ドキュメント
102 ------------
103
104 Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ
105 らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。
106 新しい機能がカーネルに追加される場合、その機能の使い方について説明した
107 新しいドキュメントファイルも追加することを勧めます。
108 カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
109 変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
110 をマニュアルページのメンテナ mtk-manpages@gmx.net に送ることを勧めます。
111
112 以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で
113 す-
114
115   README
116     このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注
117     configure )し、生成(訳注 build )するために必要なことは何かが書かれ
118     ています。カーネルに関して初めての人はここからスタートするとよいで
119     しょう。
120
121   Documentation/Changes
122      このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
123      小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
124      ます。
125
126   Documentation/CodingStyle
127     これは Linux カーネルのコーディングスタイルと背景にある理由を記述
128     しています。全ての新しいコードはこのドキュメントにあるガイドライン
129     に従っていることを期待されています。大部分のメンテナーはこれらのルー
130     ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
131     だけをレビューします。
132
133   Documentation/SubmittingPatches
134   Documentation/SubmittingDrivers
135      これらのファイルには、どうやってうまくパッチを作って投稿するかに
136      ついて非常に詳しく書かれており、以下を含みます(これだけに限らない
137      けれども)
138         - Email に含むこと
139         - Email の形式
140         - だれに送るか
141      これらのルールに従えばうまくいくことを保証することではありません
142      が (すべてのパッチは内容とスタイルについて精査を受けるので)、
143      ルールに従わなければ間違いなくうまくいかないでしょう。
144      この他にパッチを作る方法についてのよくできた記述は-
145
146         "The Perfect Patch"
147                 http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
148         "Linux kernel patch submission format"
149                 http://linux.yyz.us/patch-format.html
150
151   Documentation/stable_api_nonsense.txt
152      このファイルはカーネルの中に不変のAPIを持たないことにした意識的な
153      決断の背景にある理由について書かれています。以下のようなことを含
154      んでいます-
155        - サブシステムとの間に層を作ること(コンパチビリティのため?)
156        - オペレーティングシステム間のドライバの移植性
157        - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更
158          を妨げる)
159      このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
160      そして、他のOSでの開発者が Linux に移る時にとても重要です。
161
162   Documentation/SecurityBugs
163     もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
164     のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
165     支援してください。
166
167   Documentation/ManagementStyle
168     このドキュメントは Linux カーネルのメンテナー達がどう行動するか、
169     彼らの手法の背景にある共有されている精神について記述しています。こ
170     れはカーネル開発の初心者なら(もしくは、単に興味があるだけの人でも)
171     重要です。なぜならこのドキュメントは、カーネルメンテナー達の独特な
172     行動についての多くの誤解や混乱を解消するからです。
173
174   Documentation/stable_kernel_rules.txt
175     このファイルはどのように stable カーネルのリリースが行われるかのルー
176     ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
177     り入れてもらいたい場合に何をすればいいかが示されています。
178
179   Documentation/kernel-docs.txt
180   カーネル開発に付随する外部ドキュメントのリストです。もしあなたが
181     探しているものがカーネル内のドキュメントでみつからなかった場合、
182     このリストをあたってみてください。
183
184   Documentation/applying-patches.txt
185     パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
186     適用するのかについて正確に記述した良い入門書です。
187
188 カーネルはソースコードから自動的に生成可能な多数のドキュメントを自分自
189 身でもっています。これにはカーネル内 API のすべての記述や、どう正しく
190 ロックをかけるかの規則が含まれます。このドキュメントは
191 Documentation/DocBook/ ディレクトリに作られ、以下のように
192         make pdfdocs
193         make psdocs
194         make htmldocs
195         make mandocs
196 コマンドを実行するとメインカーネルのソースディレクトリから
197 それぞれ、PDF, Postscript, HTML, man page の形式で生成されます。
198
199 カーネル開発者になるには
200 ---------------------------
201
202 もしあなたが、Linux カーネル開発について何も知らないならば、
203 KernelNewbies プロジェクトを見るべきです
204         http://kernelnewbies.org
205
206 このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関
207 するほとんどどんな種類の質問もできます (既に回答されているようなことを
208 聞く前にまずはアーカイブを調べてください)。
209 またここには、リアルタイムで質問を聞くことができる IRC チャネルや、Linux
210 カーネルの開発に関して学ぶのに便利なたくさんの役に立つドキュメントがあ
211 ります。
212
213 web サイトには、コードの構成、サブシステム、現在存在するプロジェクト(ツ
214 リーにあるもの無いものの両方)の基本的な管理情報があります。
215 ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接
216 的な基本情報も記述されています。
217
218 あなたがどこからスタートしてよいかわからないが、Linux カーネル開発コミュ
219 ニティに参加して何かすることをさがしている場合には、Linux kernel
220 Janitor's プロジェクトにいけばよいでしょう -
221         http://janitor.kernelnewbies.org/
222 ここはそのようなスタートをするのにうってつけの場所です。ここには、
223 Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな
224 らない、単純な問題のリストが記述されています。このプロジェクトに関わる
225 開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入
226 れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ
227 ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。
228
229 もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入
230 れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネル
231 メンターズプロジェクトはそのような皆さんを助けるためにできました。
232 ここにはメーリングリストがあり、以下から参照できます
233         http://selenic.com/mailman/listinfo/kernel-mentors
234
235 実際に Linux カーネルのコードについて修正を加える前に、どうやってその
236 コードが動作するのかを理解することが必要です。そのためには、特別なツー
237 ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど
238 のトリッキーな部分は十分にコメントしてありますから)。そういうツールで
239 特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、
240 自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
241 できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
242 ます-
243         http://sosdg.org/~coywolf/lxr/
244
245 開発プロセス
246 -----------------------
247
248 Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン
249 チ」と多数のサブシステム毎のカーネルブランチから構成されます。
250 これらのブランチとは-
251   - メインの 2.6.x カーネルツリー
252   - 2.6.x.y -stable カーネルツリー
253   - 2.6.x -git カーネルパッチ
254   - 2.6.x -mm カーネルパッチ
255   - サブシステム毎のカーネルツリーとパッチ
256
257 2.6.x カーネルツリー
258 -----------------
259
260 2.6.x カーネルは Linus Torvalds によってメンテナンスされ、kernel.org
261 の pub/linux/kernel/v2.6/ ディレクトリに存在します。この開発プロセスは
262 以下のとおり-
263
264   - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、
265     この期間中に、メンテナー達は Linus に大きな差分を送ることができま
266     す。このような差分は通常 -mm カーネルに数週間含まれてきたパッチで
267     す。 大きな変更は git(カーネルのソース管理ツール、詳細は
268     http://git.or.cz/  参照) を使って送るのが好ましいやり方ですが、パッ
269     チファイルの形式のまま送るのでも十分です。
270
271   - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定
272     性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと
273     はできません。新しいドライバ(もしくはファイルシステム)のパッチは
274     -rc1 の後で受け付けられることもあることを覚えておいてください。な
275     ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え
276     ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、
277     Linus へパッチを送付するのに git を使うこともできますが、パッチは
278     レビューのために、パブリックなメーリングリストへも同時に送る必要が
279     あります。
280
281   - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分
282     に安定した状態にあると判断したときにリリースされます。目標は毎週新
283     しい -rc カーネルをリリースすることです。
284
285   - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま
286     す。このプロセスはだいたい 6週間継続します。
287
288 Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ
289 て書いたことをここで言っておくことは価値があります-
290   「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現
291   実に認識されたバグの状況によりリリースされるのであり、前もって決めら
292   れた計画によってリリースされるものではないからです。」
293
294 2.6.x.y -stable カーネルツリー
295 ---------------------------
296
297 バージョンに4つ目の数字がついたカーネルは -stable カーネルです。これに
298 は、2.6.x カーネルで見つかったセキュリティ問題や重大な後戻りに対する比
299 較的小さい重要な修正が含まれます。
300
301 これは、開発/実験的バージョンのテストに協力することに興味が無く、
302 最新の安定したカーネルを使いたいユーザに推奨するブランチです。
303
304 もし、2.6.x.y カーネルが存在しない場合には、番号が一番大きい 2.6.x
305 が最新の安定版カーネルです。
306
307 2.6.x.y は "stable" チーム <stable@kernel.org> でメンテされており、だ
308 いたい隔週でリリースされています。
309
310 カーネルツリーに入っている、Documentation/stable_kernel_rules.txt ファ
311 イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ
312 リースプロセスがどう動くかが記述されています。
313
314 2.6.x -git パッチ
315 ------------------
316
317 git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ
318 ショットがあります。(だから -git という名前がついています)。これらのパッ
319 チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ
320 れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的
321 に生成されるので、より実験的です。
322
323 2.6.x -mm カーネルパッチ
324 ------------------------
325
326 Andrew Morton によってリリースされる実験的なカーネルパッチ群です。
327 Andrew は個別のサブシステムカーネルツリーとパッチを全て集めてきて
328 linux-kernel メーリングリストで収集された多数のパッチと同時に一つにま
329 とめます。
330 このツリーは新機能とパッチが検証される場となります。ある期間の間パッチ
331 が -mm に入って価値を証明されたら、Andrew やサブシステムメンテナが、メ
332 インラインへ入れるように Linus にプッシュします。
333
334 メインカーネルツリーに含めるために Linus に送る前に、すべての新しいパッ
335 チが -mm ツリーでテストされることが強く推奨されます。
336
337 これらのカーネルは安定して動作すべきシステムとして使うのには適切ではあ
338 りませんし、カーネルブランチの中でももっとも動作にリスクが高いものです。
339
340 もしあなたが、カーネル開発プロセスの支援をしたいと思っているのであれば、
341 どうぞこれらのカーネルリリースをテストに使ってみて、そしてもし問題があ
342 れば、またもし全てが正しく動作したとしても、linux-kernel メーリングリ
343 ストにフィードバックを提供してください。
344
345 すべての他の実験的パッチに加えて、これらのカーネルは通常リリース時点で
346 メインラインの -git カーネルに含まれる全ての変更も含んでいます。
347
348 -mm カーネルは決まったスケジュールではリリースされません、しかし通常幾
349 つかの -mm カーネル (1 から 3 が普通)が各-rc カーネルの間にリリースさ
350 れます。
351
352 サブシステム毎のカーネルツリーとパッチ
353 -------------------------------------------
354
355 カーネルの様々な領域で何が起きているかを見られるようにするため、多くの
356 カーネルサブシステム開発者は彼らの開発ツリーを公開しています。これらの
357 ツリーは説明したように -mm カーネルリリースに入れ込まれます。
358
359 以下はさまざまなカーネルツリーの中のいくつかのリスト-
360
361   git ツリー-
362     - Kbuild の開発ツリー、Sam Ravnborg <sam@ravnborg.org>
363         kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git
364
365     - ACPI の開発ツリー、 Len Brown <len.brown@intel.com>
366         kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git
367
368     - Block の開発ツリー、Jens Axboe <axboe@suse.de>
369         kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git
370
371     - DRM の開発ツリー、Dave Airlie <airlied@linux.ie>
372         kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git
373
374     - ia64 の開発ツリー、Tony Luck <tony.luck@intel.com>
375         kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
376
377     - ieee1394 の開発ツリー、Jody McIntyre <scjody@modernduck.com>
378         kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git
379
380     - infiniband, Roland Dreier <rolandd@cisco.com>
381         kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git
382
383     - libata, Jeff Garzik <jgarzik@pobox.com>
384         kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git
385
386     - ネットワークドライバ, Jeff Garzik <jgarzik@pobox.com>
387         kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git
388
389     - pcmcia, Dominik Brodowski <linux@dominikbrodowski.net>
390         kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git
391
392     - SCSI, James Bottomley <James.Bottomley@SteelEye.com>
393         kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git
394
395   その他の git カーネルツリーは http://kernel.org/git に一覧表がありま
396   す。
397
398   quilt ツリー-
399     - USB, PCI ドライバコアと I2C, Greg Kroah-Hartman <gregkh@suse.de>
400         kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/
401
402 バグレポート
403 -------------
404
405 bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する
406 場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。
407 どう kernel bugzilla を使うかの詳細は、以下を参照してください-
408         http://test.kernel.org/bugzilla/faq.html
409
410 メインカーネルソースディレクトリにあるファイル REPORTING-BUGS はカーネ
411 ルバグらしいものについてどうレポートするかの良いテンプレートであり、問
412 題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳
413 細が書かれています。
414
415 メーリングリスト
416 -------------
417
418 上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分
419 は Linux kernel メーリングリストに参加しています。このリストの登録/脱
420 退の方法については以下を参照してください-
421         http://vger.kernel.org/vger-lists.html#linux-kernel
422
423 このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ
424 れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば-
425         http://dir.gmane.org/gmane.linux.kernel
426
427 リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索
428 することを是非やってください。多数の事がすでに詳細に渡って議論されて
429 おり、アーカイブにのみ記録されています。
430
431 大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス
432 トを持っています。個々のグループがどんなリストを持っているかは、
433 MAINTAINERS ファイルにリストがありますので参照してください。
434
435 多くのリストは kernel.org でホストされています。これらの情報は以下にあ
436 ります-
437         http://vger.kernel.org/vger-lists.html
438
439 メーリングリストを使う場合、良い行動習慣に従うようにしましょう。
440 少し安っぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合の
441 シンプルなガイドラインを示しています-
442         http://www.albion.com/netiquette/
443
444 もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは
445 だいぶ多くなるでしょう。良い理由がない場合、CC: リストから誰かを削除を
446 しないように、また、メーリングリストのアドレスだけにリプライすることの
447 ないようにしましょう。1つは送信者から、もう1つはリストからのように、メー
448 ルを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追加し
449 てこの状態を変えようとしないように。人々はそのようなことは好みません。
450
451 今までのメールでのやりとりとその間のあなたの発言はそのまま残し、
452 "John Kernlehacker wrote ...:" の行をあなたのリプライの先頭行にして、
453 メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
454 す。
455
456 もしパッチをメールに付ける場合は、Documentaion/SubmittingPatches に提
457 示されているように、それは プレーンな可読テキストにすることを忘れない
458 ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま
459 せん-
460 彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす
461 るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう
462 に確認した方がいいです。最初の良いテストとしては、自分にメールを送って
463 みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな
464 ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ
465 きです。
466
467 とりわけ、他の登録者に対する尊敬を表すようにすることを覚えておいてくだ
468 さい。
469
470 コミュニティと共に働くこと
471 --------------------------
472
473 カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること
474 です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術
475 的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ
476 うか?
477   - 批判
478   - コメント
479   - 変更の要求
480   - パッチの正当性の証明要求
481   - 沈黙
482
483 思い出してください、ここはあなたのパッチをカーネルに入れる話です。あ
484 なたは、あなたのパッチに対する批判とコメントを受け入れるべきで、それら
485 を技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべ
486 きでないかを明確で簡潔な理由の説明を提供してください。
487 もし、あなたのパッチに何も反応がない場合、たまにはメールの山に埋もれて
488 見逃され、あなたの投稿が忘れられてしまうこともあるので、数日待って再度
489 投稿してください。
490
491 あなたがやるべきでないものは?
492   - 質問なしにあなたのパッチが受け入れられると想像すること
493   - 守りに入ること
494   - コメントを無視すること
495   - 要求された変更を何もしないでパッチを出し直すこと
496
497 可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく
498 らい有益なのかについては常に異なる意見があります。あなたは協調的である
499 べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ
500 うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ
501 だけの価値があるとすすんで証明するようにしなければなりません。
502 正しい解決に向かって進もうという意志がある限り、間違うことがあっても許
503 容されることを忘れないでください。
504
505 あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ
506 とも普通のことです。これはあなたのパッチが受け入れられないということで
507 は *ありません*、そしてあなた自身に反対することを意味するのでも *ありま
508 せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば
509 いいのです。
510
511 カーネルコミュニティと企業組織のちがい
512 -----------------------------------------------------------------
513
514 カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で
515 動いています。以下は問題を避けるためにできるとよいことののリストです-
516
517   あなたの提案する変更について言うときのうまい言い方:
518
519     - "これは複数の問題を解決します"
520     - "これは2000行のコードを削除します"
521     - "以下のパッチは、私が言おうとしていることを説明するものです"
522     - "私はこれを5つの異なるアーキテクチャでテストしたのですが..."
523     - "以下は一連の小さなパッチ群ですが..."
524     - "これは典型的なマシンでの性能を向上させます.."
525
526   やめた方がいい悪い言い方:
527
528     - このやり方で AIX/ptx/Solaris ではできたので、できるはずだ
529     - 私はこれを20年もの間やってきた、だから
530     - これは、私の会社が金儲けをするために必要だ
531     - これは我々のエンタープライズ向け商品ラインのためである
532     - これは 私が自分のアイディアを記述した、1000ページの設計資料である
533     - 私はこれについて、6ケ月作業している。
534     - 以下は ... に関する5000行のパッチです
535     - 私は現在のぐちゃぐちゃを全部書き直した、それが以下です...
536     - 私は〆切がある、そのためこのパッチは今すぐ適用される必要がある
537
538 カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労
539 働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。
540 email と irc を第一のコミュニケーションの形とする一つの利点は、性別や
541 民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受
542 容します。なぜなら、email アドレスによってのみあなたが認識されるからで
543 す。
544 国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた
545 は人の名前で性別を想像できないからです。ある男性が アンドレアという名
546 前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、
547 それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は
548 Patricia (主に女性名)や Patrick (主に男性名)の略称)。
549 Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前
550 向きな経験をもっています。
551
552 言葉の壁は英語が得意でない一部の人には問題になります。
553 メーリングリストの中できちんとアイディアを交換するには、相当うまく英語
554 を操れる必要があることもあります。そのため、あなたは自分のメール
555 を送る前に英語で意味が通じているかをチェックすることをお薦めします。
556
557 変更を分割する
558 ---------------------
559
560 Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ
561 とはありません。変更は正確に説明される必要があり、議論され、小さい、個
562 別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて
563 きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと
564 ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい
565 ることにフィードバックを得られます。これは、コミュニティからみれば、あ
566 なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の
567 ゴミ捨て場として使っているのではない、と感じられるでしょう。
568 しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは
569 やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ
570 くなければなりません。
571
572 パッチを分割する理由は以下です-
573
574 1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー
575    ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか
576    らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。し
577    かし、500行のパッチは、正しいことをレビューするのに数時間かかるかも
578    しれません(時間はパッチのサイズなどにより指数関数に比例してかかりま
579    す)
580    小さいパッチは何かあったときにデバッグもとても簡単になります。パッ
581    チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお
582    かしくなった後で)解剖するのに比べればとても簡単です。
583
584 2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす
585    る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。
586
587 以下はカーネル開発者の Al Viro のたとえ話しです:
588
589         "生徒の数学の宿題を採点する先生のことを考えてみてください、先
590         生は生徒が解に到達するまでの試行錯誤をみたいとは思わないでしょ
591         う。先生は簡潔な最高の解をみたいのです。良い生徒はこれを知って
592         おり、そして最終解の前の中間作業を提出することは決してないので
593         す"
594         カーネル開発でもこれは同じです。メンテナー達とレビューア達は、
595         問題を解決する解の背後になる思考プロセスをみたいとは思いません。
596         彼らは単純であざやかな解決方法をみたいのです。
597
598 あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を
599 議論することのバランスをキープするのは難しいかもしれません。
600 ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ
601 うにするのもいいですが、変更点を小さい部分に分割して全体ではまだ完成し
602 ていない仕事を(部分的に)取り込んでもらえるようにすることもいいことです。
603
604 また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め
605 てもらうように送っても、それは受け付けられないことを理解してください。
606
607 あなたの変更を正当化する
608 -------------------
609
610 あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな
611 いかを Linux コミュニティに知らせることはとても重要です。新機能は必要
612 性と有用性で正当化されなければなりません。
613
614 あなたの変更の説明
615 --------------------
616
617 あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ
618 いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ
619 れ、いつも皆がみられるように保管されます。これは次のような項目を含め、
620 パッチを完全に記述するべきです-
621
622   - なぜ変更が必要か
623   - パッチ全体の設計アプローチ
624   - 実装の詳細
625   - テスト結果
626
627 これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ
628 ントの ChangeLog セクションをみてください-
629   "The Perfect Patch"
630       http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
631
632 これらのどれもが、時にはとても困難です。これらの慣例を完璧に実施するに
633 は数年かかるかもしれません。これは継続的な改善のプロセスであり、そのた
634 めには多数の忍耐と決意を必要とするものです。でも、諦めないで、これは可
635 能なことです。多数の人がすでにできていますし、彼らも皆最初はあなたと同
636 じところからスタートしたのですから。
637
638 Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process"
639 (http://linux.tar.bz/articles/2.6-development_process)セクショ
640 ンをこのテキストの原型にすることを許可してくれました。
641 Rundy Dunlap と Gerrit Huizenga はメーリングリストでやるべきこととやっ
642 てはいけないことのリストを提供してくれました。
643 以下の人々のレビュー、コメント、貢献に感謝。
644 Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
645 Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
646 Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
647 David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard
648 彼らの支援なしでは、このドキュメントはできなかったでしょう。
649
650 Maintainer: Greg Kroah-Hartman <greg@kroah.com>