向Linux主线社区提交补丁

背景

当我们在平时工作或学习中，发现linux内核有需要改进或修复的地方，而恰好在最新的社区主线也没有补丁，可以将补丁提交给社区。

完整补丁开发流程

完整补丁开发流程：

flowchart TD
    A[1. RFC阶段] --> B[2. PATCH阶段]
    B --> C{维护者反馈}
    C -->|需修改| D[3. 修订与重发 PATCH v2/v3]
    D --> B
    C -->|审核通过| E[4. 合入主线]

完整的补丁生命周期如下：

  1. [RFC] 阶段：
    提交初步设计思路（非完整代码），征求社区对架构的意见。例如：
    [RFC] mm: introduce new memory compression algorithm

  2. [PATCH] 阶段：
    根据 RFC 反馈完善代码，提交正式补丁。需包含完整实现、测试报告和 Signed-off-by。

  3. 修订与重发（v2/v3…）：
    接收维护者反馈（如“代码风格问题”“测试用例不足”）后，修改代码并以 [PATCH v2] 重发，需在描述中说明修改点：
    Changes in v2: - fix typo in comment (reported by John) - add test case for corner case

  4. 合入主线：
    维护者审核通过后，将补丁合并至子系统树（如 net-next），最终通过 Linus 的 master 树合入主线内核。

准备补丁

补丁规范

Linux社区的补丁都是以邮件的形式提交和交流讨论，在提交和回复的过程中需要遵守一定的规范要求。不同的子系统可能还有它自己的特定的一些默认的规定。

邮件主题格式

清晰是第一准则！ 主题需包含类型标识和核心内容，让接收者快速了解邮件目的。常见标识：

标识 含义 示例主题
[PATCH] 正式提交的补丁（可合入） [PATCH] net: tcp: fix retransmit timeout calculation
[RFC] 请求意见（非正式补丁，讨论设计） [RFC] net: introduce new TCP congestion control algorithm
[v2] 补丁第二版（修改后重发） [PATCH v2] mm: page_alloc: optimize buddy allocator
[RESEND] 重新发送未收到反馈的补丁 [RESEND PATCH] fs: ext4: fix inode leak on error path
[QUESTION] 技术问题咨询 [QUESTION] arm64: how to handle CPU hotplug in KVM?

注意： 标识需放在主题开头，子系统名可省略（通过列表区分），但复杂补丁建议补充，如 [PATCH net-next]（提交至网络子系统的下一版本）。

补丁邮件正文

补丁邮件正文需包含补丁描述和补丁内容，格式严格遵循内核要求。

补丁描述（邮件正文开头）：

  • 问题背景（为何需要此补丁）；
  • 解决方案（做了什么修改）；
  • 测试情况（如何验证，测试环境）。

Fixes 标签： 如果是Fix补丁，需要增加 Fixes 标签
Cc 标签： 修复已发布内核中严重错误的补丁应通过如下⾏定向到稳定版维护者，即Cc: stable@vger.kernel.org

Signed-off-by（必须）：
补丁需包含 Signed-off-by ，表明提交者同意《开发者证书 of Origin（DCO）》，即：

  • 本人编写代码或有权提交；
  • 代码符合开源协议（GPLv2）。

格式：Signed-off-by: Name <email>（姓名需真实，邮箱需可回复）。

示例：

Subject: [PATCH] net: tcp: fix retransmit timeout calculation

When the network is under high latency, the current TCP retransmit
timeout (RTO) calculation may use an outdated RTT sample, leading to
premature retransmissions and performance degradation.

This patch modifies tcp_rto_min() to always use the latest RTT sample
from the socket's rtt_min value.

Tested:
- Passed tcp_probe tests on x86_64 with 5.15.0 kernel.
- No regressions in iperf3 throughput (10Gbps link, RTT=100ms).

Signed-off-by: Your Name <your.email@example.com>
---
 net/ipv4/tcp_timer.c | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

生成补丁

