Documentation: Add HOWTO Japanese translation into rst based build system

This commit adds Japanese translation of HOWTO document into rst based
documentation build system with updates.

Signed-off-by: Tsugikazu Shibata <tshibata@ab.jp.nec.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Tsugikazu Shibata 2017-04-08 12:24:04 +02:00 committed by Jonathan Corbet
parent 0e056eb553
commit f012733894
3 changed files with 321 additions and 277 deletions

View File

@ -76,6 +76,14 @@ Chinese translations
translations/zh_CN/index
Japanese translations
---------------------
.. toctree::
:maxdepth: 1
translations/ja_JP/index
Indices and tables
==================

View File

@ -1,95 +1,81 @@
NOTE:
This is a version of Documentation/HOWTO translated into Japanese.
This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
and the JF Project team <www.linux.or.jp/JF>.
If you find any difference between this document and the original file
or a problem with the translation,
please contact the maintainer of this file or JF project.
If you find any difference between this document and the original file or
a problem with the translation, please contact the maintainer of this file.
Please also note that the purpose of this file is to be easier to read
for non English (read: Japanese) speakers and is not intended as a
fork. So if you have any comments or updates for this file, please try
to update the original English file first.
Please also note that the purpose of this file is to be easier to
read for non English (read: Japanese) speakers and is not intended as
a fork. So if you have any comments or updates for this file, please
try to update the original English file first.
Last Updated: 2013/07/19
==================================
は、
linux-3.10/Documentation/HOWTO
----------------------------------
の文書は、
Documentation/process/howto.rst
の和訳です。
翻訳団体: JF プロジェクト < http://linuxjf.sourceforge.jp/ >
翻訳日: 2013/7/19
翻訳者: Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com>
校正者: 松倉さん <nbh--mats at nifty dot com>
小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp>
武井伸光さん、<takei at webmasters dot gr dot jp>
かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp>
野口さん (Kenji Noguchi) <tokyo246 at gmail dot com>
河内さん (Takayoshi Kochi) <t-kochi at bq dot jp dot nec dot com>
岩本さん (iwamoto) <iwamoto.kn at ncos dot nec dot co dot jp>
内田さん (Satoshi Uchida) <s-uchida at ap dot jp dot nec dot com>
==================================
翻訳者: Tsugikazu Shibata <tshibata@ab.jp.nec.com>
----------------------------------
Linux カーネル開発のやり方
-------------------------------
==========================
これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した
ドキュメントです。ここには Linux カーネル開発者になるための方法と
Linux カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれて
います。カーネルプログラミングに関する技術的な項目に関することは何も含
めないようにしていますが、カーネル開発者となるための正しい方向に向かう
手助けになります。
ドキュメントです。ここには Linux カーネル開発者になるための方法とLinux
カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれています。
カーネルプログラミングに関する技術的な項目に関することは何も含めないよ
うにしていますが、カーネル開発者となるための正しい方向に向かう手助けに
なります。
もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン
の最後にリストしたメンテナにパッチを送ってください。
もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン
の最後にリストしたメンテナにパッチを送ってください。
はじめに
---------
あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか? そ
れともあなたは上司から「このデバイスの Linux ドライバを書くように」と
言われているのでしょうか? 
この文書の目的は、あなたが踏むべき手順と、コミュニティと一緒にうまく働
くヒントを書き下すことで、あなたが知るべき全てのことを教えることです。
また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も
説明しようと試みています。
あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか? そ
れとも上司から「このデバイスの Linux ドライバを書くように」と言われた
のかもしれません。この文書の目的は、あなたが踏むべき手順と、コミュニティ
と一緒にうまく働くヒントを書き下すことで、あなたが知るべき全てのことを
教えることです。また、このコミュニティがなぜ今うまくまわっているのかと
いう理由も説明しようと試みています。
カーネルは少量のアーキテクチャ依存部分がアセンブリ言語で書かれている以
外の大部分は C 言語で書かれています。C言語をよく理解していることはカー
ネル開発に必要です。低レベルのアーキテクチャ開発をするのでなければ、
(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要ありません。以下
の本は、C 言語の十分な知識や何年もの経験に取って代わるものではありませ
んが、少なくともリファレンスとしては良い本です。
カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている
以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー
ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの
でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり
ません。以下の本は、C 言語の十分な知識や何年もの経験に取って代わるもの
ではありませんが、少なくともリファレンスとしては良い本です。
- "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
-『プログラミング言語第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
- 『プログラミング言語第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
- "Practical C Programming" by Steve Oualline [O'Reilly]
- 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン]
- "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
- 『新・詳説 C 言語 H&S リファレンス』
(サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]
- 『新・詳説 C 言語 H&S リファレンス』 (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]
カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル
は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って
います。カーネルは標準 C ライブラリとは関係がないといった、C 言語フリー
スタンディング環境です。そのため、C の標準で使えないものもあります。任
意の long long の除算や浮動小数点は使えません。
ときどき、カーネルがツールチェインや C 言語拡張に置いている前提がどう
なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ
レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を
見てください。
います。カーネルは標準 C ライブラリに依存しない、C 言語非依存環境です。
そのため、C の標準の中で使えないものもあります。特に任意の long long
の除算や浮動小数点は使えません。カーネルがツールチェインや C 言語拡張
に置いている前提がどうなっているのかわかりにくいことが時々あり、また、
残念なことに決定的なリファレンスは存在しません。情報を得るには、gcc の
info ページ( info gcc )を見てください。
あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ
とに留意してください。そのコミュニティは、コーディング、スタイル、
発手順について高度な標準を持つ、多様な人の集まりです。
地理的に分散した大規模なチームに対してもっともうまくいくとわかったこと
をベースにしながら、これらの標準は長い時間をかけて築かれてきました。
これらはきちんと文書化されていますから、事前にこれらの標準についてでき
るだけたくさん学んでください。また皆があなたやあなたの会社のやり方に合わ
せてくれると思わないでください。
とに思い出してください。そのコミュニティは、コーディング、スタイル、
発手順について高度な標準を持つ、多様な人の集まりです。地理的に分散した
大規模なチームに対してもっともうまくいくとわかったことをベースにしなが
ら、これらの標準は長い時間をかけて築かれてきました。これらはきちんと文
書化されていますから、事前にこれらの標準について事前にできるだけたくさ
ん学んでください。また皆があなたやあなたの会社のやり方に合わせてくれる
と思わないでください。
法的問題
------------
--------
Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま
す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在
@ -98,8 +84,9 @@ Linux カーネルのソースコードは GPL ライセンスの下でリリー
法律家に相談してください。メーリングリストの人達は法律家ではなく、法的
問題については彼らの声明はあてにするべきではありません。
GPL に関する共通の質問や回答については、以下を参照してください。
http://www.gnu.org/licenses/gpl-faq.html
GPL に関する共通の質問や回答については、以下を参照してください-
https://www.gnu.org/licenses/gpl-faq.html
ドキュメント
------------
@ -119,111 +106,129 @@ linux-api@vger.kernel.org に送ることを勧めます。
README
このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注
configure )し、生成(訳注 build )するために必要なことは何かが書かれ
ています。カーネルに関して初めての人はここからスタートすると良い
しょう。
ています。 カーネルに関して初めての人はここからスタートすると良い
しょう。
Documentation/Changes
このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
ます。
:ref:`Documentation/Process/changes.rst <changes>`
このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
ます。
Documentation/process/coding-style.rst
:ref:`Documentation/process/coding-style.rst <codingstyle>`
これは Linux カーネルのコーディングスタイルと背景にある理由を記述
しています。全ての新しいコードはこのドキュメントにあるガイドライン
に従っていることを期待されています。大部分のメンテナはこれらのルー
ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
だけをレビューします。
Documentation/process/submitting-patches.rst
Documentation/process/submitting-drivers.rst
これらのファイルには、どうやってうまくパッチを作って投稿するかに
ついて非常に詳しく書かれており、以下を含みます(これだけに限らない
けれども)
- Email に含むこと
- Email の形式
- だれに送るか
これらのルールに従えばうまくいくことを保証することではありません
が (すべてのパッチは内容とスタイルについて精査を受けるので)、
ルールに従わなければ間違いなくうまくいかないでしょう。
:ref:`Documentation/process/submitting-patches.rst <codingstyle>`:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
これらのファイルには、どうやってうまくパッチを作って投稿するかにつ
いて非常に詳しく書かれており、以下を含みます (これだけに限らない
けれども)
この他にパッチを作る方法についてのよくできた記述は-
- Email に含むこと
- Email の形式
- だれに送るか
"The Perfect Patch"
これらのルールに従えばうまくいくことを保証することではありません
が (すべてのパッチは内容とスタイルについて精査を受けるので)、
ルールに従わなければ間違いなくうまくいかないでしょう。
この他にパッチを作る方法についてのよくできた記述は-
"The Perfect Patch"
http://www.ozlabs.org/~akpm/stuff/tpp.txt
"Linux kernel patch submission format"
"Linux kernel patch submission format"
http://linux.yyz.us/patch-format.html
Documentation/process/stable-api-nonsense.rst
このファイルはカーネルの中に不変のAPIを持たないことにした意識的な
決断の背景にある理由について書かれています。以下のようなことを含
んでいます-
- サブシステムとの間に層を作ること(コンパチビリティのため?)
- オペレーティングシステム間のドライバの移植性
- カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更
を妨げる)
このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
そして、他のOSでの開発者が Linux に移る時にとても重要です。
:ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
このファイルはカーネルの中に不変の API を持たないことにした意識的
な決断の背景にある理由について書かれています。以下のようなことを含
んでいます-
Documentation/admin-guide/security-bugs.rst
- サブシステムとの間に層を作ること(コンパチビリティのため?)
- オペレーティングシステム間のドライバの移植性
- カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更を妨げる)
このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
そして、他のOSでの開発者が Linux に移る時にとても重要です。
:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`
もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
支援してください。
Documentation/process/management-style.rst
:ref:`Documentation/process/management-style.rst <managementstyle>`
このドキュメントは Linux カーネルのメンテナ達がどう行動するか、
彼らの手法の背景にある共有されている精神について記述しています。こ
れはカーネル開発の初心者なら(もしくは、単に興味があるだけの人でも)
重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な
行動についての多くの誤解や混乱を解消するからです。
Documentation/process/stable-kernel-rules.rst
:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
このファイルはどのように stable カーネルのリリースが行われるかのルー
ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
り入れてもらいたい場合に何をすれば良いかが示されています。
Documentation/process/kernel-docs.rst
  カーネル開発に付随する外部ドキュメントのリストです。もしあなたが
しているものがカーネル内のドキュメントでみつからなかった場合、
このリストをあたってみてください。
:Ref:`Documentation/process/kernel-docs.rst <kernel_docs>`
カーネル開発に付随する外部ドキュメントのリストです。もしあなたが
しているものがカーネル内のドキュメントでみつからなかった場合、この
リストをあたってみてください。
Documentation/process/applying-patches.rst
:ref:`Documentation/process/applying-patches.rst <applying_patches>`
パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
適用するのかについて正確に記述した良い入門書です。
カーネルはソースコードから自動的に生成可能な多数のドキュメントを自分自
身でもっています。これにはカーネル内 API のすべての記述や、どう正しく
ロックをかけるかの規則が含まれます。このドキュメントは
Documentation/DocBook/ ディレクトリに作られ、以下のように
make pdfdocs
make psdocs
make htmldocs
make mandocs
コマンドを実行するとメインカーネルのソースディレクトリから
それぞれ、PDF, Postscript, HTML, man page の形式で生成されます。
カーネルはソースコードそのものや、このファイルのようなリストラクチャー
ドテキストマークアップ(ReST)から自動的に生成可能な多数のドキュメントを
もっています。これにはカーネル内APIの完全な記述や、正しくロックをかけ
るための規則などが含まれます。
これら全てのドキュメントを PDF や HTML で生成するには以下を実行します - ::
make pdfdocs
make htmldocs
それぞれメインカーネルのソースディレクトリから実行します。
ReSTマークアップを使ったドキュメントは Documentation/outputに生成され
ます。Latex とePub 形式で生成するには - ::
make latexdocs
make epubdocs
現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
Postscript または man ページの形式を生成するには以下のようにします - ::
make psdocs
make mandocs
カーネル開発者になるには
---------------------------
------------------------
もしあなたが、Linux カーネル開発について何も知らないならば、
もしあなたが、Linux カーネル開発について何も知らないならば、
KernelNewbies プロジェクトを見るべきです
http://kernelnewbies.org
https://kernelnewbies.org
このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関
するほとんどどんな種類の質問もできます (既に回答されているようなことを
聞く前にまずはアーカイブを調べてください)。
またここには、リアルタイムで質問を聞くことができる IRC チャネルや、Linux
カーネルの開発に関して学ぶのに便利なたくさんの役に立つドキュメントがあ
ります。
聞く前にまずはアーカイブを調べてください)。またここには、リアルタイム
で質問を聞くことができる IRC チャネルや、Linuxカーネルの開発に関して学
ぶのに便利なたくさんの役に立つドキュメントがあります。
web サイトには、コードの構成、サブシステム、現在存在するプロジェクト(ツ
リーにあるもの無いものの両方)の基本的な管理情報があります。
ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接
的な基本情報も記述されています。
Web サイトには、コードの構成、サブシステム、現在存在するプロジェクト
(ツリーにあるもの無いものの両方)の基本的な管理情報があります。ここには、
また、カーネルのコンパイルのやり方やパッチの当て方などの間接的な基本情
報も記述されています。
あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ
ニティに参加して何かすることをさがしている場合には、Linux kernel
ニティに参加して何かすることをさがしているのであれば、Linux kernel
Janitor's プロジェクトにいけば良いでしょう -
http://kernelnewbies.org/KernelJanitors
https://kernelnewbies.org/KernelJanitors
ここはそのようなスタートをするのにうってつけの場所です。ここには、
Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな
らない、単純な問題のリストが記述されています。このプロジェクトに関わる
@ -232,10 +237,11 @@ Linux カーネルソースツリーの中に含まれる、きれいにし、
ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。
もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入
れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネル
メンターズプロジェクトはそのような皆さんを助けるためにできました。
ここにはメーリングリストがあり、以下から参照できます
http://selenic.com/mailman/listinfo/kernel-mentors
れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネルメ
ンターズプロジェクトはそのような皆さんを助けるためにできました。ここに
はメーリングリストがあり、以下から参照できます -
https://selenic.com/mailman/listinfo/kernel-mentors
実際に Linux カーネルのコードについて修正を加える前に、どうやってその
コードが動作するのかを理解することが必要です。そのためには、特別なツー
@ -244,27 +250,29 @@ Linux カーネルソースツリーの中に含まれる、きれいにし、
特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、
自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
ます-
ます -
http://lxr.free-electrons.com/
開発プロセス
-----------------------
------------
Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン
チ」と多数のサブシステム毎のカーネルブランチから構成されます。
これらのブランチとは-
- メインの 3.x カーネルツリー
- 3.x.y -stable カーネルツリー
- 3.x -git カーネルパッチ
チ」と多数のサブシステム毎のカーネルブランチから構成されます。これらの
ブランチとは -
- メインの 4.x カーネルツリー
- 4.x.y -stable カーネルツリー
- 4.x -git カーネルパッチ
- サブシステム毎のカーネルツリーとパッチ
- 統合テストのための 3.x -next カーネルツリー
- 統合テストのための 4.x -next カーネルツリー
3.x カーネルツリー
-----------------
4.x カーネルツリー
~~~~~~~~~~~~~~~~~~
3.x カーネルは Linus Torvalds によってメンテナンスされ、kernel.org
の pub/linux/kernel/v3.x/ ディレクトリに存在します。この開発プロセスは
以下のとおり-
4.x カーネルは Linus Torvalds によってメンテナンスされ、
https://kernel.org の pub/linux/kernel/v4.x/ ディレクトリに存在します。
この開発プロセスは以下のとおり -
- 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、
この期間中に、メンテナ達は Linus に大きな差分を送ることができます。
@ -272,7 +280,6 @@ Linux カーネルの開発プロセスは現在幾つかの異なるメイン
大きな変更は git(カーネルのソース管理ツール、詳細は
http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ
チファイルの形式のまま送るのでも十分です。
- 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定
性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと
はできません。新しいドライバ(もしくはファイルシステム)のパッチは
@ -282,44 +289,45 @@ Linux カーネルの開発プロセスは現在幾つかの異なるメイン
Linus へパッチを送付するのに git を使うこともできますが、パッチは
レビューのために、パブリックなメーリングリストへも同時に送る必要が
あります。
- 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分
に安定した状態にあると判断したときにリリースされます。目標は毎週新
しい -rc カーネルをリリースすることです。
- このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま
す。このプロセスはだいたい 6週間継続します。
Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ
て書いたことをここで言っておくことは価値があります-
「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現
実に認識されたバグの状況によりリリースされるのであり、前もって決めら
れた計画によってリリースされるものではないからです。」
て書いたことをここで言っておくことは価値があります -
3.x.y -stable カーネルツリー
---------------------------
*「カーネルがいつリリースされるかは誰も知りません。なぜなら、
これは現実に認識されたバグの状況によりリリースされるのであり、
前もって決められた計画によってリリースされるものではないから
です。」*
4.x.y -stable カーネルツリー
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。
これには、3.x カーネルで見つかったセキュリティ問題や重大な後戻りに対
する比較的小さい重要な修正が含まれます。
これには、4.x カーネルで見つかったセキュリティ問題や重大な後戻りに対
る比較的小さい重要な修正が含まれます。
これは、開発/実験的バージョンのテストに協力することに興味が無く、
最新の安定したカーネルを使いたいユーザに推奨するブランチです。
これは、開発/実験的バージョンのテストに協力することに興味が無く、最新
の安定したカーネルを使いたいユーザに推奨するブランチです。
もし、3.x.y カーネルが存在しない場合には、番号が一番大きい 3.x が
最新の安定版カーネルです。
もし、4.x.y カーネルが存在しない場合には、番号が一番大きい 4.x が最新
の安定版カーネルです。
3.x.y は "stable" チーム <stable@vger.kernel.org> でメンテされており、
要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差し迫っ
た問題がなければもう少し長くなることもあります。セキュリティ関連の問題
の場合はこれに対してだいたいの場合、すぐにリリースがされます。
4.x.y は "stable" チーム <stable@vger.kernel.org> でメンテされており、
要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差
し迫った問題がなければもう少し長くなることもあります。セキュリティ関
連の問題の場合はこれに対してだいたいの場合、すぐにリリースがされます。
カーネルツリーに入っている、Documentation/process/stable-kernel-rules.rst ファ
イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ
リースプロセスがどう動くかが記述されています。
カーネルツリーに入っている、
Documentation/process/stable-kernel-rules.rst ファイルにはどのような種
類の変更が -stable ツリーに受け入れ可能か、またリリースプロセスがどう
動くかが記述されています。
3.x -git パッチ
------------------
4.x -git パッチ
~~~~~~~~~~~~~~~
git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ
ショットがあります。(だから -git という名前がついています)。これらのパッ
@ -328,7 +336,7 @@ git リポジトリで管理されているLinus のカーネルツリーの毎
に生成されるので、より実験的です。
サブシステム毎のカーネルツリーとパッチ
-------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
それぞれのカーネルサブシステムのメンテナ達は --- そして多くのカーネル
サブシステムの開発者達も --- 各自の最新の開発状況をソースリポジトリに
@ -340,42 +348,45 @@ git リポジトリで管理されているLinus のカーネルツリーの毎
大部分のこれらのリポジトリは git ツリーです。しかしその他の SCM や
quilt シリーズとして公開されているパッチキューも使われています。これら
のサブシステムリポジトリのアドレスは MAINTAINERS ファイルにリストされ
ています。これらの多くは http://git.kernel.org/ で参照することができま
ています。これらの多くは https://git.kernel.org/ で参照することができま
す。
提案されたパッチがこのようなサブシステムツリーにコミットされる前に、メー
リングリストで事前にレビューにかけられます(以下の対応するセクションを
参照)。いくつかのカーネルサブシステムでは、このレビューは patchwork
いうツールによって追跡されます。Patchwork は web インターフェイスに
よってパッチ投稿の表示、パッチへのコメント付けや改訂などができ、そして
メンテナはパッチに対して、レビュー中、受付済み、拒否というようなマーク
をつけることができます。大部分のこれらの patchwork のサイトは
http://patchwork.kernel.org/ でリストされています。
参照)。いくつかのカーネルサブシステムでは、このレビューは patchwork
いうツールによって追跡されます。Patchwork は web インターフェイスによっ
てパッチ投稿の表示、パッチへのコメント付けや改訂などができ、そしてメン
テナはパッチに対して、レビュー中、受付済み、拒否というようなマークをつ
けることができます。大部分のこれらの patchwork のサイトは
https://patchwork.kernel.org/ でリストされています。
統合テストのための 3.x -next カーネルツリー
---------------------------------------------
統合テストのための 4.x -next カーネルツリー
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
サブシステムツリーの更新内容がメインラインの 3.x ツリーにマージされ
る前に、それらは統合テストされる必要があります。この目的のため、実質的
に全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリ
ポジトリが存在します-
http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
サブシステムツリーの更新内容がメインラインの 4.x ツリーにマージされる
前に、それらは統合テストされる必要があります。この目的のため、実質的に
全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリポジ
トリが存在します-
https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
このやり方によって、-next カーネルは次のマージ機会でどんなものがメイン
ラインカーネルにマージされるか、おおまかなの展望を提供します。-next
カーネルの実行テストを行う冒険好きなテスターは大いに歓迎されます
ラインカーネルにマージされるか、おおまかなの展望を提供します。-next カー
ネルの実行テストを行う冒険好きなテスターは大いに歓迎されます
バグレポート
-------------
bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する
場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。
どう kernel bugzilla を使うかの詳細は、以下を参照してください-
http://bugzilla.kernel.org/page.cgi?id=faq.html
メインカーネルソースディレクトリにあるファイル admin-guide/reporting-bugs.rst はカーネ
ルバグらしいものについてどうレポートするかの良いテンプレートであり、問
題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳
細が書かれています。
https://bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する
場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。どう
kernel bugzilla を使うかの詳細は、以下を参照してください -
https://bugzilla.kernel.org/page.cgi?id=faq.html
メインカーネルソースディレクトリにあるファイル
admin-guide/reporting-bugs.rstはカーネルバグらしいものについてどうレポー
トするかの良いテンプレートであり、問題の追跡を助けるためにカーネル開発
者にとってどんな情報が必要なのかの詳細が書かれています。
バグレポートの管理
-------------------
@ -383,74 +394,78 @@ bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを
あなたのハッキングのスキルを訓練する最高の方法のひとつに、他人がレポー
トしたバグを修正することがあります。あなたがカーネルをより安定化させる
こに寄与するということだけでなく、あなたは 現実の問題を修正することを
学び、自分のスキルも強化でき、また他の開発者があなたの存在に気がつき
す。バグを修正することは、多くの開発者の中から自分が功績をあげる最善
道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好ま
いからです。
学び、自分のスキルも強化でき、また他の開発者があなたの存在に気がつき
す。バグを修正することは、多くの開発者の中から自分が功績をあげる最善
道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好ま
いからです。
すでにレポートされたバグのために仕事をするためには、
http://bugzilla.kernel.org に行ってください。もし今後のバグレポートに
https://bugzilla.kernel.org に行ってください。もし今後のバグレポートに
ついてアドバイスを受けたいのであれば、bugme-new メーリングリスト(新し
いバグレポートだけがここにメールされる) または bugme-janitor メーリン
グリスト(bugzilla の変更毎にここにメールされる)を購読できます。
http://lists.linux-foundation.org/mailman/listinfo/bugme-new
http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
https://lists.linux-foundation.org/mailman/listinfo/bugme-new
https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
メーリングリスト
-------------
----------------
上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分
は Linux kernel メーリングリストに参加しています。このリストの登録/脱
退の方法については以下を参照してください-
http://vger.kernel.org/vger-lists.html#linux-kernel
このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ
れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば-
http://dir.gmane.org/gmane.linux.kernel
リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索
することを是非やってください。多数の事がすでに詳細に渡って議論されて
り、アーカイブにのみ記録されています。
することを是非やってください。多数の事がすでに詳細に渡って議論されて
り、アーカイブにのみ記録されています。
大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス
トを持っています。個々のグループがどんなリストを持っているかは、
MAINTAINERS ファイルにリストがありますので参照してください。
多くのリストは kernel.org でホストされています。これらの情報は以下にあ
ります-
ります -
http://vger.kernel.org/vger-lists.html
メーリングリストを使う場合、良い行動習慣に従うようにしましょう。
少し安っぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合の
シンプルなガイドラインを示しています-
メーリングリストを使う場合、良い行動習慣に従うようにしましょう。少し安っ
ぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合のシンプル
なガイドラインを示しています -
http://www.albion.com/netiquette/
もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは
だいぶ多くなるでしょう。良い理由がない場合、CC: リストから誰かを削除を
しないように、また、メーリングリストのアドレスだけにリプライすることの
ないようにしましょう。1つは送信者から、もう1つはリストからのように、メー
ルを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追加し
てこの状態を変えようとしないように。人々はそのようなことは好みません。
だいぶ多くなるでしょう。正当な理由がない限り、CC: リストから誰かを削除
をしないように、また、メーリングリストのアドレスだけにリプライすること
のないようにしましょう。1つは送信者から、もう1つはリストからのように、
メールを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追
加してこの状態を変えようとしないように。人々はそのようなことは好みませ
ん。
今までのメールでのやりとりとその間のあなたの発言はそのまま残し、
"John Kernelhacker wrote ...:" の行をあなたのリプライの先頭行にして、
メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
す。
もしパッチをメールに付ける場合は、Documentation/process/submitting-patches.rst に提
示されているように、それは プレーンな可読テキストにすることを忘れない
ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま
せん-
彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす
るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう
に確認した方が良いです。最初の良いテストとしては、自分にメールを送って
みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな
ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ
きです。
もしパッチをメールに付ける場合は、
Documentation/process/submitting-patches.rst に提示されているように、そ
れは プレーンな可読テキストにすることを忘れないようにしましょう。カー
ネル開発者は 添付や圧縮したパッチを扱いたがりません。彼らはあなたのパッ
チの行毎にコメントを入れたいので、そうするしかありません。あなたのメー
ルプログラムが空白やタブを圧縮しないように確認しましょう。最初の良いテ
ストとしては、自分にメールを送ってみて、そのパッチを自分で当ててみるこ
とです。もしそれがうまく行かないなら、あなたのメールプログラムを直して
もらうか、正しく動くように変えるべきです。
とりわけ、他の登録者に対する尊敬を表すようにすることを覚えておいてくだ
さい。
何をおいても、他の購読者に対する敬意を表すことを忘れないでください。
コミュニティと共に働くこと
--------------------------
@ -459,21 +474,22 @@ MAINTAINERS ファイルにリストがありますので参照してくださ
です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術
的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ
うか?
- 批判
- コメント
- 変更の要求
- パッチの正当性の証明要求
- 沈黙
思い出してください、ここはあなたのパッチをカーネルに入れる話です。あ
なたは、あなたのパッチに対する批判とコメントを受け入れるべきで、それら
を技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべ
きでないかを明確で簡潔な理由の説明を提供してください。
もし、あなたのパッチに何も反応がない場合、たまにはメールの山に埋もれて
見逃され、あなたの投稿が忘れられてしまうこともあるので、数日待って再度
投稿してください。
思い出してください、これはあなたのパッチをカーネルに入れる話です。あな
たは、あなたのパッチに対する批判とコメントを受け入れるべきで、それらを
技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべき
でないかを明確で簡潔な理由の説明を提供してください。もし、あなたのパッ
チに何も反応がない場合、たまにはメールの山に埋もれて見逃され、あなたの
投稿が忘れられてしまうこともあるので、数日待って再度投稿してください。
あなたがやるべきでないことは?
あなたがやるべきでないものは?
- 質問なしにあなたのパッチが受け入れられると想像すること
- 守りに入ること
- コメントを無視すること
@ -489,37 +505,37 @@ MAINTAINERS ファイルにリストがありますので参照してくださ
あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ
とも普通のことです。これはあなたのパッチが受け入れられないということで
*ありません*、そしてあなた自身に反対することを意味するのでも *ありま
せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば
良いのです。
**ありません**、そしてあなた自身に反対することを意味するのでも **
りません**。単に自分のパッチに対して指摘された問題を全て修正して再送す
れば良いのです。
カーネルコミュニティと企業組織のちがい
-----------------------------------------------------------------
カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で
動いています。以下は問題を避けるためにできると良いことのリストです-
動いています。以下は問題を避けるためにできると良いことのリストです
あなたの提案する変更について言うときのうまい言い方
あなたの提案する変更について言うときのうまい言い方 -
- "これは複数の問題を解決します"
- "これは2000行のコードを削除します"
- "以下のパッチは、私が言おうとしていることを説明するものです"
- "私はこれを5つの異なるアーキテクチャでテストしたのですが..."
- "以下は一連の小さなパッチ群ですが..."
- "これは典型的なマシンでの性能を向上させます.."
- "これは典型的なマシンでの性能を向上させます..."
やめた方が良い悪い言い方
やめた方が良い悪い言い方 -
- このやり方で AIX/ptx/Solaris ではできたので、できるはずだ
- 私はこれを20年もの間やってきた、だから
- これは私の会社が金儲けをするために必要だ
- これは我々のエンタープライズ向け商品ラインのためである
- これは 私が自分のアイディアを記述した、1000ページの設計資料である
- 私はこれについて、6ケ月作業している
- 以下は ... に関する5000行のパッチです
- 私は現在のぐちゃぐちゃを全部書き直した、それが以下です...
- 私は〆切がある、そのためこのパッチは今すぐ適用される必要がある
- "このやり方で AIX/ptx/Solaris ではできたので、できるはずだ..."
- "私はこれを20年もの間やってきた、だから..."
- "これは私の会社が金儲けをするために必要だ"
- "これは我々のエンタープライズ向け商品ラインのためである"
- "これは私が自分のアイディアを記述した、1000ページの設計資料である"
- "私はこれについて、6ケ月作業している..."
- "以下は ... に関する5000行のパッチです"
- "私は現在のぐちゃぐちゃを全部書き直した、それが以下です..."
- "私は〆切がある、そのためこのパッチは今すぐ適用される必要がある"
カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労
働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。
@ -535,13 +551,13 @@ Patricia (主に女性名)や Patrick (主に男性名)の略称)。
Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前
向きな経験をもっています。
言葉の壁は英語が得意でない一部の人には問題になります。
メーリングリストの中できちんとアイディアを交換するには、相当うまく英語
を操れる必要があることもあります。そのため、あなたは自分のメール
を送る前に英語で意味が通じているかをチェックすることをお薦めします。
言葉の壁は英語が得意でない一部の人には問題になります。メーリングリスト
の中できちんとアイディアを交換するには、相当うまく英語を操れる必要が
あることもあります。そのため、自分のメールを送る前に英語で意味が通じて
いるかをチェックすることをお薦めします。
変更を分割する
---------------------
--------------
Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ
とはありません。変更は正確に説明される必要があり、議論され、小さい、個
@ -555,7 +571,7 @@ Linux カーネルコミュニティは、一度に大量のコードの塊を
やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ
くなければなりません。
パッチを分割する理由は以下です-
パッチを分割する理由は以下 -
1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー
ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか
@ -571,41 +587,41 @@ Linux カーネルコミュニティは、一度に大量のコードの塊を
2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす
る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。
以下はカーネル開発者の Al Viro のたとえ話です
以下はカーネル開発者の Al Viro のたとえ話です -
"生徒の数学の宿題を採点する先生のことを考えてみてください、
生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでし
う。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知っ
おり、そして最終解の前の中間作業を提出することは決してないの
す"
*"生徒の数学の宿題を採点する先生のことを考えてみてください、
生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでし
う。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知っ
おり、そして最終解の前の中間作業を提出することは決してないの
です*
カーネル開発でもこれは同じです。メンテナ達とレビューア達は、
*カーネル開発でもこれは同じです。メンテナ達とレビューア達は、
問題を解決する解の背後になる思考プロセスを見たいとは思いません。
彼らは単純であざやかな解決方法を見たいのです。
彼らは単純であざやかな解決方法を見たいのです。"*
あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を
議論することのバランスをキープするのは難しいかもしれません。
ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ
うにするのも良いですが、変更点を小さい部分に分割して全体ではまだ完成し
ていない仕事を(部分的に)取り込んでもらえるようにすることも良いことです。
議論することのバランスをキープするのは難しいかもしれません。ですから、
開発プロセスの早期段階で改善のためのフィードバックをもらうようにするの
も良いですが、変更点を小さい部分に分割して全体ではまだ完成していない仕
事を(部分的に)取り込んでもらえるようにすることも良いことです。
また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め
てもらうように送っても、それは受け付けられないことを理解してください。
あなたの変更を正当化する
-------------------
------------------------
あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな
いかを Linux コミュニティに知らせることはとても重要です。新機能は必要
性と有用性で正当化されなければなりません。
あなたの変更の説明
--------------------
あなたの変更を説明する
----------------------
あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ
いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ
れ、いつも皆がみられるように保管されます。これは次のような項目を含め、
パッチを完全に記述するべきです-
パッチを完全に記述するべきです -
- なぜ変更が必要か
- パッチ全体の設計アプローチ
@ -613,18 +629,24 @@ Linux カーネルコミュニティは、一度に大量のコードの塊を
- テスト結果
これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ
ントの ChangeLog セクションを見てください-
ントの ChangeLog セクションを見てください -
"The Perfect Patch"
http://www.ozlabs.org/~akpm/stuff/tpp.txt
これらのどれもが、時にはとても困難です。これらの慣例を完璧に実施するに
は数年かかるかもしれません。これは継続的な改善のプロセスであり、そのた
めには多数の忍耐と決意を必要とするものです。でも、諦めないで、これは可
能なことです。多数の人がすでにできていますし、彼らも皆最初はあなたと同
じところからスタートしたのですから。
これらはどれも、実行することが時にはとても困難です。これらの例を完璧に
実施するには数年かかるかもしれません。これは継続的な改善のプロセスであ
り、多くの忍耐と決意を必要とするものです。でも諦めないで、実現は可能で
す。多数の人がすでにできていますし、彼らも最初はあなたと同じところから
スタートしたのですから。
----------
Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process"
(http://lwn.net/Articles/94386/) セクションをこのテキストの原型にする
(https://lwn.net/Articles/94386/) セクションをこのテキストの原型にする
ことを許可してくれました。Rundy Dunlap と Gerrit Huizenga はメーリング
リストでやるべきこととやってはいけないことのリストを提供してくれました。
以下の人々のレビュー、コメント、貢献に感謝。
@ -634,4 +656,6 @@ Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard
彼らの支援なしでは、このドキュメントはできなかったでしょう。
Maintainer: Greg Kroah-Hartman <greg@kroah.com>

View File

@ -0,0 +1,12 @@
.. raw:: latex
\renewcommand\thesection*
\renewcommand\thesubsection*
Japanese translations
=====================
.. toctree::
:maxdepth: 1
howto