Contribution: The Workflow That Actually Blocks People
Foundations taught you to write kernel code. This section is about getting it merged, and it is deliberately short — because the gap between "I can write a driver" and "I have a patch in mainline" is workflow, not knowledge, and workflow can be taught in two weeks.
It is also the section that stops the most people. Not because it is hard, but because none of it is
discoverable. There is no CONTRIBUTING.md with a green button at the end. There is a text file
naming two thousand maintainers, a mailing list you have to find, an email format that most modern
mail clients silently corrupt, and a social protocol nobody wrote down in one place.
This section writes it down.
Learning Objectives
| # | You will be able to |
|---|---|
| 1 | Find the right person, list, and tree for any file in the kernel |
| 2 | Base a patch on the tree a maintainer actually pulls from |
| 3 | Write a commit message that answers the question a maintainer is about to ask |
| 4 | Split a change into a bisectable series where every commit builds and boots |
| 5 | Use the right tags: Fixes:, Cc: stable, Reported-by:, Link:, Reviewed-by: |
| 6 | Send a patch by email that survives the round trip, correctly threaded |
| 7 | Use b4 to fetch, apply, version, and send series |
| 8 | Respond to review — including revising, disagreeing, and handling silence |
| 9 | Review someone else's patch usefully, and know which trailer you have earned |
| 10 | Pass every automated check before a bot mails you about it |
Start Now, Not Later
Do Lab 7 this week, even if you are only halfway through the rest.
The community's latency is measured in weeks. A patch sent today might get a reply in three days or three weeks, land in a maintainer's tree a fortnight later, and appear in a release two months after that. Every one of those clocks runs in parallel with your reading, and none of them start until you press send.
THE MISTAKE THE FIX
─────────── ───────
week 1-18 learn everything week 9 send a trivial patch ← clock starts
week 19 send first patch week 10 review someone else's
week 20+ wait... week 11-17 read subsystems while it soaks
week 18 send the real one
week 20+ both are in flight
See the part of the schedule you do not control.
The Five Chapters
| Chapter | The question it answers |
|---|---|
| Maintainers and Trees | Who do I send this to, and what do I base it on? |
| Patch Craft | What is one patch, what goes in the message, and what makes a series bisectable? |
| Email Workflow | How do I physically send this without corrupting it? |
| Review and Etiquette | What do I do when they reply — or when they do not? |
| Style and Checks | What will be run against my patch, and how do I run it first? |
Read all five before Lab 7. They total less than an hour, and each one prevents a specific, avoidable, public mistake.
The Three Labs
| Lab | Milestone | Deliverable |
|---|---|---|
| Lab 7: Your First Patch | M8 | A real fix, on a real list, with a message-ID on lore |
| Lab 8: A Patch Series | M9 | A cover letter, N bisectable patches, and a v2 |
| Lab 9: Review a Patch | M10 | A public review the author acted on |
Lab 9 is the one people skip and the one that changes how you are seen. Review is the currency of the kernel community: it is scarce, it is what maintainers are drowning in, and someone who gives good review in a subsystem becomes a person whose patches get read first.
The Shape of the Whole Thing
1. FIND WORK a real bug, a real gap, a real doc error
│ ./scripts/get_maintainer.pl -f <file>
▼
2. BASE IT RIGHT git remote add <subsys> <the T: line from MAINTAINERS>
│ git switch -c my-fix <subsys>/for-next
▼
3. WRITE IT one logical change per commit
│ every commit builds and boots
▼
4. CHECK IT checkpatch --strict · sparse · W=1 · allmodconfig
│ the test that proves it works
▼
5. WRITE THE MESSAGE what is wrong · why it matters · what you did · how you know
│ Fixes: / Cc: stable / Link: / Signed-off-by:
▼
6. SEND IT git send-email, or b4 send
│ To: the M: lines. Cc: the L: lines and the R: lines.
▼
7. WAIT days. Sometimes weeks. Do not resend in a panic.
│ Meanwhile: review someone else's patch.
▼
8. RESPOND revise, or defend, or concede — in the thread, inline
│ collect Reviewed-by / Acked-by / Tested-by trailers
▼
9. RESEND v2, In-Reply-To the v1 thread, changelog under the ---
│ git range-diff to prove v2 is what you say it is
▼
10. APPLIED it appears in the maintainer's tree, then linux-next,
then mainline at the next merge window
Every step has a way to get it wrong that costs you a round trip, and a round trip costs a week. That is the entire argument for reading these chapters before sending rather than after.
Common Mistakes, and What They Cost
| Mistake | What happens | Cost |
|---|---|---|
| HTML email | The patch is corrupted; some lists silently drop it | A round trip, and embarrassment |
| Patch as an attachment | Reviewers cannot quote it inline; many will not read it | A round trip |
| Wrong recipients | Nobody who can apply it ever sees it | Silence, forever |
| Based on the wrong tree | "Does not apply." | A round trip |
checkpatch warnings | You look like you did not try | Credibility, which is the scarce thing |
| Several logical changes in one patch | "Please split this." | A round trip |
| A series where commit 3 does not build | Breaks git bisect for everyone, forever | Rejection, or a revert later |
Missing Fixes: on a bug fix | Stable maintainers cannot pick it up | Users keep the bug |
| Top-posting in a reply | Reviewers cannot follow the thread | Ignored |
| Resending after two days of silence | You annoyed a busy person | Goodwill |
| Arguing with a NAK you did not understand | The one move guaranteed to fail | The patch, and more |
| Fixing style in code you did not otherwise touch | Mixed-purpose patch | A round trip |
Every row is avoidable by reading one of the five chapters.
What You Need Working Before Lab 7
[ ] git send-email configured, and PROVEN by sending a patch to yourself
and applying the received mail with `git am`
[ ] b4 installed
[ ] scripts/checkpatch.pl runs and you understand its output
[ ] a subsystem tree added as a git remote, and you can build its for-next branch
[ ] a real name and a working email address in `git config user.name/user.email`
— the DCO requires a real identity, and pseudonymous Signed-off-by is rejected
[ ] you have read Documentation/process/submitting-patches.rst end to end
That last item is not optional and it is not long. It is the specification; this section is the commentary.
$EDITOR ~/kernel/linux/Documentation/process/submitting-patches.rst
$EDITOR ~/kernel/linux/Documentation/process/submit-checklist.rst
$EDITOR ~/kernel/linux/Documentation/process/howto.rst
ls ~/kernel/linux/Documentation/process/maintainer-*.rst # per-subsystem profiles
Contributor Profile: Contribution Graduate
| Dimension | What you can do |
|---|---|
| Targeting | Find the maintainer, the list, and the tree for any file, and base your work correctly |
| Decomposition | Split a change into a series that bisects cleanly |
| Commit messages | Explain why, in the imperative, at the right level of detail |
| Tags | Use Fixes:, Cc: stable, and the -by: trailers correctly and only when earned |
| Mechanics | Send correctly threaded plain-text mail that applies with git am |
| Review response | Revise, defend, or concede — and know which is called for |
| Giving review | Add useful signal to someone else's patch, on-list |
| Self-checking | Run everything the bots run, first |
| What you still cannot do | Judge whether a change is a good idea in a subsystem you do not know. That is Subsystems. |
Next: Maintainers and Trees — who to send it to, and what to base it on. Get this wrong and nothing else matters.