linux内核补丁更新,5. 发布补丁 — The Linux Kernel documentation

5.4.补丁格式和更改日志¶

所以现在你有了一系列完美的补丁可以发布，但是这项工作还没有完成。每个补丁都

需要被格式化成一条消息，它可以快速而清晰地将其目的传达给世界其他地方。为此，

每个补丁将由以下部分组成：

命名补丁作者的可选“from”行。只有当你通过电子邮件传递别人的补丁时，这一行

才是必要的，但是如果有疑问，添加它不会有任何伤害。

一行描述补丁的作用。对于没有其他上下文的读者来说，此消息应该足够了解补丁

的范围；这是将在“短格式”变更日志中显示的行。此消息通常首先用相关的子系统

名称格式化，然后是补丁的目的。例如：

gpio: fix build on CONFIG_GPIO_SYSFS=n

一个空白行，后面是补丁内容的详细描述。这个描述可以是必需的；它应该说明补丁

的作用以及为什么它应该应用于内核。

一个或多个标记行，至少有一个由补丁作者的：signed-off-by 签名。签名将在下面

更详细地描述。

上面的项目一起构成补丁的变更日志。写一篇好的变更日志是一门至关重要但常常被

忽视的艺术；值得花一点时间来讨论这个问题。当你写一个变更日志时，你应该记住

有很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否

应该包括补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核，

bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知道内核如何变化的用户。

等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。

为此，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。

然后，详细的描述可以详述这些主题，并提供任何需要的附加信息。如果补丁修复了

一个bug，请引用引入该bug的commit(如果可能，请在引用commits时同时提供commit id

和标题)。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他

人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么就这么

说。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。一般

来说，你越能把自己放在每个阅读你的changelog的人的位置上，changelog(和内核

作为一个整体)就越好。

不用说，变更日志应该是将变更提交到修订控制系统时使用的文本。接下来是：

补丁本身，采用统一的(“-u”)补丁格式。将“-p”选项用于diff将使函数名与更改

相关联，从而使结果补丁更容易被其他人读取。

您应该避免在补丁中包括对不相关文件(例如，由构建过程生成的文件或编辑器

备份文件)的更改。文档目录中的文件“dontdiff”在这方面有帮助；使用“-X”选项将

其传递给diff。

上面提到的标签用于描述各种开发人员如何与这个补丁的开发相关联。

文档中对它们进行了详细描述；下面是一个简短的总结。每一行的格式如下：

tag: Full Name optional-other-stuff

常用的标签有：

Signed-off-by: 这是一个开发人员的证明，他或她有权提交补丁以包含到内核中。

这是开发来源认证协议，其全文可在

中找到，如果没有适当的签字，则不能合并到主线中。

Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上

工作时，它用于将属性赋予共同作者(除了 From: 所赋予的作者之外)。因为

Co-developed-by: 表示作者身份，所以每个共同开发人, 必须紧跟在相关合作作者

的签名之后。具体内容和示例可以在以下文件中找到

Acked-by: 表示另一个开发人员(通常是相关代码的维护人员)同意补丁适合包含

在内核中。

Tested-by: 声明指定的人已经测试了补丁并发现它可以工作。

Reviewed-by: 指定的开发人员已经审查了补丁的正确性；有关详细信息，请参阅

Reported-by: 指定报告此补丁修复的问题的用户；此标记用于提供感谢。

Cc：指定的人收到了补丁的副本，并有机会对此发表评论。

在补丁中添加标签时要小心：只有cc:才适合在没有指定人员明确许可的情况下添加。