================================== これは、 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 校正者： Masanori Kobayashi さん ================================== 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 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: Signed-off-by: Andrew Morton --- 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/