Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deelerdev/linux/llms.txt

Use this file to discover all available pages before exploring further.

A subsystem maintainer is responsible for a specific area of the kernel — a driver, a filesystem, a networking protocol, or a broader subsystem — and for shepherding contributions through review and into the mainline. This guide covers the git workflows and practices that maintainers use day to day, drawn from the Kernel Maintainer Handbook in the kernel source tree.

​
Responsibilities

As a maintainer you are responsible for:
  • Reviewing patches sent to your subsystem’s mailing list and providing timely, technically grounded feedback.
  • Applying accepted patches to your subsystem’s git tree and forwarding them upstream via pull requests.
  • Writing and maintaining a Maintainer Entry Profile that tells contributors what your subsystem expects: which branch to submit against, key merge-window dates, CI requirements, and review cadence.
  • Leading by example in following the Code of Conduct and helping to resolve conduct issues in your area of the community.
You are listed in the MAINTAINERS file in the kernel source tree. Contributors run scripts/get_maintainer.pl to find your address and mailing list. Keep your entry current.

​
Setting up git

Tagged branches used in pull requests must be signed with your GPG key. Configure your signing key so you can use the -s shorthand with git tag: 
git config user.signingkey "your-key-id"
If gpg cannot find a terminal to prompt for your passphrase, add this to your shell’s rc file: 
export GPG_TTY=$(tty)

​
Managing patch queues

Maintainers apply patches from email using git am. The general flow is:
1

Save the raw email

Save the patch email as a raw text file including all headers. Many email clients have a “save as” or “view source” option for this.
2

Apply with git am

git am raw_email.txt
If the patch applies cleanly, it is added to your tree with the author, date, and commit message from the email preserved exactly.
3

Verify the result

git log -1
git show
Check that the author identity, Signed-off-by chain, and commit message are intact.

​
Modifying patches during review

