Documentation / zh_CN / SubmittingPatches

Custom Search

Based on kernel version 2.6.33. Page generated on 2010-02-24 15:37 EST.

	Chinese translated version of Documentation/SubmittingPatches
	
	If you have any comment or update to the content, please contact the
	original document maintainer directly.  However, if you have a problem
	communicating in English you can also ask the Chinese maintainer for
	help.  Contact the Chinese maintainer if this translation is outdated
	or if there is a problem with the translation.
	
	Chinese maintainer: TripleX Chung <triplex[AT]zh-kernel[DOT]org>
	---------------------------------------------------------------------
	Documentation/SubmittingPatches 的中文翻译
	
	如果想评论或更新本文的内容，请直接�系原文档的维护者。如果你使用英文
	交�有困难的�，也�以�中文版维护者求助。如果本翻译更新��时或者翻
	译存在问题，请�系中文版维护者。
	
	中文版维护者： 钟宇 TripleX Chung <triplex[AT]zh-kernel[DOT]org>
	中文版翻译者： 钟宇 TripleX Chung <triplex[AT]zh-kernel[DOT]org>
	中文版校译者： �阳 Li Yang <leo[AT]zh-kernel[DOT]org>
	               王� Wang Cong <xiyou.wangcong[AT]gmail[DOT]com>
	
	以下为正文
	---------------------------------------------------------------------
	
	   如何让你的改动进入内核
	     或者
	  获得亲爱的 Linus Torvalds 的关注和处�
	----------------------------------
	
	对于想�将改动�交到 Linux 内核的个人或者公��说，如果�熟悉“规矩�，
	�交的�程会让人�惧。本文档收集了一系列建议，这些建议�以大大的�高你
	的改动被接�的机会。
	阅读 Documentation/SubmitChecklist �获得在�交代��需�检查的项目的列
	表。如果你在�交一个驱动程�，那么�时阅读一下
	Documentation/SubmittingDrivers 。
	
	
	--------------------------
	第一节 - 创建并��你的改动
	--------------------------
	
	1) "diff -up"
	-----------
	
	使用 "diff -up" 或者 "diff -uprN" �创建补�。
	
	所有内核的改动，都是以补�的形�呈现的，补�由 diff(1) 生�。创建补�的
	时候，�确认它是以 "unified diff" 格�创建的，这�格�由 diff(1) 的 '-u'
	�数生�。而且，请使用 '-p' �数，那样会显示�个改动所在的C函数，使得
	产生的补�容易读得多。补�应该基于内核�代�树的根目录，而�是里边的任
	何�目录。
	为一个�独的文件创建补�，一般�说这样�就够了：
	
	        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
	
	为多个文件创建补�，你�以解开一个没有修改过的内核�代�树，然�和你自
	己的代�树之间� diff 。例如：
	
	        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" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1)
	产生的补�里会被跳过。"dontdiff" 文件被包�在2.6.12和之�版本的内核�代
	�树中。对于更早的内核版本，你�以从
	<http://www.xenotime.net/linux/doc/dontdiff> 获�它。
	确定你的补�里没有包�任何�属于这次补��交的�外文件。记得在用diff(1)
	生�补�之�，审阅一次补�，以确�准确。
	如果你的改动很散乱，你应该研究一下如何将补�分割�独立的部分，将改动分
	割�一系列�乎逻辑的步骤。这样更容易让其他内核开�者审核，如果你想你的
	补�被接�，这是很��的。下�这些脚本能够帮助你�这件事情：
	Quilt:
	http://savannah.nongnu.org/projects/quilt
	
	Andrew Morton 的补�脚本:
	http://www.zip.com.au/~akpm/linux/patches/
	作为这些脚本的替代，quilt 是值得推�的补�管�工具(看上�的链接)。
	
	2)�述你的改动。
	�述你的改动包�的技术细节。
	
	�多具体就写多具体。最糟糕的�述�能是�下�这些语�：“更新了�驱动程
	��，“修正了�驱动程�的bug�，或者“这个补�包�了��系统的修改，请
	使用。�
	
	如果你的�述开始�长，这表示你也许需�拆分你的补�了，请看第3�节，
	继续。
	
	3)拆分你的改动
	
	将改动拆分，逻辑类似的放到�一个补�文件里。
	
	例如，如果你的改动里�时有bug修正和性能优化，那么把这些改动�分到两个或
	者更多的补�文件中。如果你的改动包�对API的修改，并且修改了驱动程��适
	应这些新的API，那么把这些修改分�两个补�。
	
	�一方�，如果你将一个�独的改动��多个补�文件，那么将它们�并�一个
	�独的补�文件。这样一个逻辑上�独的改动�被包�在一个补�文件里。
	
	如果有一个补��赖�外一个补��完�它的改动，那没问题。简�的在你的补
	��述里指出“这个补��赖�补��就好了。
	
	如果你�能将补�浓缩�更少的文件，那么�次大约��出15个，然�等待审查
	和整�。
	
	4)选择 e-mail 的收件人
	
	看一� MAINTAINERS 文件和�代�，看看你所的改动所在的内核�系统有没有指
	定的维护者。如果有，给他们�e-mail。
	
	如果没有找到维护者，或者维护者没有�馈，将你的补���到内核开�者主邮
	件列表 linux-kernel[AT]vger.kernel[DOT]org。大部分的内核开�者都跟踪这个邮件列
	表，�以评价你的改动。
	
	�次����超过15个补�到 vger 邮件列表���
	
	Linus Torvalds 是决定改动能�进入 Linux 内核的最终�决者。他的 e-mail
	地�是 <torvalds[AT]linux-foundation[DOT]org> 。他收到的 e-mail 很多，所以一般
	的说，最好别给他� e-mail。
	
	那些修正bug，“显而易��的修改或者是类似的�需�很少讨论的补��以直接
	��或者CC给Linus。那些需�讨论或者没有很清楚的好处的补�，一般先��到
	linux-kernel邮件列表。�有当补�被讨论得差�多了，��交给Linus。
	
	5)选择CC( e-mail 抄�)列表
	
	除�你有�由�这样�，�则CC linux-kernel[AT]vger.kernel[DOT]org。
	
	除了 Linus 之外，其他内核开�者也需�注�到你的改动，这样他们�能评论你
	的改动并�供代�审查和建议。linux-kernel 是 Linux 内核开�者主邮件列表
	。其它的邮件列表为特定的�系统�供�务，比如 USB，framebuffer 设备，虚
	拟文件系统，SCSI �系统，等等。查看 MAINTAINERS 文件�获得和你的改动有
	关的邮件列表。
	
	Majordomo lists of VGER.KERNEL.ORG at:
	        <http://vger.kernel.org/vger-lists.html>
	
	如果改动影�了用户空间和内核之间的接�，请给 MAN-PAGES 的维护者（列在
	MAITAINERS 文件里的）��一个手册页（man-pages）补�，或者至少通知一下改
	�，让一些信�有途径进入手册页。
	
	�使在第四步的时候，维护者没有作出回应，也�确认在修改他们的代�的时候
	，一直将维护者拷�到CC列表中。
	
	对于�的补�，你也许会CC到 Adrian Bunk 管�的�集�碎补�的邮件列表
	(Trivial Patch Monkey)trivial[AT]kernel[DOT]org，那里专门收集�碎的补�。下�这样
	的补�会被看作“�碎的�补�：
	  文档的拼写修正。
	  修正会影�到 grep(1) 的拼写。
	  警告信�修正(频�的打�无用的警告是�好的。)
	  编译错误修正（代�逻辑的确是对的，�是编译有问题。）
	  �行时修正（��真的修正了错误。）
	  移除使用了被废弃的函数/�的代�(例如 check_region。)
	  �系方�和文档修正。
	  用�移�的代�替���移�的代�（�使在体系结构相关的代�中，既然有
	  人拷�，��它是�碎的）
	  任何文件的作者/维护者对该文件的改动（例如 patch monkey 在�传模�下）
	
	URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/>
	
	(译注，关于“�碎补��的一些说明：因为原文的这一部分写得比较简�，所以�得�
	�例写一下译注。"trivial"这个英文��的本�是“�碎的，���的。�但是在这里
	有�微有一些�化，例如对一些明显的NULL指针的修正，属于�行时修正，会被归类
	到�碎补�里。虽然NULL指针的修正很��，但是这样的修正往往很�而且很容易得到
	检验，所以也被归入�碎补�。�碎补�更精确的归类应该是
	“simple, localized & easy to verify�，也就是说简�的，局部的和易于检验的。
	trivial[AT]kernel[DOT]org邮件列表的目的是针对这样的补�，为�交者�供一个中心，�
	�低�交的门槛。)
	
	6)没有 MIME 编�，没有链接，没有压缩，没有附件，�有纯文本。
	
	Linus 和其他的内核开�者需�阅读和评论你�交的改动。对于内核开�者�说
	，�以“引用�你的改动很��，使用一般的 e-mail 工具，他们就�以在你的
	代�的任何�置添加评论。
	
	因为这个原因，所有的�交的补�都是 e-mail 中“内嵌�的。
	警告：如果你使用剪切-粘贴你的补�，�心你的编辑器的自动�行功能破�你的
	补�。
	
	��将补�作为 MIME 编�的附件，�管是�压缩。很多�行的 e-mail 软件�
	是任何时候都将 MIME 编�的附件当作纯文本��的，这会使得别人无法在你的
	代�中加评论。�外，MIME 编�的附件会让 Linus 多花一点时间�处�，这就
	�低了你的改动被接�的�能性。
	
	警告：一些邮件软件，比如 Mozilla 会将你的信�以如下格���：
	---- 邮件头 ----
	Content-Type: text/plain; charset=us-ascii; format=flowed
	---- 邮件头 ----
	问题在于 “format=flowed� 会让接收端的�些邮件软件将邮件中的制表符替�
	�空格以��一些类似的替�。这样，你��的时候看起�没问题的补�就被破
	�了。
	
	�修正这个问题，�需�将你的 mozilla 的 defaults/pref/mailnews.js 文件
	里的
	pref("mailnews.send_plaintext_flowed", false); // RFC 2646=======
	修改�
	pref("mailnews.display.disable_format_flowed_support", true);
	就�以了。
	
	7) e-mail 的大�
	
	给 Linus ��补�的时候，永远按照第6�节说的�。
	
	大的改动对邮件列表��适，对�些维护者也��适。如果你的补�，在�压缩
	的情况下，超过了40kB，那么你最好将补�放在一个能通过 internet 访问的�
	务器上，然�用指�你的补�的 URL 替代。
	
	8) 指出你的内核版本
	
	在标题和在补�的�述中，指出补�对应的内核的版本，是很��的。
	
	如果补��能干净的在最新版本的内核上打上，Linus 是�会接�它的。
	
	9) ��气�，继续�交。
	
	当你�交了改动以�，�心地等待。如果 Linus 喜欢你的改动并且��它，那么
	它将在下一个内核�布版本中出现。
	
	然而，如果你的改动没有出现在下一个版本的内核中，�能有若干原因。�少那
	些原因，修正错误，�新�交更新�的改动，是你自己的工作。
	
	Linus�给出任何评论就“丢弃�你的补�是常�的事情。在系统中这样的事情很
	平常。如果他没有接�你的补�，也许是由于以下原本：
	* 你的补��能在最新版本的内核上干净的打上。
	* 你的补�在 linux-kernel 邮件列表中没有得到充分的讨论。
	* 风格问题（�照第2�节）
	* 邮件格�问题（�读本节）
	* 你的改动有技术问题。
	* 他收到了��的 e-mail，而你的在混乱中丢失了。
	* 你让人为难。
	
	有疑问的时候，在 linux-kernel 邮件列表上请求评论。
	
	10) 在标题上加上 PATCH 的字样
	
	Linus 和 linux-kernel 邮件列表的 e-mail ��都很高，一个通常的约定是标
	题行以 [PATCH] 开头。这样�以让 Linus 和其他内核开�人员�以从 e-mail
	的讨论中很轻易的将补�分辨出�。
	
	11）为你的工作签�
	
	为了加强对��了何事的追踪，尤其是对那些�过好几层的维护者的补�，我们
	建议在��出去的补�上加一个 “sign-off� 的过程。
	
	"sign-off" 是在补�的注释的最�的简�的一行文字，认�你编写了它或者其他
	人有�力将它作为开放�代�的补�传递。规则很简�：如果你能认�如下信�
	：
	      开�者���书 1.1
	      对于本项目的贡献，我认�如下信�：
	      （a）这些贡献是完全或者部分的由我创建，我有�利以文件中指出
	       的开放�代�许���交它；或者
	      （b）这些贡献基于以�的工作，�我所知，这些以�的工作��当的开放
	       �代�许���护，而且，根�许��，我有��交修改�的贡献，
	       无论是完全还是部分由我创造，这些贡献都使用�一个开放�代�许��
	       （除�我被�许用其它的许��），正如文件中指出的；或者
	      （c）这些贡献由认�（a），（b）或者（c）的人直接�供给我，而
	       且我没有修改它。
	      （d）我�解并��这个项目和贡献是公开的，贡献的记录（包括我
	       一起�交的个人记录，包括 sign-off ）被永久维护并且�以和这个项目
	       或者开放�代�的许���步地��行。
	       那么加入这样一行：
	       Signed-off-by: Random J Developer <random[AT]developer.example[DOT]org>
	
	使用你的真�（抱歉，�能使用��或者匿�。）
	
	有人在最�加上标签。现在这些东西会被忽略，但是你�以这样�，�标记公�
	内部的过程，或者�是指出关于 sign-off 的一些特殊细节。
	
	12）标准补�格�
	
	标准的补�，标题行是：
	    Subject: [PATCH 001/123] �系统:一��概述
	
	标准补�的信体存在如下部分：
	
	  - 一个 "from" 行指出补�作者。
	
	  - 一个空行
	
	  - 说明的主体，这些说明文字会被拷�到�述该补�的永久改动记录里。
	
	  - 一个由"---"构�的标记行
	
	  - ��适放到改动记录里的�外的注解。
	
	  - 补�本身（diff 输出）
	
	标题行的格�，使得对标题行按字��排��常的容易 - 很多 e-mail 客户端都
	�以支� - 因为�列�是用零填充的，所以按数字排�和按字�排�是一样的。
	
	e-mail 标题中的“�系统�标识哪个内核�系统将被打补�。
	
	e-mail 标题中的“一��概述�扼�的�述 e-mail 中的补�。“一��概述�
	�应该是一个文件�。对于一个补�系列（“补�系列�指一系列的多个相关补
	�），��对�个补�都使用�样的“一��概述�。
	
	记� e-mail 的“一��概述�会�为该补�的全局唯一标识。它会蔓延到 git
	的改动记录里。然�“一��概述�会被用在开�者的讨论里，用�指代这个补
	�。用户将希望通过 google ��索"一��概述"�找到那些讨论这个补�的文
	章。
	
	一些标题的例�：
	
	    Subject: [patch 2/5] ext2: improve scalability of bitmap searching
	    Subject: [PATCHv2 001/207] x86: fix eflags tracking
	
	"from" 行是信体里的最上�一行，具有如下格�：
	        From: Original Author <author[AT]example[DOT]com>
	
	"from" 行指明在永久改动日志里，�会被确认为作者。如果没有 "from" 行，那
	么邮件头里的 "From: " 行会被用�决定改动日志中的作者。
	
	说明的主题将会被�交到永久的�代�改动日志里，因此对那些早已��记得和
	这个补�相关的讨论细节的有能力的读者�说，是有�义的。
	
	"---" 标记行对于补�处�工具�找到哪里是改动日志信�的结�，是��缺少
	的。
	
	对于 "---" 标记之�的�外注解，一个好的用途就是用�写 diffstat，用�显
	示修改了什么文件和�个文件都增加和删除了多少行。diffstat 对于比较大的补
	�特别有用。其余那些�是和时刻或者开�者相关的注解，��适放到永久的改
	动日志里的，也应该放这里。
	使用 diffstat的选项 "-p 1 -w 70" 这样文件�就会从内核�代�树的目录开始
	，�会�用太宽的空间（很容易适�80列的宽度，也许会有一些缩进。）
	
	在��的�考资料中能看到适当的补�格�的更多细节。
	
	-------------------------------
	第二节 �示，建议和诀�
	-------------------------------
	
	本节包�很多和�交到内核的代�有关的通常的"规则"。事情永远有例外...但是
	你必须真的有好的�由这样�。你�以把本节��Linus的计算机科学入门课。
	
	1) 读 Document/CodingStyle
	
	Nuff 说过，如果你的代�和这个�离太多，那么它有�能会被拒�，没有更多的
	审查，没有更多的评价。
	
	2) #ifdef 是丑陋的
	混�了 ifdef 的代�难以阅读和维护。别这样�。作为替代，将你的 ifdef 放
	在头文件里，有�件地定义 "static inline" 函数，或者�，在代�里用这些东
	西。让编译器把那些"空�作"优化掉。
	
	一个简�的例�，�好的代�：
	
	    dev = alloc_etherdev (sizeof(struct funky_private));
	    if (!dev)
	        return -ENODEV;
	    #ifdef CONFIG_NET_FUNKINESS
	    init_funky_net(dev);
	    #endif
	
	清��的例�:
	
	(头文件里)
	    #ifndef CONFIG_NET_FUNKINESS
	    static inline void init_funky_net (struct net_device *d) {}
	    #endif
	
	(代�文件里)
	    dev = alloc_etherdev (sizeof(struct funky_private));
	    if (!dev)
	        return -ENODEV;
	    init_funky_net(dev);
	
	3) 'static inline' 比�好
	
	Static inline 函数相比��说，是好得多的选择。Static inline 函数�供了
	类型安全，没有长度�制，没有格��制，在 gcc 下开销和�一样�。
	
	��在 static inline 函数�是最优的时候[在 fast paths 里有很少的独立的
	案例]，或者��能用 static inline 函数的时候[例如字符串分�]。
	应该用 'static inline' 而�是 'static __inline__', 'extern inline' 和
	'extern __inline__' 。
	
	4) ��过度设计
	
	��试图预计模糊的未�事情，这些事情也许有用也许没有用："让事情尽�能的
	简�，而�是更简�"。
	
	----------------
	第三节 �考文献
	----------------
	
	Andrew Morton, "The perfect patch" (tpp).
	  <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt>
	
	Jeff Garzik, "Linux kernel patch submission format".
	  <http://linux.yyz.us/patch-format.html>
	
	Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
	  <http://www.kroah.com/log/2005/03/31/>
	  <http://www.kroah.com/log/2005/07/08/>
	  <http://www.kroah.com/log/2005/10/19/>
	  <http://www.kroah.com/log/2006/01/11/>
	
	NO!!!! No more huge patch bombs to linux-kernel[AT]vger.kernel[DOT]org people!
	  <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2>
	
	Kernel Documentation/CodingStyle:
	  <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle>
	
	Linus Torvalds's mail on the canonical patch format:
	  <http://lkml.org/lkml/2005/4/7/183>
	--

• [ zh_CN ]
• CodingStyle
• HOWTO
• oops-tracing.txt
• sparse.txt
• stable_api_nonsense.txt
• stable_kernel_rules.txt
• SubmittingDrivers
• SubmittingPatches
• volatile-considered-harmful.txt
•