完璧なパッチ

akpm@osdl.org

訳: MUNEDA Takahiro <mail address>
2005 05 05

訳者が追記した行をわかりやすくするために,行頭に縦棒を記してある.

この文章の最新版は以下の場所にある.
http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

和訳版の最新版は以下の場所にある.
http://mux03.panda64.net/docs/tpp_ja.html

http://linux.yyz.us/patch-format.html も見て欲しい.

内容

1: 送付

a) パッチはメール経由でのみ送られるものである.インターネットサーバからダウンロードさせられるのは苦痛である.

b) メール一通につき 1 つのパッチにすること.メールの本文に変更履歴を付けること.

2: 件名

a) メールの件名はメールに含まれているパッチについて簡潔に述べること.件名はファイル名であってはならない.一連のパッチそれぞれにおいて同じ件名を使ってはならない.

メール件名はそのパッチに対して世界で唯一の識別子となるようにすることを心にとどめておくこと.BitKeeper に取り込む時に広く広報される.件名は後々パッチを参照する開発者たちの議論において使われるかもしれない.人々はパッチに関連する議論を読むためにパッチの件名を Google で検索したくなるだろう.

b) 一連のパッチを投稿する時には,パッチの件名に連番を付けること.

c) パッチが影響を与えるサブシステムについての記述が含まれているのはよい.以下の例を見ること.

d) 件名の例

[patch 2/5] ext2: bitmap 検索性能の改善

e) 注意 何人かの人たちのパッチ受け取りスクリプトは,件名文章中の [ ] 括弧を取り除いてしまう.よって,パッチに関連しない,長くない用語の情報を括弧の中に記述するべきである.この情報には "patch" という単語と連番を含めること.なので,サブシステム識別子 (今回の場合 "ext2:") は括弧の外に記述すること.

3: 変更履歴

a) あなたが記す件名と変更履歴は永久的にカーネルの記録に広められることを心にとどめておくこと.誰かほかの開発者が数年後にあなたのパッチを変更履歴を読んで理解したくなるかもしれない.

そのため,変更履歴はパッチについて完全に記述すること:

b) パッチがどの版数のカーネルに適用すべきかなどと,わざわざ記述しないこと(たとえば "2.6.8-rc1 に適用すること").それは興味深い情報ではない

c) 新しい版のパッチの変更履歴を作成している時に,最新のパッチを参照しないこと. bitkeeper の変更履歴に "これは昨日いわれたことを修正するためのものである" などと書かれているのは全然役に立たない.繰り返しのパッチそれぞれに独立した変更履歴が記述されていなければならない.これは変更履歴を管理するパッチ管理システムが必要であることを意味する.以下を参照すること.

d) Signed-off-by: 行を追加すること.

e) 多くの人たちのパッチ受け取りスクリプトは ^--- 文字列を変更履歴とパッチ本体の間の区切りとして扱う.どんな diffstat 情報でもパッチが適用される時に破棄されることを保証されているとしてもよい.

Another few #if/#ifdef cleanups, this time for the PPC architecture.

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,

4: 差分

a) パッチは `patch -p1' 形式でなければならない.

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

b) パッチはかならず最新版のカーネルツリーに適用すること.bitkeeper から取得したままのものか,ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/からのもののどちらか.

c) -mm からパッチを作成した時は,最新版の Linus ツリーを基本としたパッチとするのが一般的には最もよい.パッチの適用拒否や不一致については私がうまくやる.もちろん例外はあるが.

d) パッチによって末尾に新しく空白を追加することが必ずないようにすること.以下のスクリプトはパッチからそのような空白を取り除いて直してくれる.

#!/bin/sh

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

for i in $*
do
	strip1 $i
done

5: 全般的

a) できるかぎり,MIME やファイルの添付を避けること.メールソフトがパッチの行送りをしないようにすること.メールソフトがタブをスペースに変換することがないようにすること.

スクリプト・ツール

http://www.zip.com.au/~akpm/linux/patches/ で手に入れられるパッチ管理スクリプトは以上のことをすべて実装している.

https://savannah.nongnu.org/projects/quilt/ で手に入れられるパッチ管理ツールもまた以上のことをすべて実装している.