submittingpatches

linux 内核源代码

NOTE:
This is a version of Documentation/SubmittingPatches into Japanese.
This document is maintained by Keiichi KII <[e-mail]>
and the JF Project team <http://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.

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 of this file, please try
to update the original English file first.

Last Updated: 2007/10/24
==================================
これは、
linux-2.6.23/Documentation/SubmittingPatches の和訳
です。
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日： 2007/10/17
翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com>
校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp>
         Matsukura さん <nbh--mats at nifty dot com>
==================================

        Linux カーネルに変更を加えるための Howto
        又は
        かの Linus Torvalds の取り扱い説明書

Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ
てもらえやすくする提案を集めたものです。

コードを投稿する前に、Documentation/SubmitChecklist の項目リストに目
を通してチェックしてください。もしあなたがドライバーを投稿しようとし
ているなら、Documentation/SubmittingDrivers にも目を通してください。

--------------------------------------------
セクション1 パッチの作り方と送り方
--------------------------------------------

1) 「 diff -up 」
------------

パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。

Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で
生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引
数を指定して、unified 形式のパッチを作成することを確認してください。また、
変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。
この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux
カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート
ディレクトリを基準にしないといけません。

1個のファイルについてのパッチを作成するためには、ほとんどの場合、
以下の作業を行えば十分です。

	SRCTREE= linux-2.6
	MYFILE=  drivers/net/mydriver.c

	cd $SRCTREE
	cp $MYFILE $MYFILE.orig
	vi $MYFILE	# make your change
	cd ..
	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch

複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
ソースとの差分を生成しないといけません。例えば、

	MYSRC= /devel/linux-2.6

	tar xvfz linux-2.6.12.tar.gz
	mv linux-2.6.12 linux-2.6.12-vanilla
	diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
		linux-2.6.12-vanilla $MYSRC > /tmp/patch

dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された
ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1)
コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ
ンの Linux カーネルソースツリーに含まれています。それより前のバージョン
の Linux カーネルソースツリーに対する dontdiff ファイルは、
<http://www.xenotime.net/linux/doc/dontdiff>から取得することができます。

投稿するパッチの中に関係のない余分なファイルが含まれていないことを確
認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお
りのものであることを確認してください。

もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ
を意味のあるひとまとまりごとに分けたいと思うかもしれません。
これは他のカーネル開発者にとってレビューしやすくなるので、あなたの
パッチを受け入れてもらうためにはとても重要なことです。これを補助でき
る多くのスクリプトがあります。

Quilt:
http://savannah.nongnu.org/projects/quilt

Andrew Morton's patch scripts:
http://www.zip.com.au/~akpm/linux/patches/
このリンクの先のスクリプトの代わりとして、quilt がパッチマネジメント
ツールとして推奨されています(上のリンクを見てください)。

2) パッチに対する説明

パッチの中の変更点に対する技術的な詳細について説明してください。

説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、
「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス
テム X に対する更新を含んでいます。どうか取り入れてください。」などです。

説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある
という兆候です。次の #3 を見てください。

3) パッチの分割

意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。

例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強
化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分
けてください。もし変更箇所に API の更新と、その新しい API を使う新たな
ドライバーが含まれているなら、2つのパッチに分けてください。

一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え
るのであれば、その変更を1つのパッチにまとめてください。言いかえると、
意味的に同じ1つの変更は1つのパッチの中に含まれます。

あるパッチが変更を完結させるために他のパッチに依存していたとしても、
それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存
している」と簡単に注意書きをつけてください。

もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは
15かそこらのパッチを送り、そのレビューと統合を待って下さい。

4) パッチのスタイルチェック

あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
ていないかをチェックして下さい。その詳細を Documentation/CodingStyle で
見つけることができます。コーディングスタイルの違反はレビューする人の
時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
拒否されるでしょう。

あなたはパッチを投稿する前に最低限パッチスタイルチェッカー
( scripts/patchcheck.pl )を利用してパッチをチェックすべきです。
もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な
理由を示せるようにしておく必要があります。

5) 電子メールの宛先の選び方

MAINTAINERS ファイルとソースコードに目を通してください。そして、その変
更がメンテナのいる特定のサブシステムに加えられるものであることが分か
れば、その人に電子メールを送ってください。

もし、メンテナが載っていなかったり、メンテナからの応答がないなら、
LKML ( [e-mail] )へパッチを送ってください。ほとんど
のカーネル開発者はこのメーリングリストに目を通しており、変更に対して
コメントを得ることができます。

15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな
いでください!!!

Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者
です。電子メールアドレスは [e-mail] になります。彼は
多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは
避けるべきです。

バグフィックスであったり、自明な変更であったり、話し合いをほとんど
必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。
話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず
は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを
Linus へ送るべきです。

6) CC (カーボンコピー)先の選び方

特に理由がないなら、LKML にも CC してください。

Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ
の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ
るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー
リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ
ムなどの特定のサブシステムに関するメーリングリストもあります。あなた
の変更に、はっきりと関連のあるメーリングリストについて知りたければ
MAINTAINERS ファイルを参照してください。

VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の
サイトに載っています。