==================================
これは、
http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt の和訳
です。
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日： 2006/12/26
更新日： 2007/2/5
翻訳者： Takayoshi Kochi <t-kochi at bq dot jp dot nec dot com>
校正者： Masanori Kobayashi さん <zap03216 at nifty dot ne dot jp>
==================================

The perfect patch.
完全なるパッチ。
akpm@osdl.org
Updated 4 March 2006

The latest version of this document may be found at
この文書の最新版は以下の場所から参照できる。
http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

Please also see http://linux.yyz.us/patch-format.html
http://linux.yyz.us/patch-format.html も参照すること。

1: Delivery
1: 投稿
===========

a) Patches are delivered via email only.  Downloading them from internet
   servers is a pain.

   パッチは電子メールでのみ投稿すること。インターネットサーバから
   ダウンロードさせられるのはたまらない。

b) One patch per email, with the changelog in the body of the email.

   電子メール一通につきパッチは一つだけにし、変更履歴をメール本文の
   中に含めること。

2: Subject:
2: Subject: (件名)
===========

a) The email's Subject: should concisely describe the patch which that
   email contains.  The Subject: should not be a filename.  Use different
   Subject:s for each patch in a patch series.

   電子メールの Subject: はパッチの内容を簡潔に要約すべきである。
   Subject: はファイル名のみにすべきではない。一連のパッチを
   送る場合はそれぞれに異なる Subject: を付けること。

   Bear in mind that the Subject: of your email becomes a globally-unique
   identifier for that patch.  It propagates all the way into the kernel
   revision control system.  The Subject: may later be used in developer
   discussions which refer to the patch.  People will want to google for the
   patch's Subject: to read discussion regarding that patch.

   電子メールの Subject: はパッチについての世界中で唯一の識別子となることを心に
   留めておくこと。Subject: は最終的にカーネルのリビジョンコントロール
   システムにまで伝搬する。後に開発者が議論の中でそのパッチを参照する
   ためにその Subject: を使うこともあるだろう。そしてそのパッチについての
   議論を読むために Subject: を Google で検索したい人々も出てくるだろう。

b) It is nice if the Subject: includes mention of the subsystem which it
   affects.  See example below.

   Subject: に関連するサブシステムの名前を含めておくと良い。以下の例を見よ。

c) Example Subject:
   Subject: の例 -

	[patch 2/5] ext2: improve scalability of bitmap searching
        ([patch 2/5] ext2: ビットマップ探索のスケーラビリティ向上)

        (訳注: 本来パッチの投稿は英語で行うものなので、Subject: や
        メールの中身に関しては英文と並べて参考訳とする。以下同じ)

d) Note that various people's patch receiving scripts will strip away
   Subject: text which is inside brackets [].  So you should place information
   which has no long-term relevance to the patch inside brackets.  This
   includes the word "patch" and any sequence numbering.  The subsystem
   identifier ("ext2:") should hence be outside brackets.

   いろんな人の使っているパッチ処理スクリプトは、Subject: の角括弧 [] で
   囲まれた部分を削ることに注意すること。だから角括弧の中に入れるのは
   長期的にはそのパッチと関係のないような情報だけにすべきである。
   たとえば "patch" という単語や連番などである。したがってサブシステムを
   示す情報 (上記の例では ext2:) は角括弧の外側に書くべきだ。

3: Attribution
3: 作者の表示
==============

If someone else wrote the patch, they should be credited (and blamed) for it. 
To communicate this, add a line:

もし誰か他人がパッチを書いたのなら、その人がクレジットされ (かつ非難され)
るようにすべきだ。この情報を伝えるためには、以下のような一行を電子メールの
最初の一行に書き加えること -

From: John Doe <jdoe@wherever.com>

as the very first line of the email.  Downstream tools will pick this up and
jdoe will get the git "Author" line.

下流のツールがこれを拾い、jdoe が git (訳注: カーネルソースコード管理
ツールの名称) の "Author" 行に表示されるようになる。

4: Changelog
4: 変更履歴
============

