Author: Chuanyu Xue – University of Connecticut
Let me first explain why I decided to submit a patch…
Recently, I was working on a research project that utilized the DPDK framework. During the process, I realized that the framework’s driver did not implement all the functionalities specified by the network card. Since one particular functionality, the “launch time feature”, was essential for my work, I spent some time modifying the driver for my project to use this feature.
After that, I decided to invest some time integrating this patch into the DPDK framework, basically for two main reasons. First, I believe this feature is essential for real-time community to use DPDK, and I have seen several discussions online about it, suggesting that its implementation could benefit many others. Secondly, I had never contributed to a large open-source project before and saw this as an opportunity to learn the basic process of submitting patches.
1. Preparation
Before submitting the patch, it’s crucial to understand the project’s development process. DPDK is an open-source project currently managed by Linux Foundation. The development of DPDK happens on the mailing list (like Linux kernel) instead of on GitHub.
This means we can’t simply use git commit to submit patches, then followed by a pull request. Instead, patches are submitted via email to maintainers. Therefore, some extra preparatory steps are needed before submission, including:
- Registering and subscribing to the DPDK mailing list
- Configuring email to use git-send-email
- Identifying the maintainers and the subtree of the module you are modifying
Mailing List: The process of registering and subscribing to the mailing list is relatively straightforward and can be done by following the steps in the DPDK official documentation. I won’t repeat that here. I also recommend registering for Patchwork to easily track the code review process. From my experience, it’s best to disable receiving all the emails from the mailing list or set the digest mode to only receive one summary per day, otherwise the daily generated patches will mix with the regular email and overflow the mailbox…
Email Configuration: Setting up the email is also quite simple. I used a Google email, and configured it following this article to link git send-email. I didn’t encounter any issues during the process.
Finding Maintainers: DPDK is a large, modular open-source project, designed for collaborative work. Each module has a designated maintainer, and some even have specific maintenance branches. Therefore, it’s necessary to find the maintainer and the branch of the module you want to modify, and submit the patch to them for integration into the mainline repository. An important point to note is to use the script devtools/get-maintainer.sh in the repository to automatically find the maintainers to Cc, just like this:xxxxxxxxxxgit send-email –to dev@dpdk.org –cc-cmd devtools/get-maintainer.sh
The first time, I attempted to find maintainer information in the list provided in the documentation and manually added it to the CC field. However, I later discovered that this information was outdated, which led me to inadvertently send the patch to a previous maintainer…
As for understanding the project’s coding style, I suggest not spending too much time studying the official style guide. This is because you can ensure the consistency of the coding style with the automated review scripts mentioned later.
2. Writing the Patch
The process of writing the patch is essentially modifying the original code to fix bug or add new functionalities, and after formatting it with diff, these modifications become the patch. An important suggestion here is to disable the auto-formatting feature of your IDE. Many projects have unique code formatting styles, and auto-formatting might mess up the format with Tab/Space changes everywhere.
2.1 Testing
Testing is divided into three main parts:
- Compilation and functional testing
- Code style check
- ABI Policy
Compilation and Functional Testing: Since my modifications were minor, I only compiled it on my local machine. The specific process is largely similar to installing DPDK, except the first step involves using meson setup --wipe build to clear the previous build directory. For functional testing, I recommend testing all DPDK built-in apps that might be affected, such as dpdk-testpmd.
Code Style Check: This part can be done following the Section 5.7 Checking the Patches in the DPDK official tutorial. It’s important to note that you need to download checkpatch.pl yourself (You can get the source code by Google searching, just a simple script). After generating codespell-dpdk.txt as instructed, run devtools/checkpatches.sh patch_name.patch in the same directory. The output log shows the results, where both errors and warnings need to be corrected, but some checks may not need changes if they are unreasonable.
ABI Policy: ABI Policy refers to the requirements for variable and function naming. It is recommended to self-check against the official ABI Guideline. But personally, I feel if no new file is created, there shouldn’t be many issues, just compare with the surrounding code to get a sense of the appropriate naming conventions.
2.2 Submitting the Patch
After testing, it is good to generate the patch. Before doing so, it’s recommended to double-check your git username and email, using git config --global user.name & git config --global user.email.
My method of generating patches might not be the best practice. I initially used git add & git commit for a simple commit, then git commit --amend to modify the commit message. Finally, I generated the patch with git format-patch -1 -o ~/patch/. Here -1 indicates the patch-set includes the last few commits, but I only needed to generate one patch.
Before submission, check if the patch contains the Signed-off-by: xxxxx <xxxxxx@xxx> line. Mine wasn’t generated automatically, so I added it manually.
Finally, the patch can be submitted via git send-email, typically --to the mailing list dev@dpdk.org, and --cc to maintainers.xxxxxxxxxxgit send-email \–to dev@dpdk.org \–cc-cmd devtools/get-maintainer.sh \ ./patch_name.patch
Before sending, it is best to first send it to yourself to check if the email format is correct with git send-email --to=[your email] patch_name.patch.
If you have registered for Patchwork, you’ll receive the patch submission notification after a few hours.
3. Code Review
Compared to smaller open-source projects, code review in DPDK is quite stringent, involving both automated reviews from the system and manual reviews from maintainers.
The results of the automated review are received via email within a few hours of submission. Fortunately, despite this being my first patch submission, no errors were detected with beginner luck.
In the subsequent manual review phase, maintainers pose questions about the content of the patch, which feels similar to the rebuttal phase of a research paper submission process. The main issues raised in my case focused on:
- Explaining the functionality of different lines of code
- Justifying the chosen solution
- Providing test results
Responding directly to these questions is usually sufficient. A few minor details to note:
- When replying, use the
--in-reply-toparameter to specify which email you are responding to.
xxxxxxxxxxgit send-email \ –in-reply-to=xxxxxxxx.namprd11.prod.outlook.com \ –to=xxxx@xxx.com \ –cc=xxxx@xxx.com \ –subject=”RE: [PATCH] net/e1000: support launchtime feature” \./reply.txt
- Pay attention to formatting. Indicate references to previous emails by adding
>. - In the subject, add
RE:before the title of the patch. Remember, no matter how many times you reply, there should only be oneRE:, not a chain likeRE: RE: RE:.
4. Lessons
Although the process seemed somewhat complicated to me initially, the friendly atmosphere made it smoother. From submission to the final review, it took me over ten days, which included three replies and one code update. Along the way, I encountered some technical issues and uncertainties. However, these were resolved with the help of the maintainers and other developers, who provided guidance and support throughout the process.
The biggest takeaway for me from this experience is that contributing to a large open-source project is not as daunting as it might seem. It’s often the intricate rules and the stereotypes about open-source communities that dissuade people from getting involved. However, I found that the community was welcoming, and the process, while detailed, was manageable when you are willing to spend some time on it.
Although contributing to the open-source community is not my focus, attempting to submit a patch was definitely a valuable experience.
Follow Chuanyu Xue on Medium here
Get started with DPDK here