KernelNewbies:

Patch tips and tricks

Patch subject prefixes

You can pass `git format-patch` a --subject-prefix="string" parameter. It sets the Subject line prefix (the text in the square brackets) to the string you specify. By default, it is set to "PATCH", and this will generate email with the Subject line "[PATCH] <git short description>". The git tools will ignore anything in square brackets, so you can put whatever you want in the subject prefix.

For example, if you're sending the second revision of a patch, you should use [PATCH v2]. And yes, some patchsets even get up to [PATCH v8].

Another common Subject prefix is "RFC". This stands for "Request for Comment", which tells maintainers should review your patch thoroughly, and provide feedback. RFC is typically used when sending feature patches for the first time, or anytime the patch is more than just a simple bug fix. Developers will often use [RFC v2] on the second revision of their feature patchset.

Tips for editing patch emails

In general, you should never edit the patch subject line (except the subject prefix in square brackets), and you should never edit the patch body or diff. If you need to do that, go back into git, and amend your commit. It is sloppy to edit patches in mutt, and will trip you up if you ever get to the stage of sending maintainers pull requests.

There are a couple places where it's okay to add extra text. You can edit an inline patch to add notes below the --- line. The git tools to apply the patch will ignore any text after the ---}, up to the start of the diff. This is useful for adding information to the maintainer that you don't necessarily need to include in the patch description. For example, if you're sending a second revision of a patch, you may want to type: 

Signed-off-by: Your Name <my.email@gmail.com>
---

Changes since v2:
 * Made commit message more clear
 * Corrected grammer in code comment
 * Used new API instead of depreciated API

drivers/staging/csr/bh.c

You can also add comments before the patch description by adding scissor lines. This is useful if you want to give comments to the maintainer, but your patch body is longer than one page (yes, this happens in good patch descriptions). Scissor lines look like this: 

Subject: [PATCH] csr: Misc cleanups
Reply-to:

Changes since v2:
 * Made commit message more clear
 * Corrected grammer in code comment
 * Used new API instead of depreciated API

>8------------------------------------------------------8<

Play around with these options if you want. Bonus points if you send your first patch to the opw-kernel mailing list using one of these options.

Submitting a patchset

Sometimes you need to send multiple related patches. This is useful for grouping, say, to group driver clean up patches for one particular driver into a set, or grouping patches that are part of a new feature into one set.

For example, take a look at this patch set:

Typically, the subject prefix for patches in the patchset are [PATCH X/Y] or [RFC X/Y], where Y is the total number of patches, and X is the current patch number. Patchsets often have a "cover letter" that is [PATCH 0/Y] or [RFC 0/Y]. A cover letter is used to explain why the patchset is necessary, and provide an overview of the end result of the patches. Cover letters are also great places to ask for help in reviewing specific patches in the patchset.

In order to create patchsets like this, you will need to use either `git send-email``}} or {{{`git format-patch`. These tools will generate the right "In-Reply-To" Headers, so that in a text mail client, the patches will appear next to each other, rather than having unrelated email in between. Otherwise, patches may get jumbled, depending on when they were received.

Using git format-patch to send patchsets

First, use `git log --pretty=oneline --abbrev-commit` to figure out the first commit ID you want to send. For example, say that my tree had this git log history: 

b7ca36a Docs: Move ref to Frohwalt Egerer to end of REPORTING-BUGS
bf6adaf Docs: Add a tips section to REPORTING-BUGS.
bc6bed4 Docs: Expectations for bug reporters and maintainers
2c97a63 Docs: Add info on supported kernels to REPORTING-BUGS.
7883a25 Docs: Add "Gather info" section to REPORTING-BUGS.
d60418b Docs: Step-by-step directions for reporting bugs.
3b12c21 Trivial: docs: Remove six-space indentation in REPORTING-BUGS.
bb33db7 Merge branches 'timers-urgent-for-linus', 'irq-urgent-for-linus' and 'core-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip
41ef2d5 Linux 3.9-rc7

The first commit I want to send as part of the patchset has commit ID 3b12c21. The last patch I want to send has commit ID b7ca36a. So, I want to pass the commit range 3b12c21..b7ca36a to {{{git format-patch}}}. (Remember, the {{{git format-patch}}} range starting commit must be the commit ''before'' the first commit you want to send, so we use the '' to specify the patch before commit 3b12c21.) The command will look something like this: 

git format-patch -o /tmp/ --cover-letter -n --thread=shallow --cc="linux-usb@vger.kernel.org" 3b12c21^..b7ca36a

Again, the -o flag specifies where to put the email files. The -n flag says to add numbering to each patch (e.g. [PATCH 2/5]). The --thread=shallow flag specifies that all patches will be In-Reply-To your cover letter.

That will output files into /tmp, and you can edit them in mutt in multiple terminal tabs: 

/tmp/0000-cover-letter.patch
/tmp/0001-Trivial-docs-Remove-six-space-indentation-in-REPORTI.patch
/tmp/0002-Docs-Step-by-step-directions-for-reporting-bugs.patch
/tmp/0003-Docs-Add-Gather-info-section-to-REPORTING-BUGS.patch
/tmp/0004-Docs-Add-info-on-supported-kernels-to-REPORTING-BUGS.patch
/tmp/0005-Docs-Expectations-for-bug-reporters-and-maintainers.patch
/tmp/0006-Docs-Add-a-tips-section-to-REPORTING-BUGS.patch
/tmp/0007-Docs-Move-ref-to-Frohwalt-Egerer-to-end-of-REPORTING.patch

KernelNewbies: PatchTipsAndTricks (last edited 2013-05-03 14:31:54 by SarahSharp)