git format-patch 是 Linux 内核开发中生成补丁文件的核心命令，用于将 Git 提交转换为标准 .patch 文件，便于通过邮件发送给维护者审核。
常用命令如下：

git format-patch -3 -v2 --cover-letter -o patchs

说明：

  • -3 ：代表需要生成 3 个当前的分支 HEAD 位置往下的补丁
  • -v2：代表准备给维护者发送提交的第二版补丁，这样提取的补丁会有 [PATCH v2] 的字样开头，第三版，第四版以此类推。
  • --cover-letter：提交一系列的补丁时，最好有个总结的文字在前面，而这个参数会生成一个 v1-0000-cover-letter.patch 的补丁，需要自己修改名字以及它里面的内容，你需要尽可能的详细，让维护者正确理解你的代码所要表达的意思。
  • -o patchs：将补丁全部出去到 patchs 目录，这样容易归纳处理。

补丁格式检查

内核源码自带 scripts/checkpatch.pl 工具，可自动检查补丁是否符合代码风格（如缩进、命名规范）：

# --strict 启用严格检查
./scripts/checkpatch.pl --strict 0001-xxx.patch

必须修复所有报错，否则补丁可能会被直接退回。

提交补丁

工具安装与配置

提交发送补丁需使用 git send-email （而非邮件客户端附件），它能自动生成符合 LKML 格式的邮件。
首先需要安装它：

sudo apt-get update
sudo apt-get install git-email

然后进行邮箱相关的配置：
可以通过 git config ，也可以直接修改配置文件 ~/.gitconfig ：

[sendemail]
	smtpencryption = <ssl or tls>
	smtpserver = <your smtp address>  
	smtpserverport = xxx
	smtpuser = your.email@example.com
	smtppass = xxxxxx
	from = Your Name <your.email@example.com>

[user]
	email = your.email@example.com(补丁带的邮箱)
	name = Your Name

发送第一版补丁

发送补丁：

