因为 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
- https://hackerbikepacker.com/b4-for-kernel-contributors
- https://b4.docs.kernel.org/en/latest/
- https://www.marcusfolkesson.se/blog/use-b4-for-kernel-contributions/
- https://yuque.antfin.com/antit/bgvguh/ow3q6bzkowdgmpd3
- https://docs.kernel.org/process/email-clients.html#thunderbird-gui
- https://docs.kernel.org/process/maintainer-netdev.html
- https://patchwork.kernel.org/project/netdevbpf/list/