If you need to make a small adjustment to a patch before merging — for example, because the code has diverged slightly in your tree — add a note between the submitter’s last Signed-off-by line and yours to document the change you made: 
Signed-off-by: Random J Developer <random@developer.example.org>
[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
You must never change the From: header of a patch email. That header determines the author shown in the kernel changelog, and altering it falsely attributes the work.
This practice is particularly important when maintaining a stable branch: it lets you credit the original author, track your changes, and protect the submitter from complaints about modifications you made.

​
Backporting patches to stable

When backporting a fix from mainline to an older kernel, insert the origin commit at the top of the commit message (just after the subject line): 
libata: Un-break ATA blacklist

commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
For patches going the other direction — a fix developed on an older branch and forward-ported to mainline: 
wireless, airo: waitbusy() won't delay

[backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
This information is invaluable to anyone tracking your trees or troubleshooting regressions.

​
Creating pull requests

Linus will only accept pull requests based on a signed tag. Other maintainers may vary, but using signed tags is best practice universally.
1

Create a branch and tag it

Collect all the changes you want to pull on a dedicated branch. Then create a signed tag with a meaningful name that includes the subsystem and target kernel version:
git tag -s char-misc-4.15-rc1 char-misc-next
When git opens an editor for the tag message, write a thorough description: what the pull contains, why it should be merged, and what testing has been done. This message appears verbatim in the merge commit and will be in the kernel tree forever.
2

Push the tag to a public location

git push origin char-misc-4.15-rc1
The tag must be publicly accessible before you can generate the pull request message. If it is not present in the remote repo, git request-pull will tell you.
3

Generate the pull request message

git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1
This command compares the tag with the master branch (your last known upstream point) and produces a message containing the pull URL, a shortlog of commits, and a diffstat.
4

Send the pull request by email

Send the output of git request-pull as an inline plain-text email to the upstream maintainer, CC’ing LKML and any relevant subsystem lists. Use a subject line of the form:
[GIT PULL] <subsystem> changes for v4.15-rc1
Linus prefers the git:// protocol in pull request URLs. Use https:// only if the tree has no signed tag, as some developers behind firewalls have trouble with https:// git pulls.

​
What to write in the tag message

Linus is explicit about this: the message matters most. It should explain what is being pulled and why it should be merged, and it should make sense as a historical record in the merge commit. If anything is unusual — touching files outside your subsystem, late-cycle fixes with timing concerns — explain it explicitly. A good example structure: 
Char/Misc patches for 4.15-rc1

Here is the big char/misc patch set for the 4.15-rc1 merge window.
Contained in here is the normal set of new functions added to all
of these drivers, as well as the following brand new subsystems:
    - time_travel_controller: ...
    - relativity_shifters: ...

All of these patches have been successfully tested in the latest
linux-next releases.

Signed-off-by: Your-name-here <your_email@domain>

​
Rebasing and merging

​
Rules for rebasing

The kernel community is not averse to merge commits — given the scale of the project, they are unavoidable. Trouble arises when maintainers rebase incorrectly.
History that has been pushed to a public repository and may have been pulled by others must not be changed. If a branch needs rebasing, that is a signal it is not yet ready to be public. Exceptions exist for trees like linux-next that are explicitly documented as frequently rebased.
If you have pulled another developer’s commits into your tree, you are a custodian of their history. Do not change it. A broken commit in such a tree should be explicitly reverted, not silently removed via history modification.
Moving a branch to a new base just to be on a newer commit or to avoid a merge is not a good reason. When you must reparent, pick a stable, well-known point such as an -rc release — not a random commit between releases.
Reparenting changes the environment in which patches were developed and likely invalidates testing. Treat a reparented patch series as new code and retest from the beginning.

​
Merging from lower-level trees

When a lower-level maintainer sends you a pull request, acting on it will almost always produce a merge commit — that is correct and expected. Use --no-ff in the rare case where a fast-forward would normally occur, so the reason for the merge is recorded. The merge commit changelog should summarize the changes being brought in. All maintainers at all levels should use signed tags on their pull requests, and upstream maintainers should verify tags when pulling: 
git pull --verify-signatures <remote> <tag>

​
Avoiding back merges

Merging mainline or a sibling tree into your subsystem branch — a “back merge” — should be avoided almost all of the time. Back merges muddy your branch’s history, increase the chance of encountering bugs from elsewhere, and can hide problems with your own development process. They also complicate Linus’s work: he handles on the order of 382 merges per development cycle and explicitly prefers to see merge conflicts rather than unnecessary back merges, because conflicts show him where potential problem areas are.
Do not resolve merge conflicts by back-merging the mainline into your branch before sending a pull request. Warn Linus in the pull request message instead, and if the conflict is complex, push a separate branch showing how you would resolve it.
When a back merge is genuinely required, document why in the commit message and merge to a well-known stable point, not a random commit.

​
Merging at the start of a cycle

It is common to merge with mainline near the beginning of a development cycle to pick up fixes. If your upstream-bound branch has been fully merged during the merge window, you can advance it with: 
git merge --ff-only v5.2-rc1

​
Maintainer entry profiles

Each subsystem should have a Maintainer Entry Profile — a document that supplements the top-level submission guides with subsystem-local rules. Contributors use it to calibrate expectations; maintainers can compare profiles across subsystems to converge on common practices. A complete profile covers:
How the subsystem operates: notifications when patches are applied, patchwork or CI infrastructure, which git branches feed into linux-next, and which branch contributors should submit against.
Mandatory and advisory criteria beyond the standard submit-checklist: for example, “pass checkpatch.pl with no errors or warnings” or “pass the unit test at $URI”. Also covers any requirements around hardware specification revisions.
The -rc week by which new feature submissions must arrive to be considered for the next merge window (generally before -rc5), and the deadline after which unreviewed patches must wait for the following cycle.
How long contributors should wait before re-pinging, whether to resend the full series or send a private reminder, and any non-maintainer review channels available for the subsystem.

Build docs developers (and LLMs) love

Get started for freeTalk to us