Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 81

Linux Kernel Patch Review & LKML Navigation

Recommended resources

Introduction

Welcome to the final module of our course. Over the past several modules, you've built a formidable set of technical skills, from compiling the kernel and navigating its source to debugging complex user-space and kernel-level virtualization components with tools like GDB and QEMU's tracing system. Now, it's time to pivot from theory and isolated practice to real-world application.

This module is dedicated to the process of contributing to open-source projects, a key goal you set for your career development. Our objective for this lesson is to help you navigate the Linux Kernel Mailing List (LKML) archives and understand the community patch review process.

Before you can write a line of code for submission, you must understand the environment where all development happens. The Linux kernel community uses a decades-old, highly-refined, email-based workflow. Mastering its nuances is the first and most critical step to becoming a successful contributor. We will dissect this process, from finding information to understanding the unwritten rules of engagement.

1. The Hub of Kernel Development: The LKML

The Linux Kernel Mailing List (LKML) is the primary public forum for all discussion, development, patch submission, and review related to the kernel. Unlike modern platforms like GitHub which use web-based pull requests, the kernel community relies almost exclusively on plain-text email. This ensures maximum accessibility, allows for robust archiving, and supports a powerful inline commenting and review workflow.

Becoming a Kernel Developer (2/3): Posted patches, what next?

To start, let's get a feel for the basic etiquette and purpose of the LKML. This article from Linaro provides a concise overview.

Read the introduction and the section titled 'The Linux Kernel Mailing List (LKML)'. Pay close attention to the netiquette points, such as using plain text and avoiding top-posting. These are fundamental for effective communication.

As you've just read, the LKML has a specific culture. Your ability to communicate professionally and adhere to these conventions is just as important as the technical quality of your code.

2. Navigating the Archives: How to Find Information

Subscribing to the LKML can result in hundreds or even thousands of emails per day. It's generally impractical. Instead, developers interact with the LKML through its web-based archives. The most popular and feature-rich archive is lore.kernel.org.

Let's watch a brief segment that shows how to find the mailing lists and browse the archives.

Creating And Submitting Patches to the Linux kernel community

This video provides a quick visual tour of the mailing list section on kernel.org and what a patch email looks like in the archive.

Watch from 00:27:14 to 00:30:15. The speaker demonstrates navigating to the mailing list archives from kernel.org and shows the structure of a patch email thread.

The interface shown in the video is a classic mail-archive view. Modern interfaces like lore.kernel.org present this information in a more threaded, web-forum-like manner.

Linux Kernel Mailing List (LKML) Patch Series Example
This screenshot shows a typical patch series as viewed on lore.kernel.org. Note the subject line prefixes: `[PATCH 00/12]` is the "cover letter" describing the entire series, followed by the individual patches. The nested replies from developers like Greg Kroah-Hartman are the public code review.

Key features of lore.kernel.org to explore:

  • Search: You can search by subject, author, or Message-Id.
  • Threading: The nested view clearly shows who is replying to whom.
  • Permalinks: Every message has a unique, permanent link, which is invaluable for referencing discussions.

3. The Patch Review Process: A Step-by-Step Guide

Once a developer emails a patch to the appropriate list, it undergoes a public review. This iterative process is the cornerstone of the kernel's quality control.

The Lifecycle of a Patch

  1. Submission: The author sends the patch or patch series as a plain-text email.
  2. Review: Other developers, including subsystem maintainers, review the code. They reply to the email with inline comments, questions, and suggestions for improvement.
  3. Feedback Tags: As reviewers scrutinize the patch, they may add formal "tags" in their replies. These are crucial signals to the maintainer.
  4. Iteration: The author collects the feedback, revises the code, and submits a new version (e.g., [PATCH v2]...). This version is sent as a reply to the cover letter of the previous version to keep the thread organized.
  5. Acceptance: When the subsystem maintainer is satisfied, they will "pull" the patch into their development branch, from which it will eventually make its way into the mainline kernel.

Understanding the Tags

The review process is formalized through several key tags, which you'll see in email replies and commit messages.

Becoming a Kernel Developer (2/3): Posted patches, what next?

This article provides an excellent explanation of the most common tags you'll encounter and what they signify.