a) Bear in mind that the Subject: and changelog which you provide will
   propagate all the way into the permanent kernel record.  Other developers
   will want to read and understand your patch and changelog years in the
   future.

   自分の書いた Subject: と変更履歴は、はるばる伝搬しカーネルの
   履歴として永久に記録されることを心に留めておくこと。他の開発者は
   何年も先にあなたのパッチと変更履歴を読んで中身を理解しようとする
   ことだろう。

   So the changelog should describe the patch fully:

   だから変更履歴にはそのパッチについて以下のような事柄を
   漏れなく記述しておくべきだ -

   - why the kernel needed patching
   - カーネルにパッチが必要な理由

   - the overall design approach in the patch
   - パッチの全体的な設計戦略

   - implementation details
   - 実装の詳細

   - testing results
   - テストの結果

b) Don't bother mentioning what version of the kernel the patch applies to
   ("applies to 2.6.8-rc1").  This is not interesting information - once the
   patch is in the kernel.org kernel, of _course_ it applied, and it'll
   probably be merged into a later kernel than the one which you wrote it for.

   パッチがどのバージョンに適用できるのか ("applies to 2.6.8-rc1"
   (2.6.8-rc1 に適用できる)) を書く必要はない。もし kernel.org 版カーネルに
   取り込まれたならば「当然」適用できたのだし、おそらくはパッチが
   対象としていたバージョンより後のカーネルにマージされる
   であろうから、どのバージョンに適用できるパッチなのかは変更履歴の
   中ではあまり重要ではない情報だ。

c) Don't include text such as "this patch does ..." or "here is patch which
   ...".  There's no point in telling us that it's a patch - once it's in the
   kernel SCM we _know_ it's a patch!

   "this patch does..." (「これは〜をするパッチです」)や
   "here is patch which..." (「このパッチは〜」) といった表現を
   含めないこと。カーネル SCM (訳注: Source Code Management の略、
   すなわち git のこと) に入ってしまえばそれはパッチであることは
   明明白白なのでパッチであることをわざわざ説明する価値はない。

d) Do not refer to earlier patches when changelogging a new version of a
   patch.  It's not very useful to have a final changelog which says "OK,
   this fixes the things you mentioned yesterday".  Each iteration of the
   patch should contain a standalone changelog.  This implies that you need a
   patch management system which maintains changelogs.  See below.

   パッチの新しいバージョンの変更履歴で以前のパッチへの言及をしないこと。
   最終的な変更履歴に「OK、昨日指摘された問題を修正した」と書かれて
   いてもあまり意味がない。パッチの投稿ごとに変更履歴は独立して
   意味をなすようにすべきである。
   これは変更履歴を管理できるパッチ管理システムが必要になることを
   暗に意味している。下方を参照せよ。

e) Add a Signed-off-by: line, as per section 11 of the
   Documentation/SubmittingPatches file in the kernel tree.

   カーネルツリーの Documentation/SubmittingPatches ファイルの項番 11 に
   あるように、Signed-off-by: 行を書くこと。

   Signed-off-by: implies that you had some part in the developent of the
   patch, or that you handled it and passed it on to another developer for
   merging.

   Signed-off-by: 行はその人がパッチ開発の一部分を担ったり、その人が
   関わった後、マージのために他の開発者に渡したりしたことを意味する。

   If your role was purely review and/or testing, please use Acked-by:
   instead.

   もし果たした役割が純粋にレビューやテスト、あるいはその両方ならば
   Acked-by: を代わりに使うこと。

   Sometimes we also use Cc: in a patch to keep particular individuals
   abreast of the patch's status and to give them an opportunity to review it.

   時には特定の個人にパッチの状況を伝えるとともにレビューしてもらう
   ようお願いするため、Cc: を使うこともある。

