Documentation/ja_JP/HOWTO

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