如何向开源社区奉献代码

ゝ一世哀愁。 2022-10-12 01:49 179阅读 0赞

从事嵌入式工作, 日常就是与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的工作即可.

--------------------

*感谢完成阅读，我是喜欢打篮球的写代码的篮球球痴，这个是我的公众号，感谢你关注并支持。我从大学开始接触电子和嵌入式软件知识，至今，已经毕业工作了9年，我喜欢嵌入式，也愿意从事这个行业。不管是从技术还是职场经验，都积累了足够多的经验，目前在一个非常优秀的团队中做开发工作。*

*很高兴认识每一个对技术努力，对人用心的朋友。*