KernelNewbies:

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 outreachy-kernel mailing list using one of these options.

Dealing with tags

When submitting a patch or patchset, Linux kernel community members will often reply with a "Reviewed-by" tag. That tag means the developer has reviewed the code, and thinks it looks fine. When the maintainer picks that patch for their tree, they will edit it to include that line, so that the reviewer gets credit (and blame, if the patch later has issues). Here's an example

If the maintainer applies the revision of the patch that the mentor added their Reviewed-by tag to, you don't have to do anything more with the tag.

However, sometimes a reviewer says the patch itself looks fine and adds their Reviewed-by tag, but also says you need to do a small fix, like change the subject line. If you need to send another revision of your patch, please make sure to include that Reviewed-by tag in your next patch version. That will ensure that the tags don't get lost and reviewers get proper credit.

Other tags you might see in community patches include "Suggested-by" (for saying someone suggested you make this change), "Reported-by" (to acknowledge people who report bugs), "Tested-by" (to indicate code was tested by a developer), and more.

KernelNewbies: PatchTipsAndTricks (last edited 2017-12-30 01:29:53 by localhost)