From: Alex Shi Date: Mon, 1 Apr 2019 14:44:45 +0000 (+0800) Subject: docs/zh_CN: update to latest submitting-patches.rst X-Git-Url: http://git.cdn.openwrt.org/?a=commitdiff_plain;h=62130affd7b30cce7f67f066922def351ba31aa4;p=openwrt%2Fstaging%2Fblogic.git docs/zh_CN: update to latest submitting-patches.rst Updated huge changes for this docs. Seems we forget this for decades. And use local stub to pointer this Chinese docs. Signed-off-by: Alex Shi Cc: Harry Wei Cc: Jonathan Corbet Cc: Tom Levy Cc: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Signed-off-by: Jonathan Corbet --- diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index 1bd64832b424..5fa716584598 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -1,4 +1,4 @@ -.. _cn_process_submittingpatches: +.. _cn_submittingpatches: .. include:: ../disclaimer-zh_CN.rst @@ -19,15 +19,34 @@ 对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”， 提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你 -的改动被接受的机会。 -阅读 Documentation/process/submit-checklist.rst 来获得在提交代码前需要检查的项目的列 -表。如果你在提交一个驱动程序，那么同时阅读一下 -Documentation/process/submitting-drivers.rst 。 +的改动被接受的机会. +以下文档含有大量简洁的建议， 具体请见： +:ref:`Documentation/process ` +同样，:ref:`Documentation/process/submit-checklist.rst ` +给出在提交代码前需要检查的项目的列表。如果你在提交一个驱动程序，那么 +同时阅读一下: +:ref:`Documentation/process/submitting-drivers.rst ` ---------------------------- -第一节 - 创建并发送你的改动 ---------------------------- +其中许多步骤描述了Git版本控制系统的默认行为；如果您使用Git来准备补丁， +您将发现它为您完成的大部分机械工作，尽管您仍然需要准备和记录一组合理的 +补丁。一般来说，使用git将使您作为内核开发人员的生活更轻松。 + + +0) 获取当前源码树 +----------------- + +如果您没有一个可以使用当前内核源代码的存储库，请使用git获取一个。您将要 +从主线存储库开始，它可以通过以下方式获取:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +但是，请注意，您可能不希望直接针对主线树进行开发。大多数子系统维护人员运 +行自己的树，并希望看到针对这些树准备的补丁。请参见MAINTAINERS文件中子系 +统的 **T:** 项以查找该树，或者简单地询问维护者该树是否未在其中列出。 + +仍然可以通过tarballs下载内核版本（如下一节所述），但这是进行内核开发的 +一种困难的方式。 1) "diff -up" ------------- @@ -39,9 +58,10 @@ Documentation/process/submitting-drivers.rst 。 参数生成。而且，请使用 '-p' 参数，那样会显示每个改动所在的C函数，使得 产生的补丁容易读得多。补丁应该基于内核源代码树的根目录，而不是里边的任 何子目录。 + 为一个单独的文件创建补丁，一般来说这样做就够了:: - SRCTREE=linux-2.6 + SRCTREE=linux MYFILE=drivers/net/mydriver.c cd $SRCTREE @@ -53,38 +73,103 @@ Documentation/process/submitting-drivers.rst 。 为多个文件创建补丁，你可以解开一个没有修改过的内核源代码树，然后和你自 己的代码树之间做 diff 。例如:: - MYSRC=/devel/linux-2.6 + MYSRC=/devel/linux - 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 + tar xvfz linux-3.19.tar.gz + mv linux-3.19 linux-3.19-vanilla + diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ + linux-3.19-vanilla $MYSRC > /tmp/patch "dontdiff" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1) -产生的补丁里会被跳过。"dontdiff" 文件被包含在2.6.12和之后版本的内核源代 -码树中。对于更早的内核版本，你可以从 - 获取它。 +产生的补丁里会被跳过。 + 确定你的补丁里没有包含任何不属于这次补丁提交的额外文件。记得在用diff(1) 生成补丁之后，审阅一次补丁，以确保准确。 + 如果你的改动很散乱，你应该研究一下如何将补丁分割成独立的部分，将改动分 割成一系列合乎逻辑的步骤。这样更容易让其他内核开发者审核，如果你想你的 -补丁被接受，这是很重要的。下面这些脚本能够帮助你做这件事情： -Quilt: -http://savannah.nongnu.org/projects/quilt +补丁被接受，这是很重要的。请参阅： +:ref:`cn_split_changes` + +如果你用 ``git`` , ``git rebase -i`` 可以帮助你这一点。如果你不用 ``git``, +``quilt`` 另外一个流行的选择。 + +.. _cn_describe_changes: + +2) 描述你的改动 +--------------- + +描述你的问题。无论您的补丁是一行错误修复还是5000行新功能，都必须有一个潜在 +的问题激励您完成这项工作。让审稿人相信有一个问题值得解决，让他们读完第一段 +是有意义的。 + +描述用户可见的影响。直接崩溃和锁定是相当有说服力的，但并不是所有的错误都那么 +明目张胆。即使在代码审查期间发现了这个问题，也要描述一下您认为它可能对用户产 +生的影响。请记住，大多数Linux安装运行的内核来自二级稳定树或特定于供应商/产品 +的树，只从上游精选特定的补丁，因此请包含任何可以帮助您将更改定位到下游的内容： +触发的场景、DMESG的摘录、崩溃描述、性能回归、延迟尖峰、锁定等。 + +量化优化和权衡。如果您声称在性能、内存消耗、堆栈占用空间或二进制大小方面有所 +改进，请包括支持它们的数字。但也要描述不明显的成本。优化通常不是免费的，而是 +在CPU、内存和可读性之间进行权衡；或者，探索性的工作，在不同的工作负载之间进 +行权衡。请描述优化的预期缺点，以便审阅者可以权衡成本和收益。 + +一旦问题建立起来，就要详细地描述一下您实际在做什么。对于审阅者来说，用简单的 +英语描述代码的变化是很重要的，以验证代码的行为是否符合您的意愿。 + +如果您将补丁描述写在一个表单中，这个表单可以很容易地作为“提交日志”放入Linux +的源代码管理系统git中，那么维护人员将非常感谢您。见 :ref:`cn_explicit_in_reply_to`. + +每个补丁只解决一个问题。如果你的描述开始变长，这就表明你可能需要拆分你的补丁。 +请见 :ref:`cn_split_changes` + +提交或重新提交修补程序或修补程序系列时，请包括完整的修补程序说明和理由。不要 +只说这是补丁（系列）的第几版。不要期望子系统维护人员引用更早的补丁版本或引用 +URL来查找补丁描述并将其放入补丁中。也就是说，补丁（系列）及其描述应该是独立的。 +这对维护人员和审查人员都有好处。一些评审者可能甚至没有收到补丁的早期版本。 + +描述你在命令语气中的变化，例如“make xyzzy do frotz”而不是“[这个补丁]make +xyzzy do frotz”或“[我]changed xyzzy to do frotz”，就好像你在命令代码库改变 +它的行为一样。 + +如果修补程序修复了一个记录的bug条目，请按编号和URL引用该bug条目。如果补丁来 +自邮件列表讨论，请给出邮件列表存档的URL；使用带有 ``Message-ID`` 的 +https://lkml.kernel.org/ 重定向，以确保链接不会过时。 + +但是，在没有外部资源的情况下，尽量让你的解释可理解。除了提供邮件列表存档或 +bug的URL之外，还要总结需要提交补丁的相关讨论要点。 + +如果您想要引用一个特定的提交，不要只引用提交的 SHA-1 ID。还请包括提交的一行 +摘要，以便于审阅者了解它是关于什么的。例如:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + +您还应该确保至少使用前12位 SHA-1 ID. 内核存储库包含*许多*对象，使与较短的ID +发生冲突的可能性很大。记住，即使现在不会与您的六个字符ID发生冲突，这种情况 +可能五年后改变。 + +如果修补程序修复了特定提交中的错误，例如，使用 ``git bisct`` ，请使用带有前 +12个字符SHA-1 ID 的"Fixes:"标记和单行摘要。为了简化不要将标记拆分为多个， +行、标记不受分析脚本“75列换行”规则的限制。例如:: -2)描述你的改动。 -描述你的改动包含的技术细节。 + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") -要多具体就写多具体。最糟糕的描述可能是像下面这些语句：“更新了某驱动程 -序”，“修正了某驱动程序的bug”，或者“这个补丁包含了某子系统的修改，请 -使用。” +下列 ``git config`` 设置可以添加让 ``git log``, ``git show`` 漂亮的显示格式:: -如果你的描述开始变长，这表示你也许需要拆分你的补丁了，请看第3小节， -继续。 + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") -3)拆分你的改动 +.. _cn_split_changes: -将改动拆分，逻辑类似的放到同一个补丁文件里。 +3) 拆分你的改动 +--------------- + +将每个逻辑更改分隔成一个单独的补丁。 例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或 者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适 @@ -96,64 +181,94 @@ http://savannah.nongnu.org/projects/quilt 如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。简单的在你的补 丁描述里指出“这个补丁依赖某补丁”就好了。 +在将您的更改划分为一系列补丁时，要特别注意确保内核在系列中的每个补丁之后 +都能正常构建和运行。使用 ``git bisect`` 来追踪问题的开发者可能会在任何时 +候分割你的补丁系列；如果你在中间引入错误，他们不会感谢你。 + 如果你不能将补丁浓缩成更少的文件，那么每次大约发送出15个，然后等待审查 -和整合。 +和集成。 + +4) 检查你的更改风格 +------------------- + +检查您的补丁是否存在基本样式冲突，详细信息可在 +:ref:`Documentation/process/coding-style.rst ` +中找到。如果不这样做，只会浪费审稿人的时间，并且会导致你的补丁被拒绝，甚至 +可能没有被阅读。 + +一个重要的例外是在将代码从一个文件移动到另一个文件时——在这种情况下，您不应 +该在移动代码的同一个补丁中修改移动的代码。这清楚地描述了移动代码和您的更改 +的行为。这大大有助于审查实际差异，并允许工具更好地跟踪代码本身的历史。 + +在提交之前，使用补丁样式检查程序检查补丁（scripts/check patch.pl）。不过， +请注意，样式检查程序应该被视为一个指南，而不是作为人类判断的替代品。如果您 +的代码看起来更好，但有违规行为，那么最好不要使用它。 + +检查者报告三个级别： -4)选择 e-mail 的收件人 + - ERROR：很可能出错的事情 + - WARNING：需要仔细审查的事项 + - CHECK：需要思考的事情 -看一遍 MAINTAINERS 文件和源代码，看看你所的改动所在的内核子系统有没有指 -定的维护者。如果有，给他们发e-mail。 +您应该能够判断您的补丁中存在的所有违规行为。 -如果没有找到维护者，或者维护者没有反馈，将你的补丁发送到内核开发者主邮 -件列表 linux-kernel@vger.kernel.org。大部分的内核开发者都跟踪这个邮件列 -表，可以评价你的改动。 +5) 选择补丁收件人 +----------------- -每次不要发送超过15个补丁到 vger 邮件列表！！！ +您应该总是在任何补丁上复制相应的子系统维护人员，以获得他们维护的代码；查看 +维护人员文件和源代码修订历史记录，以了解这些维护人员是谁。脚本 +scripts/get_Maintainer.pl在这个步骤中非常有用。如果您找不到正在工作的子系统 +的维护人员，那么Andrew Morton（akpm@linux-foundation.org）将充当最后的维护 +人员。 + +您通常还应该选择至少一个邮件列表来接收补丁集的。linux-kernel@vger.kernel.org +作为最后一个解决办法的列表，但是这个列表上的体积已经引起了许多开发人员的拒绝。 +在MAINTAINERS文件中查找子系统特定的列表；您的补丁可能会在那里得到更多的关注。 +不过，请不要发送垃圾邮件到无关的列表。 + +许多与内核相关的列表托管在vger.kernel.org上；您可以在 +http://vger.kernel.org/vger-lists.html 上找到它们的列表。不过，也有与内核相关 +的列表托管在其他地方。 + +不要一次发送超过15个补丁到vger邮件列表！！！！ Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他的 e-mail 地址是 。他收到的 e-mail 很多，所以一般 的说，最好别给他发 e-mail。 -那些修正bug，“显而易见”的修改或者是类似的只需要很少讨论的补丁可以直接 -发送或者CC给Linus。那些需要讨论或者没有很清楚的好处的补丁，一般先发送到 -linux-kernel邮件列表。只有当补丁被讨论得差不多了，才提交给Linus。 +如果您有修复可利用安全漏洞的补丁，请将该补丁发送到 security@kernel.org。对于 +严重的bug，可以考虑短期暂停以允许分销商向用户发布补丁；在这种情况下，显然不应 +将补丁发送到任何公共列表。 -5)选择CC( e-mail 抄送)列表 +修复已发布内核中严重错误的补丁程序应该指向稳定版维护人员，方法是放这样的一行:: -除非你有理由不这样做，否则CC linux-kernel@vger.kernel.org。 + Cc: stable@vger.kernel.org -除了 Linus 之外，其他内核开发者也需要注意到你的改动，这样他们才能评论你 -的改动并提供代码审查和建议。linux-kernel 是 Linux 内核开发者主邮件列表 -。其它的邮件列表为特定的子系统提供服务，比如 USB，framebuffer 设备，虚 -拟文件系统，SCSI 子系统，等等。查看 MAINTAINERS 文件来获得和你的改动有 -关的邮件列表。 +进入补丁的签准区（注意，不是电子邮件收件人）。除了这个文件之外，您还应该阅读 +:ref:`Documentation/process/stable-kernel-rules.rst ` -Majordomo lists of VGER.KERNEL.ORG at: - +但是，请注意，一些子系统维护人员希望得出他们自己的结论，即哪些补丁应该被放到 +稳定的树上。尤其是网络维护人员，不希望看到单个开发人员在补丁中添加像上面这样 +的行。 -如果改动影响了用户空间和内核之间的接口，请给 MAN-PAGES 的维护者（列在 -MAINTAINERS 文件里的）发送一个手册页（man-pages）补丁，或者至少通知一下改 -变，让一些信息有途径进入手册页。 +如果更改影响到用户和内核接口，请向手册页维护人员（如维护人员文件中所列）发送 +手册页补丁，或至少发送更改通知，以便一些信息进入手册页。还应将用户空间API +更改复制到 linux-api@vger.kernel.org。 -即使在第四步的时候，维护者没有作出回应，也要确认在修改他们的代码的时候 -，一直将维护者拷贝到CC列表中。 +对于小的补丁，你也许会CC到搜集琐碎补丁的邮件列表(Trivial Patch Monkey) +trivial@kernel.org，那里专门收集琐碎的补丁。下面这样的补丁会被看作“琐碎的” +补丁： -对于小的补丁，你也许会CC到 Adrian Bunk 管理的搜集琐碎补丁的邮件列表 -(Trivial Patch Monkey)trivial@kernel.org，那里专门收集琐碎的补丁。下面这样 -的补丁会被看作“琐碎的”补丁： - - 文档的拼写修正。 - 修正会影响到 grep(1) 的拼写。 - 警告信息修正(频繁的打印无用的警告是不好的。) - 编译错误修正（代码逻辑的确是对的，只是编译有问题。） - 运行时修正（只要真的修正了错误。） - 移除使用了被废弃的函数/宏的代码(例如 check_region。) - 联系方式和文档修正。 - 用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有 - 人拷贝，只要它是琐碎的） - 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下） - -EMAIL: trivial@kernel.org + - 文档的拼写修正。 + - 修正会影响到 grep(1) 的拼写。 + - 警告信息修正(频繁的打印无用的警告是不好的。) + - 编译错误修正（代码逻辑的确是对的，只是编译有问题。） + - 运行时修正（只要真的修正了错误。） + - 移除使用了被废弃的函数/宏的代码(例如 check_region。) + - 联系方式和文档修正。 + - 用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有 + - 人拷贝，只要它是琐碎的） + - 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下） (译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不 违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里 @@ -164,100 +279,92 @@ EMAIL: trivial@kernel.org trivial@kernel.org邮件列表的目的是针对这样的补丁，为提交者提供一个中心，来 降低提交的门槛。) -6)没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本。 +6) 没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本 +----------------------------------------------------------- Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说 ，可以“引用”你的改动很重要，使用一般的 e-mail 工具，他们就可以在你的 代码的任何位置添加评论。 因为这个原因，所有的提交的补丁都是 e-mail 中“内嵌”的。 -警告：如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的 -补丁。 + +.. warning:: + 如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的补丁 不要将补丁作为 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); -就可以了。 +例外：如果你的邮递员弄坏了补丁，那么有人可能会要求你使用mime重新发送补丁 -7) e-mail 的大小 +请参阅 :ref:`Documentation/process/e-mail-clients.rst ` +以获取有关配置电子邮件客户端以使其不受影响地发送修补程序的提示。 -给 Linus 发送补丁的时候，永远按照第6小节说的做。 +7) e-mail 的大小 +---------------- 大的改动对邮件列表不合适，对某些维护者也不合适。如果你的补丁，在不压缩 -的情况下，超过了40kB，那么你最好将补丁放在一个能通过 internet 访问的服 -务器上，然后用指向你的补丁的 URL 替代。 +的情况下，超过了300kB，那么你最好将补丁放在一个能通过 internet 访问的服 +务器上，然后用指向你的补丁的 URL 替代。但是请注意，如果您的补丁超过了 +300kb，那么它几乎肯定需要被破坏。 -8) 指出你的内核版本 +8）回复评审意见 +--------------- -在标题和在补丁的描述中，指出补丁对应的内核的版本，是很重要的。 +你的补丁几乎肯定会得到评审者对补丁改进方法的评论。您必须对这些评论作出 +回应；让补丁被忽略的一个好办法就是忽略审阅者的意见。不会导致代码更改的 +意见或问题几乎肯定会带来注释或变更日志的改变，以便下一个评审者更好地了解 +正在发生的事情。 -如果补丁不能干净的在最新版本的内核上打上，Linus 是不会接受它的。 +一定要告诉审稿人你在做什么改变，并感谢他们的时间。代码审查是一个累人且 +耗时的过程，审查人员有时会变得暴躁。即使在这种情况下，也要礼貌地回应并 +解决他们指出的问题。 -9) 不要气馁，继续提交。 +9）不要泄气或不耐烦 +------------------- -当你提交了改动以后，耐心地等待。如果 Linus 喜欢你的改动并且同意它，那么 -它将在下一个内核发布版本中出现。 +提交更改后，请耐心等待。审阅者是忙碌的人，可能无法立即访问您的修补程序。 -然而，如果你的改动没有出现在下一个版本的内核中，可能有若干原因。减少那 -些原因，修正错误，重新提交更新后的改动，是你自己的工作。 +曾几何时，补丁曾在没有评论的情况下消失在空白中，但开发过程比现在更加顺利。 +您应该在一周左右的时间内收到评论；如果没有收到评论，请确保您已将补丁发送 +到正确的位置。在重新提交或联系审阅者之前至少等待一周-在诸如合并窗口之类的 +繁忙时间可能更长。 -Linus不给出任何评论就“丢弃”你的补丁是常见的事情。在系统中这样的事情很 -平常。如果他没有接受你的补丁，也许是由于以下原因： -* 你的补丁不能在最新版本的内核上干净的打上。 -* 你的补丁在 linux-kernel 邮件列表中没有得到充分的讨论。 -* 风格问题（参照第2小节） -* 邮件格式问题（重读本节） -* 你的改动有技术问题。 -* 他收到了成吨的 e-mail，而你的在混乱中丢失了。 -* 你让人为难。 +10）主题中包含 PATCH +-------------------- -有疑问的时候，在 linux-kernel 邮件列表上请求评论。 +由于到linus和linux内核的电子邮件流量很高，通常会在主题行前面加上[PATCH] +前缀. 这使Linus和其他内核开发人员更容易将补丁与其他电子邮件讨论区分开。 -10) 在标题上加上 PATCH 的字样 - -Linus 和 linux-kernel 邮件列表的 e-mail 流量都很高，一个通常的约定是标 -题行以 [PATCH] 开头。这样可以让 Linus 和其他内核开发人员可以从 e-mail -的讨论中很轻易的将补丁分辨出来。 - -11）为你的工作签名 +11）签署你的作品-开发者原始认证 +------------------------------- 为了加强对谁做了何事的追踪，尤其是对那些透过好几层的维护者的补丁，我们 建议在发送出去的补丁上加一个 “sign-off” 的过程。 "sign-off" 是在补丁的注释的最后的简单的一行文字，认证你编写了它或者其他 -人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息 -： +人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息: + 开发者来源证书 1.1 ^^^^^^^^^^^^^^^^^^ + 对于本项目的贡献，我认证如下信息： （a）这些贡献是完全或者部分的由我创建，我有权利以文件中指出 - 的开放源代码许可证提交它；或者 + 的开放源代码许可证提交它；或者 （b）这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放 - 源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献， - 无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证 - （除非我被允许用其它的许可证），正如文件中指出的；或者 + 源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献， + 无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证 + （除非我被允许用其它的许可证），正如文件中指出的；或者 （c）这些贡献由认证（a），（b）或者（c）的人直接提供给我，而 - 且我没有修改它。 + 且我没有修改它。 （d）我理解并同意这个项目和贡献是公开的，贡献的记录（包括我 - 一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目 - 或者开放源代码的许可证同步地再发行。 - 那么加入这样一行： + 一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目 + 或者开放源代码的许可证同步地再发行。 + +那么加入这样一行:: + Signed-off-by: Random J Developer 使用你的真名（抱歉，不能使用假名或者匿名。） @@ -265,24 +372,141 @@ Linus 和 linux-kernel 邮件列表的 e-mail 流量都很高，一个通常的 有人在最后加上标签。现在这些东西会被忽略，但是你可以这样做，来标记公司 内部的过程，或者只是指出关于 sign-off 的一些特殊细节。 +如果您是子系统或分支维护人员，有时需要稍微修改收到的补丁，以便合并它们， +因为树和提交者中的代码不完全相同。如果你严格遵守规则（c），你应该要求提交者 +重新发布，但这完全是在浪费时间和精力。规则（b）允许您调整代码，但是更改一个 +提交者的代码并让他认可您的错误是非常不礼貌的。要解决此问题，建议在最后一个 +由签名行和您的行之间添加一行，指示更改的性质。虽然这并不是强制性的，但似乎 +在描述前加上您的邮件和/或姓名（全部用方括号括起来），这足以让人注意到您对最 +后一分钟的更改负有责任。例如:: + + Signed-off-by: Random J Developer + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer + +如果您维护一个稳定的分支机构，同时希望对作者进行致谢、跟踪更改、合并修复并 +保护提交者不受投诉，那么这种做法尤其有用。请注意，在任何情况下都不能更改作者 +的ID（From 头），因为它是出现在更改日志中的标识。 + +对回合（back-porters）的特别说明：在提交消息的顶部（主题行之后）插入一个补丁 +的起源指示似乎是一种常见且有用的实践，以便于跟踪。例如，下面是我们在3.x稳定 +版本中看到的内容:: + + Date: Tue Oct 7 07:26:38 2014 -0400 + + libata: Un-break ATA blacklist + + commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. + +还有， 这里是一个旧版内核中的一个回合补丁:: + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +12）何时使用Acked-by:，CC:，和Co-Developed by: +---------------------------------------------- + +Singed-off-by: 标记表示签名者参与了补丁的开发，或者他/她在补丁的传递路径中。 + +如果一个人没有直接参与补丁的准备或处理，但希望表示并记录他们对补丁的批准， +那么他们可以要求在补丁的变更日志中添加一个 Acked-by: + +Acked-by：通常由受影响代码的维护者使用，当该维护者既没有贡献也没有转发补丁时。 + +Acked-by: 不像签字人那样正式。这是一个记录，确认人至少审查了补丁，并表示接受。 +因此，补丁合并有时会手动将Acker的“Yep，looks good to me”转换为 Acked-By：（但 +请注意，通常最好要求一个明确的Ack）。 + +Acked-by：不一定表示对整个补丁的确认。例如，如果一个补丁影响多个子系统，并且 +有一个：来自一个子系统维护者，那么这通常表示只确认影响维护者代码的部分。这里 +应该仔细判断。如有疑问，应参考邮件列表档案中的原始讨论。 + +如果某人有机会对补丁进行评论，但没有提供此类评论，您可以选择在补丁中添加 ``Cc:`` +这是唯一一个标签，它可以在没有被它命名的人显式操作的情况下添加，但它应该表明 +这个人是在补丁上抄送的。讨论中包含了潜在利益相关方。 + +Co-developed-by: 声明补丁也是由另一个开发人员和原始作者一起创建的。当多个人 +在一个补丁上工作时，这很有用。注意，此人也需要在补丁中有一个 Signed-off-by: + +13）使用报告人：、测试人：、审核人：、建议人：、修复人： +-------------------------------------------------------- + +Reported-by: 给那些发现错误并报告错误的人致谢，它希望激励他们在将来再次帮助 +我们。请注意，如果bug是以私有方式报告的，那么在使用Reported-by标记之前，请 +先请求权限。 + +Tested-by: 标记表示补丁已由指定的人（在某些环境中）成功测试。这个标签通知 +维护人员已经执行了一些测试，为将来的补丁提供了一种定位测试人员的方法，并确 +保测试人员的信誉。 + +Reviewed-by：相反，根据审查人的声明，表明该补丁已被审查并被认为是可接受的： + + +审查人的监督声明 +^^^^^^^^^^^^^^^^ + +通过提供我的 Reviewed-by，我声明： + + (a) 我已经对这个补丁进行了一次技术审查，以评估它是否适合被包含到 + 主线内核中。 + + (b) 与补丁相关的任何问题、顾虑或问题都已反馈给提交者。我对提交者对 + 我的评论的回应感到满意。 + + (c) 虽然这一提交可能会改进一些东西，但我相信，此时，（1）对内核 + 进行了有价值的修改，（2）没有包含争论中涉及的已知问题。 + + (d) 虽然我已经审查了补丁并认为它是健全的，但我不会（除非另有明确 + 说明）作出任何保证或保证它将在任何给定情况下实现其规定的目的 + 或正常运行。 + +Reviewed-by 是一种观点声明，即补丁是对内核的适当修改，没有任何遗留的严重技术 +问题。任何感兴趣的审阅者（完成工作的人）都可以为一个补丁提供一个 Review-by +标签。此标签用于向审阅者提供致谢，并通知维护者已在修补程序上完成的审阅程度。 +Reviewed-by: 当由已知了解主题区域并执行彻底检查的审阅者提供时，通常会增加 +补丁进入内核的可能性。 + +Suggested-by: 表示补丁的想法是由指定的人提出的，并确保将此想法归功于指定的 +人。请注意，未经许可，不得添加此标签，特别是如果该想法未在公共论坛上发布。 +这就是说，如果我们勤快地致谢我们的创意者，他们很有希望在未来得到鼓舞，再次 +帮助我们。 + +Fixes: 指示补丁在以前的提交中修复了一个问题。它可以很容易地确定错误的来源， +这有助于检查错误修复。这个标记还帮助稳定内核团队确定应该接收修复的稳定内核 +版本。这是指示补丁修复的错误的首选方法。请参阅 :ref:`cn_describe_changes` +描述您的更改以了解更多详细信息。 + +.. _cn_the_canonical_patch_format: + 12）标准补丁格式 +---------------- + +本节描述如何格式化补丁本身。请注意，如果您的补丁存储在 ``Git`` 存储库中，则 +可以使用 ``git format-patch`` 进行正确的补丁格式设置。但是，这些工具无法创建 +必要的文本，因此请务必阅读下面的说明。 + +标准的补丁，标题行是:: -标准的补丁，标题行是： Subject: [PATCH 001/123] 子系统:一句话概述 标准补丁的信体存在如下部分： - - 一个 "from" 行指出补丁作者。 + - 一个 "from" 行指出补丁作者。后跟空行（仅当发送修补程序的人不是作者时才需要）。 + + - 解释的正文，行以75列包装，这将被复制到永久变更日志来描述这个补丁。 - 一个空行 - - 说明的主体，这些说明文字会被拷贝到描述该补丁的永久改动记录里。 + - 上面描述的“Signed-off-by” 行，也将出现在更改日志中。 - - 一个由"---"构成的标记行 + - 只包含 ``---`` 的标记线。 - - 不合适放到改动记录里的额外的注解。 + - 任何其他不适合放在变更日志的注释。 - - 补丁本身（diff 输出） + - 实际补丁（ ``diff`` 输出）。 标题行的格式，使得对标题行按字母序排序非常的容易 - 很多 e-mail 客户端都 可以支持 - 因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。 @@ -296,21 +520,35 @@ e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。 记住 e-mail 的“一句话概述”会成为该补丁的全局唯一标识。它会蔓延到 git 的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补 丁。用户将希望通过 google 来搜索"一句话概述"来找到那些讨论这个补丁的文 -章。 +章。当人们在两三个月后使用诸如 ``gitk`` 或 ``git log --oneline`` 之类 +的工具查看数千个补丁时，也会很快看到它。 + +出于这些原因，概述必须不超过70-75个字符，并且必须描述补丁的更改以及为 +什么需要补丁。既要简洁又要描述性很有挑战性，但写得好的概述应该这样做。 + +概述的前缀可以用方括号括起来：“Subject: [PATCH ...] <概述>”。标记 +不被视为概述的一部分，而是描述应该如何处理补丁。如果补丁的多个版本已发 +送出来以响应评审（即“v1，v2，v3”）或“rfc”，以指示评审请求，那么通用标记 +可能包括版本描述符。如果一个补丁系列中有四个补丁，那么各个补丁可以这样 +编号：1/4、2/4、3/4、4/4。这可以确保开发人员了解补丁应用的顺序，并且他们 +已经查看或应用了补丁系列中的所有补丁。 一些标题的例子:: Subject: [patch 2/5] ext2: improve scalability of bitmap searching Subject: [PATCHv2 001/207] x86: fix eflags tracking -"from" 行是信体里的最上面一行，具有如下格式： +"From" 行是信体里的最上面一行，具有如下格式： From: Original Author -"from" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "from" 行，那 +"From" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "From" 行，那 么邮件头里的 "From: " 行会被用来决定改动日志中的作者。 说明的主题将会被提交到永久的源代码改动日志里，因此对那些早已经不记得和 -这个补丁相关的讨论细节的有能力的读者来说，是有意义的。 +这个补丁相关的讨论细节的有能力的读者来说，是有意义的。包括补丁程序定位 +错误的（内核日志消息、OOPS消息等）症状，对于搜索提交日志以寻找适用补丁的人 +尤其有用。如果一个补丁修复了一个编译失败，那么可能不需要包含所有编译失败； +只要足够让搜索补丁的人能够找到它就行了。与概述一样，既要简洁又要描述性。 "---" 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少 的。 @@ -324,65 +562,63 @@ e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。 在后面的参考资料中能看到适当的补丁格式的更多细节。 -------------------------------- -第二节 提示，建议和诀窍 -------------------------------- +.. _cn_explicit_in_reply_to: -本节包含很多和提交到内核的代码有关的通常的"规则"。事情永远有例外...但是 -你必须真的有好的理由这样做。你可以把本节叫做Linus的计算机科学入门课。 +15) 明确回复邮件头(In-Reply-To) +------------------------------- -1) 读 Document/process/coding-style.rst +手动添加回复补丁的的标题头(In-Reply_To:) 是有帮助的（例如，使用 ``git send-email`` ） +将补丁与以前的相关讨论关联起来，例如，将bug修复程序链接到电子邮件和bug报告。 +但是，对于多补丁系列，最好避免在回复时使用链接到该系列的旧版本。这样， +补丁的多个版本就不会成为电子邮件客户端中无法管理的引用序列。如果链接有用， +可以使用 https://lkml.kernel.org/ 重定向器（例如，在封面电子邮件文本中） +链接到补丁系列的早期版本。 -Nuff 说过，如果你的代码和这个偏离太多，那么它有可能会被拒绝，没有更多的 -审查，没有更多的评价。 +16) 发送git pull请求 +-------------------- -2) #ifdef 是丑陋的 -混杂了 ifdef 的代码难以阅读和维护。别这样做。作为替代，将你的 ifdef 放 -在头文件里，有条件地定义 "static inline" 函数，或者宏，在代码里用这些东 -西。让编译器把那些"空操作"优化掉。 +如果您有一系列补丁，那么让维护人员通过git pull操作将它们直接拉入子系统存储 +库可能是最方便的。但是，请注意，从开发人员那里获取补丁比从邮件列表中获取补 +丁需要更高的信任度。因此，许多子系统维护人员不愿意接受请求，特别是来自新的 +未知开发人员的请求。如果有疑问，您可以在封面邮件中使用pull 请求作为补丁系列 +正常发布的一个选项，让维护人员可以选择使用其中之一。 -一个简单的例子，不好的代码:: +pull 请求的主题行中应该有[Git Pull]。请求本身应该在一行中包含存储库名称和 +感兴趣的分支；它应该看起来像:: - dev = alloc_etherdev (sizeof(struct funky_private)); - if (!dev) - return -ENODEV; - #ifdef CONFIG_NET_FUNKINESS - init_funky_net(dev); - #endif + Please pull from -清理后的例子: + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus -(头文件里):: + to get these changes: - #ifndef CONFIG_NET_FUNKINESS - static inline void init_funky_net (struct net_device *d) {} - #endif -(代码文件里):: +pull 请求还应该包含一条整体消息，说明请求中将包含什么，一个补丁本身的 ``Git shortlog`` +以及一个显示补丁系列整体效果的 ``diffstat`` 。当然，将所有这些信息收集在一起 +的最简单方法是让 ``git`` 使用 ``git request-pull`` 命令为您完成这些工作。 - dev = alloc_etherdev (sizeof(struct funky_private)); - if (!dev) - return -ENODEV; - init_funky_net(dev); +一些维护人员（包括Linus）希望看到来自已签名提交的请求；这增加了他们对你的 +请求信心。特别是，在没有签名标签的情况下，Linus 不会从像 Github 这样的公共 +托管站点拉请求。 -3) 'static inline' 比宏好 +创建此类签名的第一步是生成一个 GNRPG 密钥，并由一个或多个核心内核开发人员对 +其进行签名。这一步对新开发人员来说可能很困难，但没有办法绕过它。参加会议是 +找到可以签署您的密钥的开发人员的好方法。 -Static inline 函数相比宏来说，是好得多的选择。Static inline 函数提供了 -类型安全，没有长度限制，没有格式限制，在 gcc 下开销和宏一样小。 +一旦您在Git 中准备了一个您希望有人拉的补丁系列，就用 ``git tag -s`` 创建一 +个签名标记。这将创建一个新标记，标识该系列中的最后一次提交，并包含用您的私 +钥创建的签名。您还可以将changelog样式的消息添加到标记中；这是一个描述拉请求 +整体效果的理想位置。 -宏只在 static inline 函数不是最优的时候[在 fast paths 里有很少的独立的 -案例]，或者不可能用 static inline 函数的时候[例如字符串分配]。 -应该用 'static inline' 而不是 'static __inline__', 'extern inline' 和 -'extern __inline__' 。 +如果维护人员将要从中提取的树不是您正在使用的存储库，请不要忘记将已签名的标记 +显式推送到公共树。 -4) 不要过度设计 +生成拉请求时，请使用已签名的标记作为目标。这样的命令可以实现:: -不要试图预计模糊的未来事情，这些事情也许有用也许没有用："让事情尽可能的 -简单，而不是更简单"。 + git request-pull master git://my.public.tree/linux.git my-signed-tag ----------------- -第三节 参考文献 ----------------- +参考文献 +-------- Andrew Morton, "The perfect patch" (tpp). @@ -391,16 +627,28 @@ Jeff Garzik, "Linux kernel patch submission format". Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". - - - - + + + + + + + + + + + NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! Kernel Documentation/process/coding-style.rst: - + :ref:`Documentation/process/coding-style.rst ` Linus Torvalds's mail on the canonical patch format: + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + + http://halobates.de/on-submitting-patches.pdf