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