.. _development_posting: Posting patches=============== Sooner or later, the time comes when your work is ready to be presented tothe community for review and, eventually, inclusion into the mainlinekernel.  Unsurprisingly, the kernel development community has evolved a setof conventions and procedures which are used in the posting of patches;following them will make life much easier for everybody involved.  Thisdocument will attempt to cover these expectations in reasonable detail;more information can also be found in the files:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.  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.  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's   debugging tools, ensure that the kernel will build with all reasonable   combinations of configuration options, use cross-compilers to build for   different architectures, etc. Add tests, likely using an existing   testing framework like KUnit, and include them as a separate member   of your series (see the next section for more about patch series).   Note that this may be mandatory when affecting some subsystems. For   example, library functions (resides under lib/) are extensively used   almost everywhere and expected to be tested appropriately.  - Make sure your code is compliant with the kernel coding style   guidelines.  - Does your change have performance implications?  If so, you should run   benchmarks showing what the impact (or benefit) of your change is; a   summary of the results should be included with the patch.  - Be sure that you have the right to post the code.  If this work was done   for an employer, the employer likely has a right to the work and must be   agreeable 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.  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 of   changes found in your working revision control system.  Instead, the   changes you have made need to be considered in their final form, then   split apart in ways which make sense.  The developers are interested in   discrete, self-contained changes, not the path you took to get to those   changes.  - Each logically independent change should be formatted as a separate   patch.  These changes can be small ("add a field to this structure") or   large (adding a significant new driver, for example), but they should be   conceptually small and amenable to a one-line description.  Each patch   should make a specific change which can be reviewed on its own and   verified to do what it says it does.  - As a way of restating the guideline above: do not mix different types of   changes in the same patch.  If a single patch fixes a critical security   bug, rearranges a few structures, and reformats the code, there is a   good chance that it will be passed over and the important fix will be   lost.  - Each patch should yield a kernel which builds and runs properly; if your   patch series is interrupted in the middle, the result should still be a   working kernel.  Partial application of a patch series is a common   scenario when the "git bisect" tool is used to find regressions; if the   result is a broken kernel, you will make life harder for developers and   users who are engaging in the noble work of tracking down problems.  - Do not overdo it, though.  One developer once posted a set of edits   to a single file as 500 separate patches - an act which did not make him   the most popular person on the kernel mailing list.  A single patch can   be reasonably large as long as it still contains a single *logical*   change.  - It can be tempting to add a whole new infrastructure with a series of   patches, but to leave that infrastructure unused until the final patch   in the series enables the whole thing.  This temptation should be   avoided if possible; if that series adds regressions, bisection will   finger the last patch as the one which caused the problem, even though   the real bug is elsewhere.  Whenever possible, a patch which adds new   code 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.  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 is   only 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 be   enough for a reader who sees it with no other context to figure out the   scope of the patch; it is the line that will show up in the "short form"   changelogs.  This message is usually formatted with the relevant   subsystem name first, followed by the purpose of the patch.  For   example:    :: 	gpio: fix build on CONFIG_GPIO_SYSFS=n  - A blank line followed by a detailed description of the contents of the   patch.  This description can be as long as is required; it should say   what 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 from   the 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 the   resulting 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 the:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`document; 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 has   the right to submit the patch for inclusion into the kernel.  It is an   agreement to the Developer's Certificate of Origin, the full text of   which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`   Code 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 author   attributed 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: of   the associated co-author.  Details and examples can be found in   :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.  - Acked-by: indicates an agreement by another developer (often a   maintainer of the relevant code) that the patch is appropriate for   inclusion into the kernel.  - Tested-by: states that the named person has tested the patch and found   it to work.  - Reviewed-by: the named developer has reviewed the patch for correctness;   see the reviewer's statement in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`   for more detail.  - Reported-by: names a user who reported a problem which is fixed by this   patch; this tag is used to give credit to the (often underappreciated)   people who test our code and let us know when things do not work   correctly. Note, this tag should be followed by a Closes: tag pointing to   the report, unless the report is not available on the web. The Link: tag   can 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 person   named 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 the   opportunity 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.  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?  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.    :ref:`Documentation/process/email-clients.rst <email_clients>` 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 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 - 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@vger.kernel.org should get a copy of   the patch.  Also add a "Cc: stable@vger.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 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.