提交内核补丁到Linux社区的步骤

简介

向Linux社区提交补丁并不频繁，某一次提交后可能了然于胸，过段时间总会忘记，于是就有了这篇文章

这篇文章是我真实提交的步骤，没有严格按官方的要求和建议来，但能覆盖大多数问题

如果希望详细学习如何提交，参考《如何让你的改动进入内核》

下载代码

在官网下载最新代码，或者通过MAINTAINERS寻找对应子系统的仓库代码。

以我要提交pstore的子系统为例，在MAINTAINERS中找到以下信息：

PSTORE FILESYSTEM
M:  Kees Cook <keescook@chromium.org>
M:  Anton Vorontsov <anton@enomsg.org>
M:  Colin Cross <ccross@android.com>
M:  Tony Luck <tony.luck@intel.com>
S:  Maintained
T:  git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git for-next/pstore
F:  fs/pstore/
F:  include/linux/pstore*
F:  drivers/firmware/efi/efi-pstore.c
F:  drivers/acpi/apei/erst.c
F:  Documentation/admin-guide/ramoops.rst
F:  Documentation/admin-guide/pstore-block.rst
F:  Documentation/devicetree/bindings/reserved-memory/ramoops.txt
K:  \b(pstore|ramoops|blkoops)

既然子系统有独立仓库分支，那就下载这个分支的代码，并切换到对应分支

git clone git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git pstore-tree
git checkout for-next/pstore

创建补丁

在下载的最新代码仓库中，本地提交自己的补丁后，就可以把补丁提取出文件来。

如果是单个补丁，用下面的命令：

git format-patch --subject-prefix='PATCH' -i HEAD~

如果是系列补丁，用下面的命令：

git format-patch --cover-letter --subject-prefix='PATCH' -N #这里的N是你要提取的补丁个数

上面两个命令比较通用了，其中

subject-prefix 是为邮件标题添加个前缀
cover-letter 是为系列邮件创建封面邮件

邮件前缀

一个邮件可有多个邮件前缀。有以下常见的邮件前缀，我的理解不确定是否准确，仅供参考

前缀	含义
PATCH	常规的且正式的补丁
RFC	不是要正式提上去的，希望一起讨论这个补丁，用来说明方向，看看意见
RESEND	邮件发过了但好几周都没人鸟，可能被遗忘了，重新发

如果根据maintainer的意见，修改后重新提交，则需要在前缀后面加上版本。

例如第5个版本：

git format-patch --subject-prefix='PATCH v5' -i HEAD~

提取出来的补丁，效果大概是这样：

[...]
Subject: [PATCH v5] ....
[...]

邮件封面

当有多个补丁来做某一件事情，我们需要提交系列补丁，那么最好有个邮件封面，介绍这系列补丁

那么，就会多出个0000编号的补丁：

0000-cover-letter.patch
0001-...
0002-...

在封面补丁里，就会列出了系列补丁包含哪些补丁？改了啥文件？如下：

[...]
Subject: [PATCH v5] *** SUBJECT HERE *** 

*** BLURB HERE ***

WeiXiong Liao (1):
  mtd: ...

 drivers/mtd/Kconfig     |   8 + 
 drivers/mtd/Makefile    |   1 + 
[...]
 3 files changed, 540 insertions(+)

其中，封面补丁里面邮件头和正文需要自己写，可别冒失就这么发出去了

SUBJECT HERE ： 封面邮件头，一句话总结系列邮件
BLURB HERE ： 封面邮件正文，讲讲系列邮件是为了做什么

编译检查

编译进内核和编译成模块，都要试试，确保都能编译过

风格检查

Linux内核有提供脚本进行补丁的风格检查，执行下面命令：

$ ./scripts/checkpatch.pl 00*.patch

脚本爆出错误啦，改！在本地仓库改，然后提交到本地仓库，重新提出补丁，再次检查。只至没有报错为止。

错误都改！如果是警告，建议改，除非你觉得修改是合理的，可以忽略

还有一些是误报/建议，自己酌情看看是否要修，例如：

WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#71: 
new file mode 100644

上面警告信息显示添加了新文件，需要我们确认新文件是否有在MAINTAINERS的记录中。实际上是有的，因为MAINTAINERS中文件是模糊匹配的，刚好囊括了我新添加的文件，因此可以忽略这警告。

kernel-doc注释规范检查

Linux系统上的kernel-doc机制，可以在源码中提取函数、结构体、枚举型、共同体等的说明。当然，要正确提取源码的注释就必须要符合一定的规范。

规范见另外一篇博客：《Linux内核文档：如何写符合 kernel-doc 规范的注释》

可以通过这样子检查是否符合规范：

$ ./scripts/kernel-doc -v -none <改动的.c/.h源码文件>

根据提示，修正warning和error即可。

确定邮件接受人

不知道把邮件发给谁？别怕，Linux内核牛叉到有提供脚本获取邮件接收人地址：

$ ./scripts/get_maintainer.pl 00*.patch

会比较慢，慢慢等，输出结果参考如下：

Kees Cook <keescook@chromium.org> (maintainer:PSTORE FILESYSTEM)
Anton Vorontsov <anton@enomsg.org> (maintainer:PSTORE FILESYSTEM)
Colin Cross <ccross@android.com> (maintainer:PSTORE FILESYSTEM)
[...]
linux-doc@vger.kernel.org (open list:DOCUMENTATION)
linux-kernel@vger.kernel.org (open list)
linux-mtd@lists.infradead.org (open list:MEMORY TECHNOLOGY DEVICES (MTD))

因为我的是系列补丁，涉及多个子系统，所以获取到的邮件地址很多。

上面显示的地址中，很明显最后linux-开头的三行不是代码reviewer，类似于订阅转发地址的存在。把邮件发给这几个地址，就会转发给所有订阅了子系统的人。

发送邮件

我们用 git send-mail 发送邮件，简单，舒心

git send-mail --to <maintainerA> --to <maintainerB> .... --cc linux-XXXX@xxxx --cc ... 00*.patch

把上面获取的maintainer地址，用 --to 指定，订阅地址改用抄送 --cc

当然，在这之前，需要在git中配置你的sendmail信息

$ cat ~/.gitconfig
[...]
[sendemail]
    smtpserver = ...
    smtpserverport = 465 
    smtpencryption = ssl 
    smtpuser = ...

响应质疑与等待合并

如果有maintainer对你的补丁有疑惑，别担心，他们邮件提问，我们邮件回复。

邮件回复的细节不累述了。