前言

先沐浴一下DPDK的官方语言：

DPDK is an open source project, with the main code BSD licensed and Linux kernel related parts are naturally licensed under the GPL. We welcome and encourage anyone who is interested to contribute and participate in the project.

DPDK 是一个开源项目，主要代码通过 BSD 获得许可，Linux 内核相关部件自然根据 GPL 获得许可。我们欢迎并鼓励任何有兴趣参与该项目的人。

所以积极的投入DPDK社区吧！！！

---

1. 给DPDK贡献的方式

给DPDK做出贡献的方式有以下几种：

1. Contribute by sending patches 
2. Contribute by testing or reviewing patches
3. Contribute by finding or fixing bugs

本文主要讲述第一种方式：发送补丁

说明：作者使用的系统是centos7，所以相关的命令也是此系统下的

2. 准备工作

2.1 阅读DPDK贡献指南

在给DPDK发送补丁之前，需要先学习一下相关的指南，最好的指南当然是官方的文档，文档地址如下：

DPDKhttps://core.dpdk.org/contribute/6. Contributing Code to DPDK — Data Plane Development Kit 21.11.0-rc0 documentationhttps://doc.dpdk.org/guides/contributing/patches.html以上两个文档主要讲述关于给DPDK贡献的内容，比如代码风格，如何做补丁以及发送补丁，补丁格式要求等，如果读者英文水平比较好，可以直接跳转到这里学习，否则可以参考本文的教程，但是无论如何都要看一下代码风格，因为这关乎到你的补丁是否合格以及是否被采纳。

DPDK代码风格：1. DPDK Coding Style — Data Plane Development Kit 21.11.0-rc0 documentationhttps://doc.dpdk.org/guides/contributing/coding_style.html#coding-style

2.2 账号、用户名、邮箱

在进行下面两个步骤前，这里有必要先说明一下下面用到的账号、用户名、邮箱等含义，防止读者混淆；

smtp账号：邮箱地址，用于发送邮件；

smtp服务：用于转发邮件；

git全局用户名：贡献者的真实姓名全拼，注意姓在后，和前面的名字之间有一个空格，在git commit时用于签名以及发送邮件时显示的Submitter名字（注：Submitter的名字其实就是你发送给对方时在对方的邮箱里显示的名字，应该是在你的邮箱里的“发件人管理”进行设置，名字和git全局用户名保持一致），如作者名字：Huichao Cai，注意首字母大写，下面的示例中huichao cai是错误的，请注意；

git全局邮箱：用于git commit时的签名和发送邮件；

注册DPDK用户名：贡献者的真实姓名全拼，格式同git全局用户名；

注册DPDK邮箱：用于接收DPDK社区的邮件，如补丁邮件等，后续和社区的大神们进行沟通（互发邮件的方式）也是通过该邮箱；

说明：

1. 补丁是以邮件的形式发送的；

2. 发送邮件时要求smtp账号和git全局邮箱是一样的；

3. 如果smtp账号和注册DPDK邮箱不一样，在发送补丁邮件后，会收到dev-owner或stable-owner（你发送补丁的地址）的回复邮件（如下图所示），里面会说你的补丁邮件会暂时被悬置直到管理员审核通过才会在 DPDK Patchwork 列表里看到你的补丁邮件，原因是发送邮件的账号不是DPDK的成员（注册DPDK的邮箱），需要审核，这样就会导致你的补丁处理时间加长，如果想马上在 DPDK Patchwork 列表里看到你的补丁邮件，那么这两个邮箱保持一样即可；

综上所述，为了方便，这些邮箱和用户名最好保持一致；

2.3 git环境搭建

DPDK是通过git进行代码管理的，其中主要的工具有 git send-email 和  git format-patch ，补丁是通过 git send-email 发送的，补丁的制作工具是 git format-patch ，所以需要先安装和配置这些工具；

安装git send-email：yum install git-email

在安装git后应该会默认有git format-patch命令；

配置git：vi ~/.gitconfig，修改gitconfig文件，添加以下内容：

[sendemail]
	suppressfrom = true
	chainreplyto = false
	confirm = always
	envelopesender = auto
	smtpuser = [email protected]
	smtpserver = smtp.domain.com
	smtpserverport = 465
	smtpencryption = ssl
[alias]
	fixline = log -1 --abbrev=12 --format='Fixes: %h (\"%s\")%nCc: %ae'

其中[email protected]为你的smtp的账号，smtp.domain.com是smtp的服务器地址，其他按照示例即可，可以在网上找一些公共免费的smtp服务(如163的smtp.163.com)。