git send-email --to kuba@kernel.org --cc netdev@vger.kernel.org 0001-xxx.patch
# 安全起见，建议先用 dry-run 预览
git send-email --dry-run patches/*.patch

说明：

  • --to 就是主要的 Maintainer 的邮箱
  • --cc 就是抄送邮件列表

补丁所属的邮箱 Maintainer 邮箱及邮件列表怎么来呢？可以通过内核源码自带的脚本 get_maintainer.pl获取：

#例如获取 Makefile 的Maintainer邮箱
./scripts/get_maintainer.pl Makefile -f

其实就是通过 get_maintainer.pl 加目录名或者文件名来查找维护者或者邮件列表，很简单。
收件人一般为个人，抄送主要是内核邮件列表

发送成功，会有如下类似的信息打印：

From: Zhao YYY <winter91@foxmail.com>
To: davem@davemloft.net,
        andrew@lunn.ch,
        hkallweit1@gmail.com,
        kuba@kernel.org
Cc: netdev@vger.kernel.org
Subject: [PATCH] net: mdiobus: xxxxxxxxxxxxxxxxxxxxxxxxx
Date: Tue, 12 May 2026 16:25:21 +0800
Message-Id: <20260512082521.382202-1-winter91@foxmail.com>
X-Mailer: git-send-email 2.25.1
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

Result: 250

提交多版本补丁

相比提交第一版补丁，提交多版本补丁时除了修改代码，还需要做些其他改动：添加patch版本号，提交信息添加修改记录。

生成补丁(带 patch 版本号)：

git format-patch -v 2 ...

修改commit(添加修改记录)：

git commit --amend

示例：

[PATCH v2] drivers: example: yyyyyy
# 描述：新提交的patch描述

Signed-off-by: Your Name <your.email@example.com>
# 注意保留`Reviewed-by`或`Tested-by`等
---
v2:
  - 改动的简单描述
v1: xxxx 可以是lore链接

注意： patch 中 --- 是需要的。

发送补丁：
V2 是一封全新的邮件！ 不要直接回复你上一版的邮件（即不要用 Reply 功能），需要开启一个新的邮件串（Thread），这样维护者才能清晰地看到最新的版本。

跟踪与回复补丁

跟踪补丁状态

跟踪补丁状态主要有以下几种方式：

  • Patchwork： 查看补丁状态（Under Review → Accepted → Applied）。
  • Lore 线程： 通过邮件线程跟踪讨论进展，维护者合并后会发送 Applied 确认邮件。
  • 内核源码： 最终通过 git log 检查补丁是否出现在主线，可以最先查看next分支。

回复补丁

回复规则

回复与讨论补丁遵循的一些原则：

  • 积极响应： 维护者反馈通常在 1-3 天内，超过一周未回复可礼貌重发（[RESEND]）。
  • 线程回复： 始终回复到原线程（点击“Reply All”），避免创建新邮件。
  • 避免 HTML 邮件： 所有邮件必须使用纯文本格式（ASCII），HTML 邮件会被自动丢弃或标记为垃圾邮件。
  • 控制每行字符数： 尽量保证每行字符不超过 72 个，这样在终端里阅读才不会乱
  • 底部回复： Linux 社区不提倡“顶楼回复”（新内容写在引用内容上方）。正确的做法是行间引用，即：引用一段对方的话，紧接着在下面回复一段。 采⽤交错回复（inline reply）的⽅式，类似“对话式”，而不是顶贴（top post）。
  • 引用符号： 在需要引用的原文每一行前面加上 > 符号。如果是引用对方的引用，就用 >>。
  • 针对性回复： 把你的回答直接写在对应的疑问或代码段落下方。
  • 简洁与感谢： 避免冗长客套，直接切入技术点；感谢用 Thanks 而非 Thank you very much。

邮件格式示例：

Subject: Re: [PATCH] 你的补丁标题

> On 07.03.23 10:03, Maintainer Name wrote:
> > 这里是你提交的补丁描述或代码。
> > 为什么这里要加这个锁？有必要吗？
> 
> 因为这里存在竞态条件，所以我加了这个锁来保护共享资源。
> 
> > 另外，第 50 行的变量命名不太符合规范。
> 
> 好的，我会在 V2 版本中修改这个命名。

-- 
Thanks,
你的名字

回复步骤

回复邮件的方法及注意点在 https://lore.kernel.org 中对应的补丁链接里的最下方会有，类似:

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=tencent_859B04510A77948C6A97FF769CBB9262A007@qq.com \
    --to=winter91@foxmail.com \
    --cc=linux-bluetooth@vger.kernel.org \
    --cc=luiz.dentz@gmail.com \
    --cc=marcel@holtmann.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.

我们可以点击那个 mbox 或者 raw 保存得到纯文本格式的原始邮件。

编辑保存的文件：

  • 删掉最上面的一大片的邮件头信息
  • 保留邮件标题所在的行，并在原标题前面加上 Re: 即可
    • 即保留 “Subject” 字样的行，并改为：Subject: Re: 原标题
  • 用符号标记 > 引用原文，自己回复的内容穿插于引用的内容之间
    • 可以批量替换：sed -i -e ‘s/^/> /g’ /path/to/the-patch-email
    • 也可以在 vim 中按下 CTRL+V 进入可视模式选中需要回复的所有行，然后键入 s/^/> / 在行首插入 >
    • 注意：不要替换 Subject 所在邮件标题行

完毕后保存到 /path/to/YOUR_REPLY。
最后用补丁页面底部列出的 git send-email 命令来回复这封邮件，保持邮件串连贯。
整个步骤可以使用脚本来处理。

其他工具：b4

b4 堪称补丁管理瑞士军刀
它可以从 Lore 下载补丁系列、检查状态、生成回复模板等等，面向维护者（审阅合并）和贡献者（提交发送）提供了很多不同开发阶段的实用功能。
安装： pip install b4
使用示例：
下载某线程的所有补丁：b4 am -l https://lore.kernel.org/netdev/xxxxxx@example.com/
更多还在不断摸索中…