如何向开源社区奉献代码

从事嵌入式工作, 日常就是与u-boot, linux这些开源代码打交道, 将自己的代码提交到主线, 将是一件快乐而又能提升逼格的事情. 有些比较新的代码会使用github进行bug追踪, pr合并, 这些直接在github提交Pull Request就好了, 比较简单, 就不在赘述. 本文重点介绍如何使用mail list的方式提交自己的代码, 以u-boot为例介绍.

一: 新建分支, 实现功能

当需要实现一个feature或者修改一个bug, 我们需要从master上面切换一个分支:

$ git checkout -b allwinner-r40-usb-otg-v2

之后在当前分支上对主线代码进行修改, 不要将所有的修改都提交到一个commit上面, 而是应该将修改拆分成几个独立的commit, 这样也便于审核和维护. 在commit之前需要配置git的邮箱等信息:

$ git config --global user.name name
$ git config --global user.email xxx@xxx.com

配置完成之后, 可以使用git config --list检查下是否已经设置成功.

开源的代码对commit都有一个约定俗成的三段式写法, 第一段简要写明当前commit修改的主要内容. 第二段可以详细的描述下为什么这么做等等原因. 第三段签上自己Signed-off-by. 下面是u-boot代码中的一个例子:

arm: mvebu: turris_mox: add support for board rescue mode

Add necessary config options and board code to support board factory
reset / rescue mode on Turris MOX.

In order to also support invoking rescue mode from U-Boot console,
without having to press the factory reset button, put the rescue command
into `bootcmd_rescue` default environment variable. When factory reset
button is pressed, invoke rescue mode via distroboot by setting
`boot_targets` to `rescue`.

Rescue boot from console can be invoked by running
  run bootcmd_rescue

Signed-off-by: Marek Behún <marek.behun@nic.cz>
Reviewed-by: Pali Rohár <pali@kernel.org>
Reviewed-by: Stefan Roese <sr@denx.de>

当然, 每次commit都写一个Signed-off-by很费劲, 因此git有选项可以配置一个commit的模板文件, 在每次commit的时候自动填充一些信息:

➜  u-boot git:(allwinner-r40-usb-otg-v2) git config --list | grep commit.template
commit.template=/home/qianfan/.git-commit-template.txt
➜  u-boot git:(allwinner-r40-usb-otg-v2) cat ~/.git-commit-template.txt

Signed-off-by: qianfan Zhao <qianfanguijin@163.com>

➜  u-boot git:(allwinner-r40-usb-otg-v2)

二: 生成, 检查patch

新建一个outgoing文件夹, 将当前的修改输出到patch文件中.

➜  u-boot git:(allwinner-r40-usb-otg-v2) git format-patch master -o outgoing
outgoing/0001-phy-sun4i-usb-Fix-sun8i_r40_cfg.patch
outgoing/0002-dts-bpi-m2u-Enable-USB_OTG-by-default.patch
outgoing/0003-sunxi-defconfig-bpi-m2u-Enable-usb-gadget-and-ums-by.patch

u-boot的源码中有checkpatch.pl程序, 可以对patch的格式进行检查, 在提交之前一定要检查下patch:

➜  u-boot git:(allwinner-r40-usb-otg-v2) ./scripts/checkpatch.pl outgoing/*.patch
---------------------------------------------------
outgoing/0001-phy-sun4i-usb-Fix-sun8i_r40_cfg.patch
---------------------------------------------------
total: 0 errors, 0 warnings, 0 checks, 8 lines checked

outgoing/0001-phy-sun4i-usb-Fix-sun8i_r40_cfg.patch has no obvious style problems and is ready for submission.
---------------------------------------------------------
outgoing/0002-dts-bpi-m2u-Enable-USB_OTG-by-default.patch
---------------------------------------------------------
total: 0 errors, 0 warnings, 0 checks, 31 lines checked

outgoing/0002-dts-bpi-m2u-Enable-USB_OTG-by-default.patch has no obvious style problems and is ready for submission.
------------------------------------------------------------------------
outgoing/0003-sunxi-defconfig-bpi-m2u-Enable-usb-gadget-and-ums-by.patch
------------------------------------------------------------------------
total: 0 errors, 0 warnings, 0 checks, 16 lines checked

outgoing/0003-sunxi-defconfig-bpi-m2u-Enable-usb-gadget-and-ums-by.patch has no obvious style problems and is ready for submission.

NOTE: Ignored message types: COMPLEX_MACRO CONSIDER_KSTRTO ENOSYS MINMAX MULTISTATEMENT_MACRO_USE_DO_WHILE NETWORKING_BLOCK_COMMENT_STYLE PREFER_ETHER_ADDR_COPY USLEEP_RANGE

三: 发送patch

对u-boot而言, 需要将patch发送到maling list: u-boot@lists.denx.de, 同时需要通知相关的维护者. 有时候, 我们也不知道谁是这份代码的维护者, 也不知道应该通知谁. 还好, 有工具可以获取某些patch的维护者:

➜  u-boot git:(allwinner-r40-usb-otg-v2) ./scripts/get_maintainer.pl outgoing/*.patch
Chen-Yu Tsai <wens@csie.org> (maintainer:BANANAPI M2 ULTRA BOARD)
Jagan Teki <jagan@amarulasolutions.com> (maintainer:ARM SUNXI)
Andre Przywara <andre.przywara@arm.com> (maintainer:ARM SUNXI,commit_signer:4/3=100%)
Ivan Uvarov <i.uvarov@cognitivepilot.com> (commit_signer:2/3=67%,authored:2/3=67%,added_lines:688/702=98%,removed_lines:62/62=100%)
qianfan Zhao <qianfanguijin@163.com> (commit_signer:1/3=33%,authored:1/3=33%)
u-boot@lists.denx.de (open list)

按照mailing list的要求, 发送的patch不能有乱七八糟的格式, 就是纯文本, 所以不能用添加附件的方式来发送. 为此, 开源社区的大佬们做了一个git send-email的程序. 如果未安装的话, 可以使用apt安装.

# apt install git-email

安装之后, 需要配置邮箱smtp地址, 账号, 密码等. 下面是我使用的网易邮箱的配置. sendemail.smtppass是邮箱密码的明文.

sendemail.smtpserver=smtp.163.com
sendemail.smtpuser=xxx@xxx.com
sendemail.smtppass=your_email_passwd
sendemail.from=xxx@xxx.com
sendemail.smtpencryption=tls

配置好账号信息之后, 就可以使用send-email发送patch了. 可以将上面得到的维护者的邮箱全部填上:

➜  u-boot git:(allwinner-r40-usb-otg-v2) git send-email outgoing/*.patch -to u-boot@lists.denx.de -cc wens@csie.org -cc jagan@amarulasolutions.com -cc andre.przywara@arm.com -cc marex@denx.de --smtp-debug

待发送完成之后, 可以在patchwork上面找到这个提交: http://patchwork.ozlabs.org/project/uboot/patch/20210616023326.18135-1-qianfanguijin@163.com/

四: 审核意见

当patch发送出去之后, 一般而言并不能直接合并入master, 主线代码维护者会对patch进行审核, 并回复. 回复的信息会发送到邮箱中. 后续可以在使用邮件进行沟通. 邮箱客户端推荐使用Mozilla Thunderbird.

对审核的建议作出修改, 需要使用git rebase回退到某一个commit修改, 全部修改完成之后, 生成patch, 重复send-email的工作即可.