然后配置git的全局用户名和邮箱：

git config --global user.name "username"

git config --global user.email "email"

2.4 注册DPDK

在贡献补丁之前，需要先在DPDK相关的机构注册自己的信息，至少需要注册的两个机构是：DPDK development和DPDK Patchwork；

DPDK development：是个邮件列表地址（ [email protected]），补丁发送到这里，订阅这个主题的人会收到该补丁邮件；

DPDK Patchwork：补丁存储、展示、操作的地方，所有贡献者发送的补丁都会在这里展示，当然也可以查看自己的补丁；

DPDK development注册地址： dev Info Page (dpdk.org)或者Contribute - DPDK

DPDK Patchwork注册地址：Project List - Patchwork (dpdk.org)

3. 补丁实操

3.1 源码下载、修改 

用git下载源码：

git clone git://dpdk.org/dpdk

或者：

git clone http://dpdk.org/git/dpdk

修改代码要遵守 DPDK Coding Style，并且通过编译，然后用git commit提交到本地，补丁的内容就是git commit的内容，git commit的内容要求如下：

3.1.1 主题行

首先看一下主题行示例，在DPDK源码库下执行git log，如下图，红框框住的那些行就是主题行：

主题行必须涵盖修改的范围和影响；

主题行包含字符50个左右；

主题行应该是小写，除了首字母缩略词，如RFC；

主题行应该以对应（你本次修改的内容）的组件名为前缀，如下：

ixgbe: fix offload config option name

config: increase max queues per port

其中组件名可以用git log changed-file查看已经存在的，如下红框内就是组件名（不包含":"）：

比如作者修改了rte_ipv4_fragmentation.c文件，执行：git log lib/ip_frag/rte_ipv4_fragmentation.c搜索到组件名如下：

主题行尽量使用动词；

主题行不要用"."等结束符结尾，因为在制作补丁时，补丁文件的名字包含主题行，并在主题行后加上".patch"，如果主题行以"."结尾，则补丁文件的名字会成为"..patch"；

3.1.2 内容体 

先看一下示例，同样用git log查看，如下红框内的就是内容体：

内容体应该描述修改的问题或添加的功能，尽量描述的详细一些以便让审查者能够很好的理解你的补丁；

内容体必须以你的签名结束，如上面的Signed-off-by:这一行，当然不用你手动输入，在git commit时加上--signoff或-s即可：git commit --signoff # or -s，可以看到签名就是配置的git全局邮箱和用户名

如果修改的内容比较简单明显，则不需要内容体，但是要保证有签名；

签名必须是真实的名字，不能用别名或昵称，可以有多个签名；

内容体字符数应该在72个以内；

修改一个bug回归时，需要在内容体里手动添加该bug对应的commit id和对应的作者，你可以使用git命令：git fixline <SHA>（<SHA>为commit id），输出要添加的内容，此命令已在前面的步骤中配置到了git配置文件中，示例如下：

doc: fix some parameter description

Update the docs, fixing description of some parameter.

Fixes: abcdefgh1234 ("doc: add some parameter")
Cc: [email protected]

Signed-off-by: Alex Smith <[email protected]>

其中两行：

Fixes: abcdefgh1234 ("doc: add some parameter")

Cc: [email protected]

为git fixline <SHA>输出的内容（在发送邮件时会自动抄送给Cc:后面的地址，无需在发送命令里单独--cc指定了）；

当修复一个错误或告警时，在内容体添加错误信息以及如何复现错误的信息是很有用的；

内容体要使用正确的大写、标点符号和拼写，就是英文要写正确，毕竟审核的人有些是老外；

内容体除了Signed-off-by:标签，还可能有其他标签，如Reviewed-by ：Acked-by：等，如下：

3.1.3 其他

如果用代码静态检查工具Coverity 扫描出issue，内容体必须包含 Coverity issue id，例如：

doc: fix some parameter description

Update the docs, fixing description of some parameter.

Coverity issue: 12345
Fixes: abcdefgh1234 ("doc: add some parameter")
Cc: [email protected]

Signed-off-by: Alex Smith <[email protected]>

如果修复的是bug追踪工具Bugzilla 里的issue，内容体必须包含Bugzilla issue id，例如：

doc: fix some parameter description

Update the docs, fixing description of some parameter.

Bugzilla ID: 12345
Fixes: abcdefgh1234 ("doc: add some parameter")
Cc: [email protected]

Signed-off-by: Alex Smith <[email protected]>