f) Most people's patch receiving scripts will treat a ^--- string as the
   separator between the changelog and the patch itself.  You can use this to
   ensure that any diffstat information is discarded when the patch is
   applied:

   ほとんどの人のパッチを処理するスクリプトは ^--- (訳注: ^ は正規表現で
   行頭を表している) という文字列を変更履歴とパッチそのものの間の
   セパレータとして扱う。これを利用してパッチ適用時に diffstat 情報を
   捨てさせることができる。

	Another few #if/#ifdef cleanups, this time for the PPC architecture.
        (さらにいくつかの #if/#ifdef クリーンアップ、今回は PPC アーキ
        テクチャ用)

	Signed-off-by: <valdis.kletnieks@vt.edu>
	Signed-off-by: Andrew Morton <akpm@osdl.org>
	---

	 25-akpm/arch/ppc/kernel/process.c                    |    2 +-
	 25-akpm/arch/ppc/platforms/85xx/mpc85xx_cds_common.c |    2 +-
	 25-akpm/arch/ppc/syslib/ppc85xx_setup.c              |    4 ++--
	 3 files changed, 4 insertions(+), 4 deletions(-)

	--- 25/arch/ppc/kernel/process.c
	+++ 25/arch/ppc/kernel/process.c
	@@ -667,7 +667,7 @@ void show_stack(struct task_struct *tsk,

g) Non-changelog text:

   変更履歴以外の文 -

   Sometimes you want to include text in the email which isn't designed to
   go into the changelog in the git repository.  Things like "this is already
   in Fred's tree" or "this is an updated version of last Friday's patch" or
   whatever.

   時には git リポジトリの変更履歴には入れたくない文を電子メールに
   含めたいことがあるだろう。例えば「これは Fred のツリーにすでに
   入っている」、「これは先週金曜のパッチのアップデート版だ」等々。

   You should place such text below the "^---" separator so that it is
   auto-removed when being placed into the revision control system.

   こういった文は "^---" セパレータの下に置いて、リビジョン管理
   システムの管理下に置かれるときには自動的に削除されるようにすべきだ。

5: The diff
5: 差分
===========

a) Patches should be in `patch -p1' form:

   パッチは以下のように `patch -p1' 形式で取られなければいけない -

  --- a/kernel/sched.c
  +++ b/kernel/sched.c

b) Make sure that your patches apply to the latest version of the kernel
   tree.  Either straight from Linus's git tree or from
   ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/

   パッチは最新バージョンのカーネルツリーに適用できるようにすること。
   直接 Linus の git ツリーを直接持ってくるか
   ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ から入手すること。

c) When raising patches for -mm kernels it's generally best to base them on
   the latest Linus tree.  I'll work out any rejects/incompatibilities.  There
   are of course exceptions to this.

   パッチを -mm カーネル向けに提出したい場合には一般的には最新の
   Linus ツリーを基準にするのがいちばん良い。リジェクトや非互換部分があれば
   私 (訳注: Andrew Morton) がなんとかする。もちろんこれには例外がある。

d) Ensure that your patch does not add new trailing whitespace.  The below
   script will fix up your patch by stripping off such whitespace.

   パッチで新たに行末の空白を増やすことがないように。以下のスクリプトは、
   そういった空白を取り去ってパッチを修正してくれる。

	#!/bin/sh

	strip1()
	{
		TMP=$(mktemp /tmp/XXXXXX)
		cp "$1" "$TMP"
		sed -e '/^+/s/[ 	]*$//' <"$TMP" >"$1"
		rm "$TMP"
	}

	for i in "$@"
	do
		strip1 "$i"
	done

6: Patch series
6: 一連のパッチ
===============

a) When sending a series of patches, number them in the Subject:s thusly:

   一連のパッチを投稿する場合は、Subject: に番号を振って以下のように
   すること -

	[patch 1/10] ext2: block allocation: frob the globnozzle
	[patch 2/10] ext2: block allocation: wash the pizza
	etc.

	([patch 1/10] ext2: ブロック割り当て: 放水口をつかんで
	 [patch 2/10] ext2: ブロック割り当て: ピザを洗う
         等々)

   (訳注: frob the globnozzle/wash the pizza の含意は、意味を持った
    順序付けをするということ、説明文をちゃんと書くこと (このようなばかげた
    文ではなく) といったところのようです)

