如何开始向 Linux kernel 贡献代码

Email workflow 实战

因为 BitKeeper 不让 Linus 白嫖代码管理功能,Linus 一气之下随手做了个小工具 —— Git,然后 Git 开始统治版本管理工具直到现在。Git 设计之初是通过邮件的形式发送和接收 patchset,这种古老的方式一直保持到现在,以至于与使用 GitHub 管理代码的方式相比,已经是完全两种贡献体验了。又因为 Linux 下面子社区众多,每个社区又有不同的规矩,这让新手贡献代码时非常头痛。

我一开始使用的是 Git 自带的命令,如 git format-patch,管理和回复邮件,使用体验就像是手动挡汽车,用起来很不方便,需要同时坚固 cover letter 更新、版本管理等等,出错概率就会明显提升。事实上社区发展这么多年,已经有一套相对好用的工具,这篇文章就介绍如何使用 b4 管理 patchset 以及如何使用 Thunderbird 作为邮件客户端回复 reviewer 审查意见。

Table of Contents

编写并发送 Patchset

设置 git smtp 邮箱,你的 commit author 邮箱最好跟这里的 smtpuser 是一样的

$ vim ~/.gitconfig
[sendemail]
smtpuser = <your email>
smtpserver = <smtp server>
smtpencryption = <ssl?/tls?>
smtpserverport = <port>

使用 b4 发送和管理 patchset,主文档参见 [2],其他教程参见 [1] 和 [3]

# 为一个 patchset 创建一个单独的分支 b4/$BRANCH
$ b4 prep -n $BRANCH
# 编译 cover letter(TODO: 是否可以不带 cover letter?)
$ b4 prep --edit-cover

接下来你就要自己写 patch 了

  • 如果你编写的是网络相关的部分(net/),参考 tip1。
  • 如果你需要引用别人的代码,参见 tip2。

编写完代码后,接下来准备发送你的 patchset 吧!

如果这是你的第一个版本,那么你还需要根据改动代码寻找合适的 reviewer。

$ b4 prep --auto-to-cc

如果之前的版本已经有 maintainer 发送 "Acked-by: someone [email protected]" 或者 "Reviewed-by: someone [email protected]",那么 b4 可以很轻松的收集它们并追加到 commit message 里。

$ b4 trailers -u

接下来进一步检查代码是否存在问题,发送给自己检查最终的格式,如果一切正常,那么就发送吧!

# 检查代码是否有问题
$ b4 prep --check
# 【可选】创建一个新的分支,把当前 patches 都 rebase 过来(需要 drop 掉 cover letter)
# TARGET_BRANCH 是基础的分支
$ ./scripts/checkpatch.pl -g $TARGET_BRANCH..HEAD --codespell
# 发送给你自己找问题
$ b4 send --reflect --no-sign
# 正式发送 patch 并使 version + 1,在自动 cc/to 的基础上可以自己额外指定 cc 地址
$ b4 send --cc EMAIL --no-sign

Tips

Tip1: Netdev 开发指南

推荐阅读 netdev maintainer 手册 [6]。

Netdev 包含两个 trees: (1) net: 用于修复已有特性,git 仓库地址是 https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git;(2) net-next: 用于接收新特性,git 仓库地址是 https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git。

你需要根据工作类型选择一个 tree,你的 patch 需要在该 tree 上做 rebase 操作,还需要在 prefix 中添加 tree 的名称。

# 添加 prefix,所以实际的 title 是 [PATCH net-next v1]
$ b4 prep --set-prefixes net-next

代码变量声明需要遵循 reverse xmas tree,排列顺序需要遵循倒三角

// good case
void test1()
{
int aaa_bbb_ccc;
int aaa_bbb;
int aaa;
}
// bad case
void test2()
{
int aaa_bbb;
// 这个声明比上面的长
int aaa_bbb_ccc;
int aaa;
}

在发送完你的 patchset 之后可以到 [7] 查看你的 patch 的状态,比如当你的代码没有正确 rebase 相应的 tree 时错误可以在这里查询。

Tip2: 引用他人代码

在开发过程中可能出现引用别人代码的情况,要检查 author 保持一致,同时添加自己 S-o-b。

# 修改 commit author 信息并添加自己的 s-o-b
$ git commit --amend -s --author "Name <Email>"

检查 cover letter 中的作者是否被正确设置

---
<Other Author> (1):
      hv_sock: Return the readable bytes in hvs_stream_has_data()

<You> (3):
      vsock: Add support for SIOCINQ ioctl
      test/vsock: Add retry mechanism to ioctl wrapper
      test/vsock: Add ioctl SIOCINQ tests

回复 Reviewer

由于 maillist 强制使用 plain text 来回复邮件,比如 netdev 在发现有 HTML 格式时会拒绝收信,因此强烈建议使用单独的邮箱客户端用于内核开发,我选择的是 Thunderbird。使用 IMAP 登录邮件后,需要设置使用 plain text 查看和回复邮件,具体设置参见 [5]。

注意事项:回复别人的邮件一定要 "Reply All",否则没法正常在 maillist 中追踪。

References

  1. https://hackerbikepacker.com/b4-for-kernel-contributors
  2. https://b4.docs.kernel.org/en/latest/
  3. https://www.marcusfolkesson.se/blog/use-b4-for-kernel-contributions/
  4. https://yuque.antfin.com/antit/bgvguh/ow3q6bzkowdgmpd3
  5. https://docs.kernel.org/process/email-clients.html#thunderbird-gui
  6. https://docs.kernel.org/process/maintainer-netdev.html
  7. https://patchwork.kernel.org/project/netdevbpf/list/
All rights reserved
Except where otherwise noted, content on this page is copyrighted.