5.1.When to post¶

There is a constant temptation to avoid posting patches before they arecompletely “ready.” For simple patches, that is not a problem. If thework being done is complex, though, there is a lot to be gained by gettingfeedback from the community before the work is complete. So you shouldconsider posting in-progress work, or even making a git tree available sothat interested developers can catch up with your work at any time.

When posting code which is not yet considered ready for inclusion, it is agood idea to say so in the posting itself. Also mention any major workwhich remains to be done and any known problems. Fewer people will look atpatches which are known to be half-baked, but those who do will come inwith the idea that they can help you drive the work in the right direction.

5.2.Before creating patches¶

There are a number of things which should be done before you considersending patches to the development community. These include:

• Test the code to the extent that you can. Make use of the kernel’sdebugging tools, ensure that the kernel will build with all reasonablecombinations of configuration options, use cross-compilers to build fordifferent architectures, etc.

• Make sure your code is compliant with the kernel coding styleguidelines.

• Does your change have performance implications? If so, you should runbenchmarks showing what the impact (or benefit) of your change is; asummary of the results should be included with the patch.

• Be sure that you have the right to post the code. If this work was donefor an employer, the employer likely has a right to the work and must beagreeable with its release under the GPL.

As a general rule, putting in some extra thought before posting code almostalways pays back the effort in short order.

5.3.Patch preparation¶

The preparation of patches for posting can be a surprising amount of work,but, once again, attempting to save time here is not generally advisableeven in the short term.

Patches must be prepared against a specific version of the kernel. As ageneral rule, a patch should be based on the current mainline as found inLinus’s git tree. When basing on mainline, start with a well-known releasepoint - a stable or -rc release - rather than branching off the mainline atan arbitrary spot.

It may become necessary to make versions against -mm, linux-next, or asubsystem tree, though, to facilitate wider testing and review. Dependingon the area of your patch and what is going on elsewhere, basing a patchagainst these other trees can require a significant amount of workresolving conflicts and dealing with API changes.

Only the most simple changes should be formatted as a single patch;everything else should be made as a logical series of changes. Splittingup patches is a bit of an art; some developers spend a long time figuringout how to do it in the way that the community expects. There are a fewrules of thumb, however, which can help considerably:

• The patch series you post will almost certainly not be the series ofchanges found in your working revision control system. Instead, thechanges you have made need to be considered in their final form, thensplit apart in ways which make sense. The developers are interested indiscrete, self-contained changes, not the path you took to get to thosechanges.

• Each logically independent change should be formatted as a separatepatch. These changes can be small (“add a field to this structure”) orlarge (adding a significant new driver, for example), but they should beconceptually small and amenable to a one-line description. Each patchshould make a specific change which can be reviewed on its own andverified to do what it says it does.

• As a way of restating the guideline above: do not mix different types ofchanges in the same patch. If a single patch fixes a critical securitybug, rearranges a few structures, and reformats the code, there is agood chance that it will be passed over and the important fix will belost.

• Each patch should yield a kernel which builds and runs properly; if yourpatch series is interrupted in the middle, the result should still be aworking kernel. Partial application of a patch series is a commonscenario when the “git bisect” tool is used to find regressions; if theresult is a broken kernel, you will make life harder for developers andusers who are engaging in the noble work of tracking down problems.

• Do not overdo it, though. One developer once posted a set of editsto a single file as 500 separate patches - an act which did not make himthe most popular person on the kernel mailing list. A single patch canbe reasonably large as long as it still contains a singlelogicalchange.

• It can be tempting to add a whole new infrastructure with a series ofpatches, but to leave that infrastructure unused until the final patchin the series enables the whole thing. This temptation should beavoided if possible; if that series adds regressions, bisection willfinger the last patch as the one which caused the problem, even thoughthe real bug is elsewhere. Whenever possible, a patch which adds newcode should make that code active immediately.

Working to create the perfect patch series can be a frustrating processwhich takes quite a bit of time and thought after the “real work” has beendone. When done properly, though, it is time well spent.

5.4.Patch formatting and changelogs¶

So now you have a perfect series of patches for posting, but the work isnot done quite yet. Each patch needs to be formatted into a message whichquickly and clearly communicates its purpose to the rest of the world. Tothat end, each patch will be composed of the following:

• An optional “From” line naming the author of the patch. This line isonly necessary if you are passing on somebody else’s patch via email,but it never hurts to add it when in doubt.

• A one-line description of what the patch does. This message should beenough for a reader who sees it with no other context to figure out thescope of the patch; it is the line that will show up in the “short form”changelogs. This message is usually formatted with the relevantsubsystem name first, followed by the purpose of the patch. Forexample:

  gpio: fix build on CONFIG_GPIO_SYSFS=n

• A blank line followed by a detailed description of the contents of thepatch. This description can be as long as is required; it should saywhat the patch does and why it should be applied to the kernel.

• One or more tag lines, with, at a minimum, one Signed-off-by: line fromthe author of the patch. Tags will be described in more detail below.

The items above, together, form the changelog for the patch. Writing goodchangelogs is a crucial but often-neglected art; it’s worth spendinganother moment discussing this issue. When writing a changelog, you shouldbear in mind that a number of different people will be reading your words.These include subsystem maintainers and reviewers who need to decidewhether the patch should be included, distributors and other maintainerstrying to decide whether a patch should be backported to other kernels, bughunters wondering whether the patch is responsible for a problem they arechasing, users who want to know how the kernel has changed, and more. Agood changelog conveys the needed information to all of these people in themost direct and concise way possible.