Read the section 'Reviewing and Testing Patches'. Focus on understanding the distinct meanings of Reviewed-by: and Acked-by:. This is critical for interpreting the status of a patch in a review thread.

In addition to the tags you just read about, the most fundamental tag is added by the author themself.

Write and Submit your first Linux kernel Patch

Greg Kroah-Hartman, a prominent kernel maintainer, explains the legal and procedural significance of the Signed-off-by: line. This is non-negotiable for any contribution.

Watch from 21:23 to 22:59. Listen carefully to the explanation of the Developer's Certificate of Origin and how the Signed-off-by: line serves as both a legal attestation and a path of blame.

To summarize the key tags:

  • Signed-off-by:: Added by the author and maintainers. Legally certifies that you have the right to submit this work (Developer's Certificate of Origin). It creates a chain of trust.
  • Reviewed-by:: Added by a developer who has done a thorough review and believes the patch is correct and ready for inclusion.
  • Acked-by:: Added by a maintainer or domain expert who agrees with the change in principle but may not have done a full, line-by-line review.
  • Tested-by:: Added by anyone who has successfully tested the patch and confirms it works as expected and introduces no regressions.

4. Finding the Right Recipients

A common mistake for newcomers is sending a patch to the main LKML address. Patches should be sent to the specific maintainer(s) and mailing list for the subsystem you are modifying. But how do you find them? The kernel source tree provides a script for exactly this purpose.

Write and Submit your first Linux kernel Patch

Let's see a demonstration of get_maintainer.pl, the canonical tool for identifying the correct recipients for a patch.

Watch from 25:58 to 26:48. Greg Kroah-Hartman demonstrates how to run the get_maintainer.pl script on a patch file to get a list of maintainers and mailing lists.

As you saw, you run the script on your patch file (.patch) or on the source files you've modified:
./scripts/get_maintainer.pl my-cool-fix.patch

The script will output the email addresses of the relevant maintainers and the specific mailing lists to CC. You will use this list of recipients when you send your patch.

5. Tools for a Smoother Workflow

While the process is email-based, a rich ecosystem of tools has been built to streamline it.

  • git format-patch: Creates the email-formatted patch files from your git commits.
  • git send-email: A command-line tool for sending your formatted patches, correctly handling them as plain text and avoiding corruption by graphical email clients.
  • b4 and lei: Modern helper tools that can fetch an entire patch series from lore.kernel.org and prepare it as a local mailbox file, which you can then apply to a git branch for testing.
Linux Kernel Patch Retrieval and Review Process via 'b4' Tool
This terminal output shows the `b4` tool being used to fetch a patch series. It analyzes the thread on lore.kernel.org, downloads the patches, and notes the `Reviewed-by` tags, preparing a mailbox file ready for use with `git am`.

These tools are essential for managing the workflow efficiently. We will practice using them in subsequent lessons.

Finally, what happens if you send your patch and hear nothing back?

Write and Submit your first Linux kernel Patch

Greg Kroah-Hartman gives some final, crucial advice on how to follow up if your patch doesn't get a response.

Watch from 36:01 to 36:31. The key takeaway here is the difference between being annoying and being persistent.

Conclusion

In this lesson, we've demystified the social and procedural heart of Linux kernel development. You now have the foundational knowledge to engage with the community effectively.

Key Takeaways:

  • The LKML is the central, email-based forum for all kernel development. Communication must be professional, public, and in plain text.
  • You can navigate the vast history of kernel development using web archives, primarily lore.kernel.org.
  • The review process is an iterative public conversation. Formal approval is signaled with tags like Signed-off-by:, Reviewed-by:, and Acked-by:.
  • Patches must be sent to the correct recipients. Use the get_maintainer.pl script to identify the right maintainers and subsystem mailing lists.
  • A suite of tools like git send-email and b4 helps streamline this unique workflow.

Preview of the Next Lesson:

You now understand the rules of the road. In our next lesson, we will address the question: "What should I work on?" We will explore strategies to identify a suitable first-contribution opportunity, such as fixing documentation, cleaning up code style, or tackling a simple bug from the bug tracker. This will set you on a direct path to preparing your first patch for submission.