0001 .. include:: ../disclaimer-zh_CN.rst
0002
0003 :Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
0004
0005 :Translator:
0006
0007 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
0008
0009 :校译:
0010
0011 吴想成 Wu XiangCheng <bobwxc@email.cn>
0012
0013 .. _cn_development_posting:
0014
0015 发布补丁
0016 ========
0017
0018 您的工作迟早会准备好提交给社区进行审查，并最终包含到主线内核中。毫不稀奇，
0019 内核开发社区已经发展出一套用于发布补丁的约定和过程；遵循这些约定和过程将使
0020 参与其中的每个人的生活更加轻松。本文档试图描述这些约定的部分细节；更多信息
0021 也可在以下文档中找到
0022 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
0023 和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。
0024
0025 何时寄送
0026 --------
0027
0028 在补丁完全“准备好”之前，避免发布补丁是一种持续的诱惑。对于简单的补丁，这
0029 不是问题。但是如果正在完成的工作很复杂，那么在工作完成之前从社区获得反馈就
0030 可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至维护一个可用的Git
0031 树，以便感兴趣的开发人员可以随时赶上您的工作。
0032
0033 当发布中有尚未准备好被包含的代码，最好在发布中说明。还应提及任何有待完成的
0034 主要工作和任何已知问题。很少有人会愿意看那些被认为是半生不熟的补丁，但是
0035 那些愿意的人会带着他们的点子来一起帮助你把工作推向正确的方向。
0036
0037 创建补丁之前
0038 ------------
0039
0040 在考虑将补丁发送到开发社区之前，有许多事情应该做。包括：
0041
0042 - 尽可能地测试代码。利用内核的调试工具，确保内核使用了所有可能的配置选项组合
0043 进行构建，使用交叉编译器为不同的体系结构进行构建等。
0044
0045 - 确保您的代码符合内核代码风格指南。
0046
0047 - 您的更改是否具有性能影响？如果是这样，您应该运行基准测试来显示您的变更的
0048 影响（或好处）；结果的摘要应该包含在补丁中。
0049
0050 - 确保您有权发布代码。如果这项工作是为雇主完成的，雇主对这项工作具有所有权，
0051 并且必须同意根据GPL对其进行发布。
0052
0053 一般来说，在发布代码之前进行一些额外的思考，几乎总是能在短时间内得到回报。
0054
0055 补丁准备
0056 --------
0057
0058 准备补丁发布的工作量可能很惊人，但在此尝试节省时间通常是不明智的，即使在短期
0059 内亦然。
0060
0061 必须针对内核的特定版本准备补丁。一般来说，补丁应该基于Linus的Git树中的当前
0062 主线。当以主线为基础时，请从一个众所周知的发布点开始——如稳定版本或 -rc
0063 版本发布点——而不是在一个任意的主线分支点。
0064
0065 也可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。
0066 根据补丁的区域以及其他地方的情况，针对其他树建立的补丁可能需要大量的工作来
0067 解决冲突和处理API更改。
0068
0069 只有最简单的更改才应格式化为单个补丁；其他所有更改都应作为一系列逻辑更改进行。
0070 分割补丁是一门艺术；一些开发人员花了很长时间来弄清楚如何按照社区期望的方式来
0071 分割。不过，这些经验法则也许有帮助：
0072
0073 - 您发布的补丁系列几乎肯定不会是开发过程中版本控制系统中的一系列更改。相反，
0074 需要对您所做更改的最终形式加以考虑，然后以有意义的方式进行拆分。开发人员对
0075 离散的、自包含的更改感兴趣，而不是您创造这些更改的原始路径。
0076
0077 - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（如“向
0078 此结构体添加字段”）或大的（如添加一个重要的新驱动程序），但它们在概念上
0079 应该是小的，并且可以在一行内简述。每个补丁都应该做一个特定的、可以单独
0080 检查并验证它所做的事情的更改。
0081
0082 - 换种方式重申上述准则，也就是说：不要在同一补丁中混合不同类型的更改。如果
0083 一个补丁修复了一个关键的安全漏洞，又重新排列了一些结构，还重新格式化了代
0084 码，那么它很有可能会被忽略，从而导致重要的修复丢失。
0085
0086 - 每个补丁都应该能创建一个可以正确地构建和运行的内核；如果补丁系列在中间被
0087 断开，那么结果仍应是一个正常工作的内核。部分应用一系列补丁是使用
0088 “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么将使
0089 那些从事追踪问题的高尚工作的开发人员和用户的生活更加艰难。
0090
0091 - 不要过分分割。一位开发人员曾经将一组针对单个文件的编辑分成500个单独的补丁
0092 发布，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大，
0093 只要它仍然包含一个单一的 *逻辑* 变更。
0094
0095 - 用一系列补丁添加一个全新的基础设施，但是该设施在系列中的最后一个补丁启用
0096 整个变更之前不能使用，这看起来很诱人。如果可能的话，应该避免这种诱惑；
0097 如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的补丁，
0098 即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即激活该
0099 代码。
0100
0101 创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要
0102 花费大量的时间和思考。但是如果做得好，花费的时间就是值得的。
0103
0104 补丁格式和更改日志
0105 ------------------
0106
0107 所以现在你有了一系列完美的补丁可以发布，但是这项工作还没有完成。每个补丁都
0108 需要被格式化成一条消息，以快速而清晰地将其目的传达到世界其他地方。为此，
0109 每个补丁将由以下部分组成：
0110
0111 - 可选的“From”行，表明补丁作者。只有当你通过电子邮件发送别人的补丁时，这一行
0112 才是必须的，但是为防止疑问加上它也不会有什么坏处。
0113
0114 - 一行描述，说明补丁的作用。对于在没有其他上下文的情况下看到该消息的读者来说，
0115 该消息应足以确定修补程序的范围；此行将显示在“short form（简短格式）”变更
0116 日志中。此消息通常需要先加上子系统名称前缀，然后是补丁的目的。例如：
0117
0118 ::
0119
0120 gpio: fix build on CONFIG_GPIO_SYSFS=n
0121
0122 - 一行空白，后接补丁内容的详细描述。此描述可以是任意需要的长度；它应该说明补丁
0123 的作用以及为什么它应该应用于内核。
0124
0125 - 一个或多个标记行，至少有一个由补丁作者的 Signed-off-by 签名。标记将在下面
0126 详细描述。
0127
0128 上面的项目一起构成补丁的变更日志。写一则好的变更日志是一门至关重要但常常被
0129 忽视的艺术；值得花一点时间来讨论这个问题。当你编写变更日志时，你应该记住有
0130 很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否
0131 应该合并补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核，
0132 缺陷搜寻人员想知道补丁是否导致他们正在追查的问题，以及想知道内核如何变化的
0133 用户等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。
0134
0135 在结尾，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。
0136 然后，详细的描述可以详述这些主题，并提供任何需要的附加信息。如果补丁修复了
0137 一个缺陷，请引用引入该缺陷的提交（如果可能，请在引用提交时同时提供其 id 和
0138 标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他
0139 人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么应当
0140 说明。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。
0141 一般来说，你越把自己放在每个阅读你变更日志的人的位置上，变更日志（和内核
0142 作为一个整体）就越好。
0143
0144 不需要说，变更日志是将变更提交到版本控制系统时使用的文本。接下来将是：
0145
0146 - 补丁本身，采用统一的（“-u”）补丁格式。使用“-p”选项来diff将使函数名与
0147 更改相关联，从而使结果补丁更容易被其他人读取。
0148
0149 您应该避免在补丁中包括与更改不相关文件（例如，构建过程生成的文件或编辑器
0150 备份文件）。文档目录中的“dontdiff”文件在这方面有帮助；使用“-X”选项将
0151 其传递给diff。
0152
0153 上面提到的标签（tag）用于描述各种开发人员如何与这个补丁的开发相关联。
0154 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
0155 文档中对它们进行了详细描述；下面是一个简短的总结。每一行的格式如下：
0156
0157 ::
0158
0159 tag: Full Name <email address> optional-other-stuff
0160
0161 常用的标签有：
0162
0163 - Signed-off-by: 这是一个开发人员的证明，证明他或她有权提交补丁以包含到内核
0164 中。这表明同意开发者来源认证协议，其全文见
0165 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
0166 如果没有合适的签字，则不能合并到主线中。
0167
0168 - Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上
0169 工作时，它用于给出共同作者（除了 From: 所给出的作者之外）。由于
0170 Co-developed-by: 表示作者身份，所以每个共同开发人，必须紧跟在相关合作作者
0171 的Signed-off-by之后。具体内容和示例见以下文件
0172 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
0173
0174 - Acked-by: 表示另一个开发人员（通常是相关代码的维护人员）同意补丁适合包含
0175 在内核中。
0176
0177 - Tested-by: 声明某人已经测试了补丁并确认它可以工作。
0178
0179 - Reviewed-by: 表示某开发人员已经审查了补丁的正确性；有关详细信息，请参阅
0180 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
0181
0182 - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于表示感谢。
0183
0184 - Cc：指定某人收到了补丁的副本，并有机会对此发表评论。
0185
0186 在补丁中添加标签时要小心：只有Cc:才适合在没有指定人员明确许可的情况下添加。
0187
0188 寄送补丁
0189 --------
0190
0191 在寄送补丁之前，您还需要注意以下几点：
0192
0193 - 您确定您的邮件发送程序不会损坏补丁吗？被邮件客户端更改空白或修饰了行的补丁
0194 无法被另一端接受，并且通常不会进行任何详细检查。如果有任何疑问，先把补丁寄
0195 给你自己，让你自己确定它是完好无损的。
0196
0197 :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>`
0198 提供了一些有用的提示，可以让特定的邮件客户端正常发送补丁。
0199
0200 - 你确定你的补丁没有荒唐的错误吗？您应该始终通过scripts/checkpatch.pl检查
0201 补丁程序，并解决它提出的问题。请记住，checkpatch.pl，虽然体现了对内核补丁
0202 应该是什么样的大量思考，但它并不比您聪明。如果修复checkpatch.pl给的问题会
0203 使代码变得更糟，请不要这样做。
0204
0205 补丁应始终以纯文本形式发送。请不要将它们作为附件发送；这使得审阅者在答复中更难
0206 引用补丁的部分。相反，只需将补丁直接放到您的消息中。
0207
0208 寄出补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核
0209 鼓励人们甚至错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。
0210 尤其是，副本应发送至：
0211
0212 - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的首选地方。
0213
0214 - 其他在同一领域工作的开发人员，尤其是那些现在可能在那里工作的开发人员。使用
0215 git查看还有谁修改了您正在处理的文件，这很有帮助。
0216
0217 - 如果您对某错误报告或功能请求做出响应，也可以抄送原始发送人。
0218
0219 - 将副本发送到相关邮件列表，或者若无相关列表，则发送到linux-kernel列表。
0220
0221 - 如果您正在修复一个缺陷，请考虑该修复是否应进入下一个稳定更新。如果是这样，
0222 补丁副本也应发到stable@vger.kernel.org 。另外，在补丁本身的标签中添加一个
0223 “Cc: stable@vger.kernel.org”；这将使稳定版团队在修复进入主线时收到通知。
0224
0225 当为一个补丁选择接收者时，最好清楚你认为谁最终会接受这个补丁并将其合并。虽然
0226 可以将补丁直接发给Linus Torvalds并让他合并，但通常情况下不会这样做。Linus很
0227 忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您的
0228 补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁接收者。
0229
0230 补丁需要好的主题行。补丁主题行的规范格式如下：
0231
0232 ::
0233
0234 [PATCH nn/mm] subsys: one-line description of the patch
0235
0236 其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的
0237 名称。当然，一个单独的补丁可以省略nn/mm。
0238
0239 如果您有一系列重要的补丁，那么通常发送一个简介作为第〇部分。不过，这个约定
0240 并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会进入内核变更日志。
0241 因此，请确保补丁本身具有完整的变更日志信息。
0242
0243 一般来说，多部分补丁的第二部分和后续部分应作为对第一部分的回复发送，以便它们
0244 在接收端都连接在一起。像git和coilt这样的工具有命令，可以通过适当的线程发送
0245 一组补丁。但是，如果您有一长串补丁，并正使用git，请不要使用–-chain-reply-to
0246 选项，以避免创建过深的嵌套。
