Week 11 — Git Workflow and Sending Patches¶

Goal¶

Learn the kernel's patch-based workflow: how to create, format, and send patches via email. Master the tools: git format-patch, git send-email, b4, and lei. Understand netdev-specific conventions.

Why This Matters¶

The Linux kernel does not use GitHub pull requests. All changes are submitted as email patches to mailing lists. The netdev list receives hundreds of patches daily. If your patch is formatted wrong, has a bad commit message, or is sent to the wrong people, it will be ignored — not out of malice, but because maintainers are overwhelmed.

Configure Git for Kernel Development¶

git config --global user.name "Your Full Name"
git config --global user.email "your@email.com"
git config --global sendemail.smtpserver smtp.your-provider.com
git config --global sendemail.smtpserverport 587
git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpuser your@email.com
git config --global core.editor nvim

If you use Gmail:

git config --global sendemail.smtpserver smtp.gmail.com
git config --global sendemail.smtpserverport 587
git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpuser your@gmail.com
# You'll need an "App Password" — regular password won't work with 2FA

Install git send-email:

sudo apt install -y git-email

The Commit Message¶

This is the most important part of your patch. Reviewers read the message before the code.

net: tcp: fix incorrect window calculation in SYN-RECV state

The receive window calculation in tcp_select_window() does not account
for the case where the initial window scale has not yet been confirmed
during the SYN-RECV state. This causes the advertised window to be
incorrectly scaled, leading to reduced throughput on high-BDP links.

Fix this by checking the socket state before applying the window scale
factor, falling back to the unscaled value during SYN-RECV.

Fixes: a1b2c3d4e5f6 ("net: tcp: rework window scaling logic")
Reported-by: Someone Who Found It <someone@example.com>
Signed-off-by: Your Name <your@email.com>

Commit Message Rules¶

Subject line:

Format: subsystem: area: short description
For networking: net: tcp:, net: ipv4:, net/mlx5:, virtio_net:, etc.
Lowercase after the prefix
No period at the end
Under ~75 characters
Imperative mood: "fix" not "fixed" or "fixes"

Body:

Explain the problem first (what's wrong)
Then explain the fix (what you did)
Wrap at 75 characters
Be specific — include observable symptoms

Trailers (at the bottom):

Signed-off-by: — required. Certifies you have the right to submit (DCO)
Fixes: — if fixing a bug, reference the commit that introduced it
Reported-by: — credit the person who found the bug
Tested-by: — someone who tested your patch
Reviewed-by: — someone who reviewed it
Cc: — additional people who should see this

Find the Fixes tag:

# Find which commit introduced the bug
git log --oneline net/ipv4/tcp_input.c | head -20
git blame net/ipv4/tcp_input.c -L 100,120

# Format it correctly (12-char abbreviated hash)
git log -1 --format='Fixes: %h ("%s")' <commit-hash>

Creating Patches with git format-patch¶

# Make your change
nvim net/ipv4/tcp.c
git add net/ipv4/tcp.c
git commit -s   # -s adds Signed-off-by automatically

# Generate a patch file
git format-patch -1    # Last 1 commit
# Creates: 0001-net-tcp-fix-something.patch

# For a series of N patches
git format-patch -N --cover-letter
# Creates: 0000-cover-letter.patch, 0001-..., 0002-..., etc.

Always check your patch:

./scripts/checkpatch.pl 0001-net-tcp-fix-something.patch

Finding the Right Recipients¶

The kernel has a script that tells you exactly who to send your patch to:

./scripts/get_maintainer.pl 0001-net-tcp-fix-something.patch

Output:

David S. Miller <davem@davemloft.net> (maintainer:NETWORKING)
Eric Dumazet <edumazet@google.com> (maintainer:NETWORKING)
Jakub Kicinski <kuba@kernel.org> (maintainer:NETWORKING)
Paolo Abeni <pabeni@redhat.com> (maintainer:NETWORKING)
netdev@vger.kernel.org (open list:NETWORKING)
linux-kernel@vger.kernel.org (open list)

Always include the output of get_maintainer.pl. Don't guess.

Sending Patches with git send-email¶

# Send a single patch
git send-email \
  --to="netdev@vger.kernel.org" \
  --cc="davem@davemloft.net" \
  --cc="kuba@kernel.org" \
  --cc="pabeni@redhat.com" \
  0001-net-tcp-fix-something.patch

# Send a series with cover letter
git send-email \
  --to="netdev@vger.kernel.org" \
  --cc="..." \
  0000-cover-letter.patch \
  0001-first-change.patch \
  0002-second-change.patch

Dry run first:

git send-email --dry-run 0001-net-tcp-fix-something.patch

Send to yourself first to verify formatting:

git send-email --to="your@email.com" 0001-net-tcp-fix-something.patch

Check the email in your inbox. Is it plain text? Are the headers correct? Does the diff look right?

b4 — Modern Patch Workflow Tool¶

b4 is a tool by Konstantin Ryabitsev (kernel.org admin) that simplifies working with patches on the mailing list.

# Install
pip install --user b4

# Or on Debian
sudo apt install -y b4

Using b4 to Send Patches¶

b4 can prepare and send your patches:

# Prepare a series for sending (creates a cover letter template)
b4 prep --fork-point HEAD~3

# Edit the cover letter
b4 prep --edit-cover

# Send
b4 send

Using b4 to Fetch Patches¶

When reviewing or testing someone else's patches:

# Apply a patch series from a message ID
b4 shazam <message-id>

# Or from a URL
b4 am https://lore.kernel.org/netdev/some-message-id/

Using b4 to Track Your Patch¶

# Check the status of your submitted patch
b4 trailers -u <message-id>

lei — Fetch from Mailing List Archives¶

lei (part of public-inbox) lets you query mailing list archives like a database:

# Install
sudo apt install -y lei

# Add the netdev archive
lei add-external https://lore.kernel.org/netdev/

# Search for recent TCP patches
lei q -t 'subject:net tcp fix' --after=2025-01-01

# Get patches from a specific author
lei q 'from:edumazet@google.com' --after=2025-04-01

netdev-Specific Conventions¶

The networking subsystem has additional rules beyond the general kernel workflow:

Tree Targeting¶

Specify which tree your patch targets in the subject:

[PATCH net] — bug fix for the current release (goes to the net tree)
[PATCH net-next] — new feature for the next merge window (goes to net-next)

git format-patch -1 --subject-prefix="PATCH net-next"

When to use which:

net: fixes for bugs in code already in Linus's tree
net-next: new features, cleanups, improvements

When the merge window is open, net-next is closed. Check the netdev wiki for the current status.

Patch Versions¶

If your patch gets feedback and you need to send a new version:

git format-patch -1 --subject-prefix="PATCH net-next v2"

Include a changelog below the --- line (after your Signed-off-by, below the scissors):

---
v2:
  - Fixed checkpatch warning about line length
  - Added missing NULL check per Eric's review
v1:
  - Initial submission
---

Patchwork¶

Patches sent to netdev are tracked on Patchwork:

https://patchwork.kernel.org/project/netdevbpf/list/

Check here to see if your patch was received and its status (New, Under Review, Accepted, Rejected, etc.).

The Review Process¶

After sending:

Your patch appears on the mailing list and Patchwork
Automated bots run tests (netdev CI) and report results
Reviewers comment on the mailing list
You may need to send v2, v3, etc. based on feedback
A maintainer applies it to the appropriate tree
It flows to Linus's tree during the merge window

Response time: Be patient. Maintainers handle hundreds of patches. A week with no response is normal. Two weeks — send a polite ping.

Exercises¶

Configure git send-email with your email provider. Send a test patch to yourself.
Make a trivial change to a comment in net/ipv4/tcp.c. Create a properly formatted patch with git format-patch. Run checkpatch.pl on it.
Run get_maintainer.pl on your patch. Note all the recipients.
Install b4. Use b4 am to apply a recent patch from the netdev list to your tree.
Use lei to search for patches related to a networking topic you're interested in. Read a few patch discussions to understand the review culture.
Browse https://patchwork.kernel.org/project/netdevbpf/list/ and find a recently accepted patch. Read the commit message and the code change.

What's Next¶

The final week: finding your first contribution. Bug fixes, cleanups, TODO items, and strategies for becoming a recognized contributor.