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