To that end, the summary line should describe the effects of and motivationfor the change as well as possible given the one-line constraint. Thedetailed description can then amplify on those topics and provide anyneeded additional information. If the patch fixes a bug, cite the commitwhich introduced the bug if possible (and please provide both the commit IDand the title when citing commits). If a problem is associated withspecific log or compiler output, include that output to help otherssearching for a solution to the same problem. If the change is meant tosupport other changes coming in later patch, say so. If internal APIs arechanged, detail those changes and how other developers should respond. Ingeneral, the more you can put yourself into the shoes of everybody who willbe reading your changelog, the better that changelog (and the kernel as awhole) will be.

Needless to say, the changelog should be the text used when committing thechange to a revision control system. It will be followed by:

• The patch itself, in the unified (“-u”) patch format. Using the “-p”option to diff will associate function names with changes, making theresulting patch easier for others to read.

The tags already briefly mentioned above are used to provide insights howthe patch came into being. They are described in detail in theDocumentation/process/submitting-patches.rstdocument; what follows here is a brief summary.

One tag is used to refer to earlier commits which introduced problems fixed bythe patch:

Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")

Another tag is used for linking web pages with additional backgrounds ordetails, for example an earlier discussion which leads to the patch or adocument with a specification implemented by the patch:

Link: https://example.com/somewhere.html  optional-other-stuff

As per guidance from the Chief Penguin, a Link: tag should only be added toa commit if it leads to useful information that is not found in the commititself.

If the URL points to a public bug report being fixed by the patch, use the“Closes:” tag instead:

Closes: https://example.com/issues/1234  optional-other-stuff

Some bug trackers have the ability to close issues automatically when acommit with such a tag is applied. Some bots monitoring mailing lists canalso track such tags and take certain actions. Private bug trackers andinvalid URLs are forbidden.

Another kind of tag is used to document who was involved in the development ofthe patch. Each of these uses this format:

tag: Full Name <email address>  optional-other-stuff

The tags in common use are:

• Signed-off-by: this is a developer’s certification that he or she hasthe right to submit the patch for inclusion into the kernel. It is anagreement to the Developer’s Certificate of Origin, the full text ofwhich can be found inDocumentation/process/submitting-patches.rstCode without a proper signoff cannot be merged into the mainline.

• Co-developed-by: states that the patch was co-created by several developers;it is a used to give attribution to co-authors (in addition to the authorattributed by the From: tag) when multiple people work on a single patch.Every Co-developed-by: must be immediately followed by a Signed-off-by: ofthe associated co-author. Details and examples can be found inDocumentation/process/submitting-patches.rst.

• Acked-by: indicates an agreement by another developer (often amaintainer of the relevant code) that the patch is appropriate forinclusion into the kernel.

• Tested-by: states that the named person has tested the patch and foundit to work.

• Reviewed-by: the named developer has reviewed the patch for correctness;see the reviewer’s statement inDocumentation/process/submitting-patches.rstfor more detail.

• Reported-by: names a user who reported a problem which is fixed by thispatch; this tag is used to give credit to the (often underappreciated)people who test our code and let us know when things do not workcorrectly. Note, this tag should be followed by a Closes: tag pointing tothe report, unless the report is not available on the web. The Link: tagcan be used instead of Closes: if the patch fixes a part of the issue(s)being reported.

• A Suggested-by: tag indicates that the patch idea is suggested by the personnamed and ensures credit to the person for the idea. This will, hopefully,inspire them to help us again in the future.

• Cc: the named person received a copy of the patch and had theopportunity to comment on it.

Be careful in the addition of the aforementioned tags to your patches, as allexcept for Cc:, Reported-by:, and Suggested-by: need explicit permission of theperson named. For those three implicit permission is sufficient if the personcontributed to the Linux kernel using that name and email address accordingto the lore archives or the commit history -- and in case of Reported-by:and Suggested-by: did the reporting or suggestion in public. Note,bugzilla.kernel.org is a public place in this sense, but email addressesused there are private; so do not expose them in tags, unless the personused them in earlier contributions.

5.5.Sending the patch¶

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

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

  Documentation/process/email-clients.rst has somehelpful hints on making specific mail clients work for sending patches.

• Are you sure your patch is free of silly mistakes? You should alwaysrun patches through scripts/checkpatch.pl and address the complaints itcomes up with. Please bear in mind that checkpatch.pl, while being theembodiment of a fair amount of thought about what kernel patches shouldlook like, is not smarter than you. If fixing a checkpatch.pl complaintwould make the code worse, don’t do it.

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

When mailing patches, it is important to send copies to anybody who mightbe interested in it. Unlike some other projects, the kernel encouragespeople to err on the side of sending too many copies; don’t assume that therelevant 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 - especiallythose who might be working there now. Using git to see who else hasmodified the files you are working on can be helpful.

• If you are responding to a bug report or a feature request, copy theoriginal 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 thenext stable update. If so,stable@vger.kernel.org should get a copy ofthe patch. Also add a “Cc:stable@vger.kernel.org” to the tags withinthe patch itself; that will cause the stable team to get a notificationwhen your fix goes into the mainline.

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

Patches need good subject lines. The canonical format for a patch line issomething 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 ofpatches 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 anintroductory description as part zero. This convention is not universallyfollowed though; if you use it, remember that information in theintroduction does not make it into the kernel changelogs. So please ensurethat the patches, themselves, have complete changelog information.

In general, the second and following parts of a multi-part patch should besent as a reply to the first part so that they all thread together at thereceiving end. Tools like git and quilt have commands to mail out a set ofpatches with the proper threading. If you have a long series, though, andare using git, please stay away from the --chain-reply-to option to avoidcreating exceptionally deep nesting.