b) Some people like to introduce a patch series with an introductory email
   which doesn't actually carry a patch, such as:

   一連のパッチが何に関する物かを説明するため、パッチを含まない
   以下のような前置きメールを好んで使う人がいる -

	[patch 0/10] ext2: block allocation changes
	([patch 0/10] ext2: ブロック割り当ての変更)

   Please don't do this.  There is no facility in the git tree to carry
   changelog-only changesets such as this (or at least, we don't do that) so
   the information in the introductory email will be lost.

  これはやらないでほしい。git ツリーにはこのような変更履歴だけの
  チェンジセットを扱う方法がない (少なくとも、我々はそのようにしていない)
  のでこの紹介メール内の情報は失われてしまう。

   So I end up copying and pasting your nice introduction into the
   changelog for the first patch, so it gets into git.  I'll follow it with
   the text

   だから私はこの素晴らしい導入部分を git に残すために最初のパッチの
   変更履歴の中にコピー&ペーストする羽目になる。その後ろに

	This patch:
	(このパッチは、)

   and then I'll include the changelog for the first patch of the series.

   という一節を加え、一連のパッチの最初の部分の変更履歴に繋げるのだ。

   It would be preferred if the patch originators were to do this.

   本当はパッチの作者がこうしてくれると好ましいのだが残念ながら
   そうはいっていない。

c) Try very hard to ensure that the kernel builds and runs correctly at
   every step of the patch series.  This requirement exists because of
   `git-bisect'.  If someone is doing a bisection search for a kernel bug and
   they land upon your won't-compile point partway through the exercise, they
   will be unhappy.

   とにかく一連のパッチの途中のどの段階でもカーネルビルドとカーネル動作が
   正しくできることを保証してほしい。これは `git-bisect' のために必要なのだ。
   もし誰かがカーネルバグの調査のために二分探索を行っている途中に
   誰かのせいでコンパイルできないような地点に当たったら気分が悪いだろう。

d) If your patch series includes non-runtime-affecting things such as
   cleanups, whitespace fixes, file renames, moving functions around, etc. then
   this work should be done in the initial patches in the series.  The
   functional changes should come later in the series.

   もし一連のパッチの中にクリーンアップや空白の修正やファイル名の
   変更や関数の移動など実行時に影響のないものを含んでいるのなら
   一連のパッチの最初でやるべきだ。機能的な変更はその後に来るべきだ。

   This is mainly so that reversion of problematic changes becomes simpler.

   これは主として問題が出た変更部分を元に戻すのを簡単にするためだ。

7: Overall
7: 全般的な事項
==========

a) Avoid MIME and attachements if possible.  Make sure that your email
   client does not wordwrap your patch.  Make sure that your email client does
   not replace tabs with spaces.

   MIME や添付をできるだけ避けること。メールクライアントがパッチの
   行を折り返したりしないようにすること。メールクライアントが
   タブを空白に置き換えないようにすること。

   Mail yourself a decent-sized patch and check that it still applies.

   自分宛てにそれなりの大きさのパッチを送って、ちゃんと適用できることを
   確認すること。

b) If all this still hopelessly fails then MIME attachments are an acceptable
   reluctant fallback.  You must ensure that the attached patches have
   text/plain mimetypes.

   もしこれらがどれもこれもどうしてもうまくいかない場合、MIME 添付が
   かろうじて許容可能な逃げ道だ。添付したパッチの MIMEタイプは text/plain に
   しなければいけない。

The patch management scripts at http://www.zip.com.au/~akpm/linux/patches/
implement all of the above.

http://www.zip.com.au/~akpm/linux/patches/ にあるパッチ管理スクリプトは
上記の全てを実装している。

The patch management tools at https://savannah.nongnu.org/projects/quilt/ also
implement all of the above.

https://savannah.nongnu.org/projects/quilt/ にあるパッチ管理ツールも上記の全てを
実装している。

Many example patches may be found under
ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/

数多くの参考となるパッチは以下のURLに置かれている。
ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/