如果补丁被要求backport到稳定版本，内容体需要包含Cc: [email protected] ，如下：

doc: fix some parameter description

Update the docs, fixing description of some parameter.

Fixes: abcdefgh1234 ("doc: add some parameter")
Cc: [email protected]

Signed-off-by: Alex Smith <[email protected]>

更多信息请参考：8. DPDK Stable Releases and Long Term Support — Data Plane Development Kit 21.11.0-rc0 documentationhttps://doc.dpdk.org/guides/contributing/stable.html

 如果补丁有依赖其他补丁，需要在commit的内容体里或者cover letter里（也可在补丁文件里，如下说明）添加说明：

Depends-on: series-NNNNN ("Title of the series") or Depends-on: patch-NNNNN ("Title of the patch")

NNNNN 是依赖的补丁在patchwork 上的id，如：

如下：

doc: fix some parameter description

Update the docs, fixing description of some parameter.

Signed-off-by: Alex Smith <[email protected]>
---
Depends-on: series-10000 ("Title of the series")

 说明：补丁文件里的“---”符号下面可以添加一些额外的简短的说明，如下：

 DPDK源码库里有个脚本devtools/check-git-log.sh可以对commit的信息进行一些检查，如在DPDK源码库根目录下执行./devtools/check-git-log.sh -n2：

表示检查最近的两次commit信息，输出结果表示检查了2个commit信息（一个commit对应一个补丁），可用2个，检查通过，如果有问题，会输出相应的错误信息；

3.2 补丁制作

如上所述，一个commit对应一个补丁，即在制作补丁时，一个commit会生成一个补丁，通过-1 -2 等参数可以指定生成多少个补丁，顺序是从最近的commit开始制作；

执行git format-patch制作补丁，以下是一些使用参考：

# Generate a patch from the last commit.
git format-patch -1

# Generate a patch from the last 3 commits.
git format-patch -3

# Generate the patches in a directory.
git format-patch -3 -o ~/patch/

# Add a cover letter to explain a patchset.
git format-patch -3 -o ~/patch/ --cover-letter

# Add a prefix with a version number.
git format-patch -3 -o ~/patch/ -v 2

比如作者计划制作一个补丁（第一个commit点），输出到/tmp/patch目录下，则执行：

git format-patch -1 -o /tmp/patch

生成补丁如下：

再看一下commit信息：

可以看到补丁的文件名包含了主题行；

关于--cover-letter和同一个补丁的后续补丁（后续补丁会从v2版本开始，并且作为对第一个补丁的回复）的内容请参考DPDK官方文档说明；

3.3 补丁检查

补丁检查主要有三部分：

补丁格式和语法检查、补丁编译检查、补丁ABI兼容性检查；

补丁格式和语法检查使用DPDK源码库里的devtools/checkpatches.sh脚本进行检查，不过该脚本依赖linux内核下的工具checkpatch.pl，所以需要下载linux内核源码，把里面的checkpatch.pl文件放到该环境下，如放到/tmp目录下，然后执行：export DPDK_CHECKPATCH_PATH=/tmp/checkpatch.pl，这时就可以在DPDK源码库根目录下执行：./devtools/checkpatches.sh /tmp/patch/0001-test-ipfrag-add-test-content-to-the-test-unit.patch，结果如下：

表示检查了一个补丁，可用1个，检查通过，如果有问题，会输出相应的错误信息；

如果想对补丁内容的单词拼写进行检查（同样使用checkpatches.sh脚本），需要把字典文件dictionary.txt文件放到/usr/share/codespell/目录下（此目录为默认目录，也可以放到其他目录，但是要设置DPDK_CHECKPATCH_CODESPELL为其他目录，同上面的设置命令一样，使用命令export DPDK_CHECKPATCH_CODESPELL=/dir/xxx.txt设置），DPDK有个脚本专门生成DPDK专用的字典文件，获取该文件：

git clone https://github.com/codespell-project/codespell.git
./devtools/build-dict.sh codespell/ > codespell-dpdk.txt

如果不使用默认目录，则字典文件的名字可以任意；

检查命令同补丁格式和语法检查：./devtools/checkpatches.sh /dir/xxx.patch

补丁编译检查是通过devtools/test-meson-builds.sh脚本完成的，直接执行：./devtools/test-meson-builds.sh即可，会在当前目录下创建子目录，并把编译结果放到该子目录里，当然可以通过DPDK_BUILD_TEST_DIR 指定不同的目录；

补丁ABI兼容性检查默认是关闭的，这里不再描述；

