5.5: Sending the patch

Before you mail your patches, there are a couple of other things you should take care of:

 

  • Are you sure that your mailer will not corrupt the patches? Patches which have had gratuitous white-space changes or line wrapping performed by the mail client will not apply at the other end, and often will not be examined in any detail. If there is any doubt at all, mail the patch to yourself and convince yourself that it shows up intact.

Documentation/email-clients.txt has some helpful hints on making specific mail clients work for sending patches.

 

  • Are you sure your patch is free of silly mistakes? You should always run patches through scripts/checkpatch.pl and address the complaints it comes up with. Please bear in mind that checkpatch.pl, while being the embodiment of a fair amount of thought about what kernel patches should look like, is not smarter than you. If fixing a checkpatch.pl complaint would make the code worse, don't do it.

Patches should always be sent as plain text. Please do not send them as attachments; that makes it much harder for reviewers to quote sections of the patch in their replies. Instead, just put the patch directly into your message.

When mailing patches, it is important to send copies to anybody who might be interested in it. Unlike some other projects, the kernel encourages people to err on the side of sending too many copies; don't assume that the relevant people will see your posting on the mailing lists. In particular, copies should go to:

 

  • The maintainer(s) of the affected subsystem(s). As described earlier, the MAINTAINERS file is the first place to look for these people.
  • Other developers who have been working in the same area - especially those who might be working there now. Using git to see who else has modified the files you are working on can be helpful.
  • If you are responding to a bug report or a feature request, copy the original poster as well.
  • Send a copy to the relevant mailing list, or, if nothing else applies, the linux-kernel list.
  • If you are fixing a bug, think about whether the fix should go into the next stable update. If so, stable@kernel.org should get a copy of the patch. Also add a "Cc: stable@kernel.org" to the tags within the patch itself; that will cause the stable team to get a notification when your fix goes into the mainline.

When selecting recipients for a patch, it is good to have an idea of who you think will eventually accept the patch and get it merged. While it is possible to send patches directly to Linus Torvalds and have him merge them, things are not normally done that way. Linus is busy, and there are subsystem maintainers who watch over specific parts of the kernel. Usually you will be wanting that maintainer to merge your patches. If there is no obvious maintainer, Andrew Morton is often the patch target of last resort.

Patches need good subject lines. The canonical format for a patch line is something like:

 

[PATCH nn/mm] subsys: one-line description of the patch

where "nn" is the ordinal number of the patch, "mm" is the total number of patches in the series, and "subsys" is the name of the affected subsystem. Clearly, nn/mm can be omitted for a single, standalone patch.

If you have a significant series of patches, it is customary to send an introductory description as part zero. This convention is not universally followed though; if you use it, remember that information in the introduction does not make it into the kernel changelogs. So please ensure that the patches, themselves, have complete changelog information.

In general, the second and following parts of a multi-part patch should be sent as a reply to the first part so that they all thread together at the receiving end. Tools like git and quilt have commands to mail out a set of patches with the proper threading. If you have a long series, though, and are using git, please provide the --no-chain-reply-to option to avoid creating exceptionally deep nesting.