3.4 补丁发送

使用git send-email发送补丁，一般需要发送给[email protected]和你修改内容对应的组件维护者，比如作者修改的ip分片相关的测试用例代码（修改test_ipfrag.c文件），对应的组件维护者在DPDK源码库里的MAINTAINERS 文件里查找，如下：

关于M、F等字符的含义，参考6.3章节：6. Contributing Code to DPDK — Data Plane Development Kit 21.11.0-rc0 documentationhttps://doc.dpdk.org/guides/contributing/patches.html#commit-messages-body接下来就可以执行发送命令了（如果是第一次操作，可以先发给自己或者加--dry-run 参数测试一下）：

发给自己：

git send-email --to “自己的邮箱” /tmp/patch/0001-test-ipfrag-add-test-content-to-the-test-unit.patch

发给DPDK社区：

git send-email --to [email protected] --cc [email protected] /tmp/patch/0001-test-ipfrag-add-test-content-to-the-test-unit.patch

说明：--cc表示邮件抄送，凡是订阅了[email protected]的贡献者，都可以收到你的这个补丁邮件，包含你自己，当然你可以在注册时的设置里关闭接收等，相关的配置请登录：

dev list: member options login pagehttps://mails.dpdk.org/options/dev/git常用语：

Git 协助常用缩写释义_一个狂徒的点滴记录、-程序员宅基地WIP   Work in progress, do not merge yet. // 尚未完工，请不要合并LGTM Looks good to me. // 我看行。（Riview 别人的 PR 确认没有问题）PTAL Please take a look. // 帮我看下，一般是请别人 review 自己的 PRCC Carbon copy // 抄送RFC  —  request for comments. // 请求评议。通常是讨论、起草某一功能特性的方案及标准IIRC  —  if .https://blog.csdn.net/ufolr/article/details/108952765

有经验的贡献者可以直接执行git send-email省去 git format-patch这一步，不过需要加上--annotate 和confirm = always参数等，作者也是刚接触不久，所以还是按照步骤一步一步操作吧；

有时补丁会被要求backport到稳定版本，这个前面已经说过，请参考官方文档，这里不再详述；

3.5 补丁确认

在成功发送补丁后，登录DPDK Patchwork，即可看到你的补丁，如作者提交的补丁：

上面的红框表示当前补丁的状态，读者可以登录进去后详细查看；

关于补丁状态以及是否会被merge等更多详细信息请参考官方文档；

这里注意一下，Patchwork是可以设置搜索条件的，如默认情况下的搜索条件如下：

 点击黑色的可以删掉搜索条件；

点击“Show patches withShow patches with”可以添加搜索条件，如下：

红色框内的为默认的条件，可以在空格内设置自己想要的搜索条件：

3.6 补丁管理 

为了方便管理自己的补丁，Patchwork提供了管理工具Bundles，进入任意一个补丁，创建自己的Bundle，如下：

在空格里输入自己Bundle的名字，然后点击“Create”按钮即可创建自己的Bundle.

同样，在创建好Bundle后，进入想要绑定到该Bundle的补丁链接里，选择自己创建好的Bundle，点击“Add”即可，当然你既可以绑定自己的补丁也可以绑定别人的补丁，如下绑定自己的补丁：

 也可以批量绑定补丁，如下根据搜索条件过滤补丁后，选中补丁，批量绑定：

 绑定补丁之后，就可以在自己的Bundle里查看了，如下：

 

注意去掉默认的搜索条件：

 绑定的补丁如下：

 也可以把已绑定的补丁去绑定，如下：

 补丁的状态可以查看如下，这些状态一般不需要你去设置，都是审核人去设置的：

已创建的Bundle也可以修改名字或者删除，还可以设置是否公开可见等，如下：

在提交补丁成功后，后续请持续关注补丁状态（比如登录DPDK Patchwork 查看自己的补丁状态或者查看自己的注册邮箱有没有收到相关邮件等），如果有问题可能需要你重新发送补丁等，当然所有的工作都是为了让自己的补丁能够被merge！！！

---

总结

关于如何给DPDK开源社区提交补丁大致步骤就介绍完了，更详细的内容还是需要阅读官方文档的，所以英语还是很重要的，作者在提交补丁前也是苦苦搜索了好久，几乎没有中文文档，于是就有了这篇文档的产生，希望能够帮助到有开源贡献精神但是不知如何实施的朋友，也欢迎各位提出文档中存在的问题，并完善文档，以帮助更多的开源人！！！