English

Submitting patches: the essential guide to getting your code into the kernel¶

For a person or company who wishes to submit a change to the Linuxkernel, the process can sometimes be daunting if you’re not familiarwith “the system.” This text is a collection of suggestions whichcan greatly increase the chances of your change being accepted.

This document contains a large number of suggestions in a relatively terseformat. For detailed information on how the kernel development processworks, seeA guide to the Kernel Development Process. Also, readLinux Kernel patch submission checklistfor a list of items to check before submitting code.For device tree binding patches, readSubmitting Devicetree (DT) binding patches.

This documentation assumes that you’re usinggit to prepare your patches.If you’re unfamiliar withgit, you would be well-advised to learn how touse it, it will make your life as a kernel developer and in general mucheasier.

Some subsystems and maintainer trees have additional information abouttheir workflow and expectations, seeDocumentation/process/maintainer-handbooks.rst.

Obtain a current source tree¶

If you do not have a repository with the current kernel source handy, usegit to obtain one. You’ll want to start with the mainline repository,which can be grabbed with:

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

Note, however, that you may not want to develop against the mainline treedirectly. Most subsystem maintainers run their own trees and want to seepatches prepared against those trees. See theT: entry for the subsystemin the MAINTAINERS file to find that tree, or simply ask the maintainer ifthe tree is not listed there.

Describe your changes¶

Describe your problem. Whether your patch is a one-line bug fix or5000 lines of a new feature, there must be an underlying problem thatmotivated you to do this work. Convince the reviewer that there is aproblem worth fixing and that it makes sense for them to read past thefirst paragraph.

Describe user-visible impact. Straight up crashes and lockups arepretty convincing, but not all bugs are that blatant. Even if theproblem was spotted during code review, describe the impact you thinkit can have on users. Keep in mind that the majority of Linuxinstallations run kernels from secondary stable trees orvendor/product-specific trees that cherry-pick only specific patchesfrom upstream, so include anything that could help route your changedownstream: provoking circumstances, excerpts from dmesg, crashdescriptions, performance regressions, latency spikes, lockups, etc.

Quantify optimizations and trade-offs. If you claim improvements inperformance, memory consumption, stack footprint, or binary size,include numbers that back them up. But also describe non-obviouscosts. Optimizations usually aren’t free but trade-offs between CPU,memory, and readability; or, when it comes to heuristics, betweendifferent workloads. Describe the expected downsides of youroptimization so that the reviewer can weigh costs against benefits.

Once the problem is established, describe what you are actually doingabout it in technical detail. It’s important to describe the changein plain English for the reviewer to verify that the code is behavingas you intend it to.

The maintainer will thank you if you write your patch description in aform which can be easily pulled into Linux’s source code managementsystem,git, as a “commit log”. SeeThe canonical patch format.

Solve only one problem per patch. If your description starts to getlong, that’s a sign that you probably need to split up your patch.SeeSeparate your changes.

When you submit or resubmit a patch or patch series, include thecomplete patch description and justification for it. Don’t justsay that this is version N of the patch (series). Don’t expect thesubsystem maintainer to refer back to earlier patch versions or referencedURLs to find the patch description and put that into the patch.I.e., the patch (series) and its description should be self-contained.This benefits both the maintainers and reviewers. Some reviewersprobably didn’t even receive earlier versions of the patch.

Describe your changes in imperative mood, e.g. “make xyzzy do frotz”instead of “[This patch] makes xyzzy do frotz” or “[I] changed xyzzyto do frotz”, as if you are giving orders to the codebase to changeits behaviour.

If you want to refer to a specific commit, don’t just refer to theSHA-1 ID of the commit. Please also include the oneline summary ofthe commit, to make it easier for reviewers to know what it is about.Example:

Commit e21d2170f36602ae2708 ("video: remove unnecessaryplatform_set_drvdata()") removed the unnecessaryplatform_set_drvdata(), but left the variable "dev" unused,delete it.

You should also be sure to use at least the first twelve characters of theSHA-1 ID. The kernel repository holds alot of objects, makingcollisions with shorter IDs a real possibility. Bear in mind that, even ifthere is no collision with your six-character ID now, that condition maychange five years from now.

If related discussions or any other background information behind the changecan be found on the web, add ‘Link:’ tags pointing to it. If the patch is aresult of some earlier mailing list discussions or something documented on theweb, point to it.

When linking to mailing list archives, preferably use the lore.kernel.orgmessage archiver service. To create the link URL, use the contents of theMessage-ID header of the message without the surrounding angle brackets.For example:

Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI

Please check the link to make sure that it is actually working and pointsto the relevant message.

However, try to make your explanation understandable without externalresources. In addition to giving a URL to a mailing list archive or bug,summarize the relevant points of the discussion that led to thepatch as submitted.

In case your patch fixes a bug, use the ‘Closes:’ tag with a URL referencingthe report in the mailing list archives or a public bug tracker. For example:

Closes: https://example.com/issues/1234

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.

If your patch fixes a bug in a specific commit, e.g. you found an issue usinggitbisect, please use the ‘Fixes:’ tag with at least the first 12characters of the SHA-1 ID, and the one line summary. Do not split the tagacross multiple lines, tags are exempt from the “wrap at 75 columns” rule inorder to simplify parsing scripts. For example:

Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")

The followinggitconfig settings can be used to add a pretty format foroutputting the above style in thegitlog orgitshow commands:

[core]        abbrev = 12[pretty]        fixes = Fixes: %h (\"%s\")

An example call:

$ git log -1 --pretty=fixes 54a4f0239f2eFixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")

Separate your changes¶

Separate eachlogical change into a separate patch.

For example, if your changes include both bug fixes and performanceenhancements for a single driver, separate those changes into twoor more patches. If your changes include an API update, and a newdriver which uses that new API, separate those into two patches.

On the other hand, if you make a single change to numerous files,group those changes into a single patch. Thus a single logical changeis contained within a single patch.

The point to remember is that each patch should make an easily understoodchange that can be verified by reviewers. Each patch should be justifiableon its own merits.

If one patch depends on another patch in order for a change to becomplete, that is OK. Simply note“this patch depends on patch X”in your patch description.

When dividing your change into a series of patches, take special care toensure that the kernel builds and runs properly after each patch in theseries. Developers usinggitbisect to track down a problem can end upsplitting your patch series at any point; they will not thank you if youintroduce bugs in the middle.

If you cannot condense your patch set into a smaller set of patches,then only post say 15 or so at a time and wait for review and integration.

Style-check your changes¶

Check your patch for basic style violations, details of which can befound inLinux kernel coding style.Failure to do so simply wastesthe reviewers time and will get your patch rejected, probablywithout even being read.

One significant exception is when moving code from one file toanother -- in this case you should not modify the moved code at all inthe same patch which moves it. This clearly delineates the act ofmoving the code and your changes. This greatly aids review of theactual differences and allows tools to better track the history ofthe code itself.

Check your patches with the patch style checker prior to submission(scripts/checkpatch.pl). Note, though, that the style checker should beviewed as a guide, not as a replacement for human judgment. If your codelooks better with a violation then its probably best left alone.

The checker reports at three levels:

ERROR: things that are very likely to be wrong
WARNING: things requiring careful review
CHECK: things requiring thought

You should be able to justify all violations that remain in yourpatch.

Select the recipients for your patch¶

You should always copy the appropriate subsystem maintainer(s) and list(s) onany patch to code that they maintain; look through the MAINTAINERS file and thesource code revision history to see who those maintainers are. The scriptscripts/get_maintainer.pl can be very useful at this step (pass paths to yourpatches as arguments to scripts/get_maintainer.pl). If you cannot find amaintainer for the subsystem you are working on, Andrew Morton(akpm@linux-foundation.org) serves as a maintainer of last resort.

linux-kernel@vger.kernel.org should be used by default for all patches, but thevolume on that list has caused a number of developers to tune it out. Pleasedo not spam unrelated lists and unrelated people, though.

Many kernel-related lists are hosted at kernel.org; you can find a listof them athttps://subspace.kernel.org. There are kernel-related listshosted elsewhere as well, though.

Linus Torvalds is the final arbiter of all changes accepted into theLinux kernel. His e-mail address is <torvalds@linux-foundation.org>.He gets a lot of e-mail, and, at this point, very few patches go throughLinus directly, so typically you should do your best to -avoid-sending him e-mail.

If you have a patch that fixes an exploitable security bug, send that patchtosecurity@kernel.org. For severe bugs, a short embargo may be consideredto allow distributors to get the patch out to users; in such cases,obviously, the patch should not be sent to any public lists. See alsoSecurity bugs.

Patches that fix a severe bug in a released kernel should be directedtoward the stable maintainers by putting a line like this:

Cc: stable@vger.kernel.org

into the sign-off area of your patch (note, NOT an email recipient). Youshould also readEverything you ever wanted to know about Linux -stable releasesin addition to this document.

If changes affect userland-kernel interfaces, please send the MAN-PAGESmaintainer (as listed in the MAINTAINERS file) a man-pages patch, or atleast a notification of the change, so that some information makes its wayinto the manual pages. User-space API changes should also be copied tolinux-api@vger.kernel.org.

No MIME, no links, no compression, no attachments. Just plain text¶

Linus and other kernel developers need to be able to read and commenton the changes you are submitting. It is important for a kerneldeveloper to be able to “quote” your changes, using standard e-mailtools, so that they may comment on specific portions of your code.

For this reason, all patches should be submitted by e-mail “inline”. Theeasiest way to do this is withgitsend-email, which is stronglyrecommended. An interactive tutorial forgitsend-email is available athttps://git-send-email.io.

If you choose not to usegitsend-email:

Warning

Be wary of your editor’s word-wrap corrupting your patch,if you choose to cut-n-paste your patch.

Do not attach the patch as a MIME attachment, compressed or not.Many popular e-mail applications will not always transmit a MIMEattachment as plain text, making it impossible to comment on yourcode. A MIME attachment also takes Linus a bit more time to process,decreasing the likelihood of your MIME-attached change being accepted.

Exception: If your mailer is mangling patches then someone may askyou to re-send them using MIME.

SeeEmail clients info for Linux for hints about configuringyour e-mail client so that it sends your patches untouched.

Respond to review comments¶

Your patch will almost certainly get comments from reviewers on ways inwhich the patch can be improved, in the form of a reply to your email. You mustrespond to those comments; ignoring reviewers is a good way to get ignored inreturn. You can simply reply to their emails to answer their comments. Reviewcomments or questions that do not lead to a code change should almost certainlybring about a comment or changelog entry so that the next reviewer betterunderstands what is going on.

Be sure to tell the reviewers what changes you are making and to thank themfor their time. Code review is a tiring and time-consuming process, andreviewers sometimes get grumpy. Even in that case, though, respondpolitely and address the problems they have pointed out. When sending a nextversion, add apatchchangelog to the cover letter or to individual patchesexplaining difference against previous submission (seeThe canonical patch format).Notify people that commented on your patch about new versions by adding them tothe patches CC list.

SeeEmail clients info for Linux for recommendations on emailclients and mailing list etiquette.

Use trimmed interleaved replies in email discussions¶

Top-posting is strongly discouraged in Linux kernel developmentdiscussions. Interleaved (or “inline”) replies make conversations mucheasier to follow. For more details see:https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

As is frequently quoted on the mailing list:

A: http://en.wikipedia.org/wiki/Top_postQ: Where do I find info about this thing called top-posting?A: Because it messes up the order in which people normally read text.Q: Why is top-posting such a bad thing?A: Top-posting.Q: What is the most annoying thing in e-mail?

Similarly, please trim all unneeded quotations that aren’t relevantto your reply. This makes responses easier to find, and saves time andspace. For more details see:http://daringfireball.net/2007/07/on_top

A: No.Q: Should I include quotations after my reply?

Don’t get discouraged - or impatient¶

After you have submitted your change, be patient and wait. Reviewers arebusy people and may not get to your patch right away.

Once upon a time, patches used to disappear into the void without comment,but the development process works more smoothly than that now. You shouldreceive comments within a few weeks (typically 2-3); if that does nothappen, make sure that you have sent your patches to the right place.Wait for a minimum of one week before resubmitting or pinging reviewers- possibly longer during busy times like merge windows.

It’s also ok to resend the patch or the patch series after a couple ofweeks with the word “RESEND” added to the subject line:

[PATCH Vx RESEND] sub/sys: Condensed patch summary

Don’t add “RESEND” when you are submitting a modified version of yourpatch or patch series - “RESEND” only applies to resubmission of apatch or patch series which have not been modified in any way from theprevious submission.

Include PATCH in the subject¶

Due to high e-mail traffic to Linus, and to linux-kernel, it is commonconvention to prefix your subject line with [PATCH]. This lets Linusand other kernel developers more easily distinguish patches from othere-mail discussions.

gitsend-email will do this for you automatically.

Sign your work - the Developer’s Certificate of Origin¶

To improve tracking of who did what, especially with patches that canpercolate to their final resting place in the kernel through severallayers of maintainers, we’ve introduced a “sign-off” procedure onpatches that are being emailed around.

The sign-off is a simple line at the end of the explanation for thepatch, which certifies that you wrote it or otherwise have the right topass it on as an open-source patch. The rules are pretty simple: if youcan certify the below:

Developer’s Certificate of Origin 1.1¶

By making a contribution to this project, I certify that:

The contribution was created in whole or in part by me and Ihave the right to submit it under the open source licenseindicated in the file; or
The contribution is based upon previous work that, to the bestof my knowledge, is covered under an appropriate open sourcelicense and I have the right under that license to submit thatwork with modifications, whether created in whole or in partby me, under the same open source license (unless I ampermitted to submit under a different license), as indicatedin the file; or
The contribution was provided directly to me by some otherperson who certified (a), (b) or (c) and I have not modifiedit.
I understand and agree that this project and the contributionare public and that a record of the contribution (including allpersonal information I submit with it, including my sign-off) ismaintained indefinitely and may be redistributed consistent withthis project or the open source license(s) involved.

then you just add a line saying:

Signed-off-by: Random J Developer <random@developer.example.org>

using a known identity (sorry, no anonymous contributions.)This will be done for you automatically if you usegitcommit-s.Reverts should also include “Signed-off-by”.gitrevert-s does thatfor you.

Some people also put extra tags at the end. They’ll just be ignored fornow, but you can do this to mark internal company procedures or justpoint out some special detail about the sign-off.

Any further SoBs (Signed-off-by:’s) following the author’s SoB are frompeople handling and transporting the patch, but were not involved in itsdevelopment. SoB chains should reflect thereal route a patch tookas it was propagated to the maintainers and ultimately to Linus, withthe first SoB entry signalling primary authorship of a single author.

When to use Acked-by:, Cc:, and Co-developed-by:¶

The Signed-off-by: tag indicates that the signer was involved in thedevelopment of the patch, or that he/she was in the patch’s delivery path.

If a person was not directly involved in the preparation or handling of apatch but wishes to signify and record their approval of it then they canask to have an Acked-by: line added to the patch’s changelog.

Acked-by: is meant to be used by those responsible for or involved with theaffected code in one way or another. Most commonly, the maintainer when thatmaintainer neither contributed to nor forwarded the patch.

Acked-by: may also be used by other stakeholders, such as people with domainknowledge (e.g. the original author of the code being modified), userspace-sidereviewers for a kernel uAPI patch or key users of a feature. Optionally, inthese cases, it can be useful to add a “# Suffix” to clarify its meaning:

Acked-by: The Stakeholder <stakeholder@example.org> # As primary user

Acked-by: is not as formal as Signed-off-by:. It is a record that the ackerhas at least reviewed the patch and has indicated acceptance. Hence patchmergers will sometimes manually convert an acker’s “yep, looks good to me”into an Acked-by: (but note that it is usually better to ask for anexplicit ack).

Acked-by: is also less formal than Reviewed-by:. For instance, maintainers mayuse it to signify that they are OK with a patch landing, but they may not havereviewed it as thoroughly as if a Reviewed-by: was provided. Similarly, a keyuser may not have carried out a technical review of the patch, yet they may besatisfied with the general approach, the feature or the user-facing interface.

Acked-by: does not necessarily indicate acknowledgement of the entire patch.For example, if a patch affects multiple subsystems and has an Acked-by: fromone subsystem maintainer then this usually indicates acknowledgement of justthe part which affects that maintainer’s code. Judgement should be used here.When in doubt people should refer to the original discussion in the mailinglist archives. A “# Suffix” may also be used in this case to clarify.

If a person has had the opportunity to comment on a patch, but has notprovided such comments, you may optionally add aCc: tag to the patch.This tag documents that potentially interested parties have been included inthe discussion. Note, this is one of only three tags you might be able to usewithout explicit permission of the person named (see ‘Tagging people requirespermission’ below for details).

Co-developed-by: states that the patch was co-created by multiple developers;it is used to give attribution to co-authors (in addition to the authorattributed by the From: tag) when several people work on a single patch. SinceCo-developed-by: denotes authorship, every Co-developed-by: must be immediatelyfollowed by a Signed-off-by: of the associated co-author. Standard sign-offprocedure applies, i.e. the ordering of Signed-off-by: tags should reflect thechronological history of the patch insofar as possible, regardless of whetherthe author is attributed via From: or Co-developed-by:. Notably, the lastSigned-off-by: must always be that of the developer submitting the patch.

Note, the From: tag is optional when the From: author is also the person (andemail) listed in the From: line of the email header.

Example of a patch submitted by the From: author:

<changelog>Co-developed-by: First Co-Author <first@coauthor.example.org>Signed-off-by: First Co-Author <first@coauthor.example.org>Co-developed-by: Second Co-Author <second@coauthor.example.org>Signed-off-by: Second Co-Author <second@coauthor.example.org>Signed-off-by: From Author <from@author.example.org>

Example of a patch submitted by a Co-developed-by: author:

From: From Author <from@author.example.org><changelog>Co-developed-by: Random Co-Author <random@coauthor.example.org>Signed-off-by: Random Co-Author <random@coauthor.example.org>Signed-off-by: From Author <from@author.example.org>Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>

Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:¶

The Reported-by tag gives credit to people who find bugs and report them and ithopefully inspires them to help us again in the future. The tag is intended forbugs; please do not use it to credit feature requests. The tag should befollowed by a Closes: tag pointing to the report, unless the report is notavailable on the web. The Link: tag can be used instead of Closes: if the patchfixes a part of the issue(s) being reported. Note, the Reported-by tag is oneof only three tags you might be able to use without explicit permission of theperson named (see ‘Tagging people requires permission’ below for details).

A Tested-by: tag indicates that the patch has been successfully tested (insome environment) by the person named. This tag informs maintainers thatsome testing has been performed, provides a means to locate testers forfuture patches, and ensures credit for the testers.

Reviewed-by:, instead, indicates that the patch has been reviewed and foundacceptable according to the Reviewer’s Statement:

Reviewer’s statement of oversight¶

By offering my Reviewed-by: tag, I state that:

I have carried out a technical review of this patch toevaluate its appropriateness and readiness for inclusion intothe mainline kernel.
Any problems, concerns, or questions relating to the patchhave been communicated back to the submitter. I am satisfiedwith the submitter’s response to my comments.
While there may be things that could be improved with thissubmission, I believe that it is, at this time, (1) aworthwhile modification to the kernel, and (2) free of knownissues which would argue against its inclusion.
While I have reviewed the patch and believe it to be sound, Ido not (unless explicitly stated elsewhere) make anywarranties or guarantees that it will achieve its statedpurpose or function properly in any given situation.

A Reviewed-by tag is a statement of opinion that the patch is anappropriate modification of the kernel without any remaining serioustechnical issues. Any interested reviewer (who has done the work) canoffer a Reviewed-by tag for a patch. This tag serves to give credit toreviewers and to inform maintainers of the degree of review which has beendone on the patch. Reviewed-by: tags, when supplied by reviewers known tounderstand the subject area and to perform thorough reviews, will normallyincrease the likelihood of your patch getting into the kernel.

Both Tested-by and Reviewed-by tags, once received on mailing list from testeror reviewer, should be added by author to the applicable patches when sendingnext versions. However if the patch has changed substantially in followingversion, these tags might not be applicable anymore and thus should be removed.Usually removal of someone’s Tested-by or Reviewed-by tags should be mentionedin the patch changelog (after the ‘---’ separator).

A Suggested-by: tag indicates that the patch idea is suggested by the personnamed and ensures credit to the person for the idea: if we diligently creditour idea reporters, they will, hopefully, be inspired to help us again in thefuture. Note, this is one of only three tags you might be able to use withoutexplicit permission of the person named (see ‘Tagging people requirespermission’ below for details).

A Fixes: tag indicates that the patch fixes a bug in a previous commit. Itis used to make it easy to determine where an issue originated, which can helpreview a bug fix. This tag also assists the stable kernel team in determiningwhich stable kernel versions should receive your fix. This is the preferredmethod for indicating a bug fixed by the patch. SeeDescribe your changesfor more details.

Note: Attaching a Fixes: tag does not subvert the stable kernel rulesprocess nor the requirement to Cc:stable@vger.kernel.org on all stablepatch candidates. For more information, please readEverything you ever wanted to know about Linux -stable releases.

Finally, while providing tags is welcome and typically very appreciated, pleasenote that signers (i.e. submitters and maintainers) may use their discretion inapplying offered tags.

Tagging people requires permission¶

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.

The canonical patch format¶

This section describes how the patch itself should be formatted. Notethat, if you have your patches stored in agit repository, proper patchformatting can be had withgitformat-patch. The tools cannot createthe necessary text, though, so read the instructions below anyway.

Subject Line¶

The canonical patch subject line is:

Subject: [PATCH 001/123] subsystem: summary phrase

The canonical patch message body contains the following:

Afrom line specifying the patch author, followed by an emptyline (only needed if the person sending the patch is not the author).
The body of the explanation, line wrapped at 75 columns, which willbe copied to the permanent changelog to describe this patch.
An empty line.
TheSigned-off-by: lines, described above, which willalso go in the changelog.
A marker line containing simply---.
Any additional comments not suitable for the changelog.
The actual patch (diff output).

The Subject line format makes it very easy to sort the emailsalphabetically by subject line - pretty much any email reader willsupport that - since because the sequence number is zero-padded,the numerical and alphabetic sort is the same.

Thesubsystem in the email’s Subject should identify whicharea or subsystem of the kernel is being patched.

Thesummaryphrase in the email’s Subject should conciselydescribe the patch which that email contains. Thesummaryphrase should not be a filename. Do not use the samesummaryphrase for every patch in a whole patch series (where apatchseries is an ordered sequence of multiple, related patches).

Bear in mind that thesummaryphrase of your email becomes aglobally-unique identifier for that patch. It propagates all the wayinto thegit changelog. Thesummaryphrase may later be used indeveloper discussions which refer to the patch. People will want togoogle for thesummaryphrase to read discussion regarding thatpatch. It will also be the only thing that people may quickly seewhen, two or three months later, they are going through perhapsthousands of patches using tools such asgitk orgitlog--oneline.

For these reasons, thesummary must be no more than 70-75characters, and it must describe both what the patch changes, as wellas why the patch might be necessary. It is challenging to be bothsuccinct and descriptive, but that is what a well-written summaryshould do.

Thesummaryphrase may be prefixed by tags enclosed in squarebrackets: “Subject: [PATCH <tag>...] <summary phrase>”. The tags arenot considered part of the summary phrase, but describe how the patchshould be treated. Common tags might include a version descriptor ifthe multiple versions of the patch have been sent out in response tocomments (i.e., “v1, v2, v3”), or “RFC” to indicate a request forcomments.

If there are four patches in a patch series the individual patches maybe numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developersunderstand the order in which the patches should be applied and thatthey have reviewed or applied all of the patches in the patch series.

Here are some good example Subjects:

Subject: [PATCH 2/5] ext2: improve scalability of bitmap searchingSubject: [PATCH v2 01/27] x86: fix eflags trackingSubject: [PATCH v2] sub/sys: Condensed patch summarySubject: [PATCH v2 M/N] sub/sys: Condensed patch summary

From Line¶

Thefrom line must be the very first line in the message body,and has the form:

From: Patch Author <author@example.com>

Thefrom line specifies who will be credited as the author of thepatch in the permanent changelog. If thefrom line is missing,then theFrom: line from the email header will be used to determinethe patch author in the changelog.

The author may indicate their affiliation or the sponsor of the workby adding the name of an organization to thefrom andSoB lines,e.g.:

From: Patch Author (Company) <author@example.com>

Explanation Body¶

The explanation body will be committed to the permanent sourcechangelog, so should make sense to a competent reader who has long sinceforgotten the immediate details of the discussion that might have led tothis patch. Including symptoms of the failure which the patch addresses(kernel log messages, oops messages, etc.) are especially useful forpeople who might be searching the commit logs looking for the applicablepatch. The text should be written in such detail so that when readweeks, months or even years later, it can give the reader the neededdetails to grasp the reasoning forwhy the patch was created.

If a patch fixes a compile failure, it may not be necessary to include_all_ of the compile failures; just enough that it is likely thatsomeone searching for the patch can find it. As in thesummaryphrase, it is important to be both succinct as well as descriptive.

Backtraces in commit messages¶

Backtraces help document the call chain leading to a problem. However,not all backtraces are helpful. For example, early boot call chains areunique and obvious. Copying the full dmesg output verbatim, however,adds distracting information like timestamps, module lists, register andstack dumps.

Therefore, the most useful backtraces should distill the relevantinformation from the dump, which makes it easier to focus on the realissue. Here is an example of a well-trimmed backtrace:

unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)Call Trace:mba_wrmsrupdate_domainsrdtgroup_mkdir

Commentary¶

The--- marker line serves the essential purpose of marking forpatch handling tools where the changelog message ends.

One good use for the additional comments after the--- marker isfor adiffstat, to show what files have changed, and the number ofinserted and deleted lines per file. Adiffstat is especially usefulon bigger patches. If you are going to include adiffstat after the--- marker, please usediffstat options-p1-w70 so thatfilenames are listed from the top of the kernel source tree and don’tuse too much horizontal space (easily fit in 80 columns, maybe with someindentation). (git generates appropriate diffstats by default.)

Other comments relevant only to the moment or the maintainer, notsuitable for the permanent changelog, should also go here. A goodexample of such comments might bepatchchangelogs which describewhat has changed between the v1 and v2 version of the patch.

Please put this informationafter the--- line which separatesthe changelog from the rest of the patch. The version information isnot part of the changelog which gets committed to the git tree. It isadditional information for the reviewers. If it’s placed above thecommit tags, it needs manual interaction to remove it. If it is belowthe separator line, it gets automatically stripped off when applying thepatch:

<commit message>...Signed-off-by: Author <author@mail>---V2 -> V3: Removed redundant helper functionV1 -> V2: Cleaned up coding style and addressed review commentspath/to/file | 5+++--...

See more details on the proper patch format in the followingreferences.

Explicit In-Reply-To headers¶

It can be helpful to manually add In-Reply-To: headers to a patch(e.g., when usinggitsend-email) to associate the patch withprevious relevant discussion, e.g. to link a bug fix to the email withthe bug report. However, for a multi-patch series, it is generallybest to avoid using In-Reply-To: to link to older versions of theseries. This way multiple versions of the patch don’t become anunmanageable forest of references in email clients. If a link ishelpful, you can use thehttps://lore.kernel.org/ redirector (e.g., inthe cover email text) to link to an earlier version of the patch series.

Providing base tree information¶

When other developers receive your patches and start the review process,it is absolutely necessary for them to know what is the basecommit/branch your work applies on, considering the sheer amount ofmaintainer trees present nowadays. Note again theT: entry in theMAINTAINERS file explained above.

This is even more important for automated CI processes that attempt torun a series of tests in order to establish the quality of yoursubmission before the maintainer starts the review.

If you are usinggitformat-patch to generate your patches, you canautomatically include the base tree information in your submission byusing the--base flag. The easiest and most convenient way to usethis option is with topical branches:

$ git checkout -t -b my-topical-branch masterBranch 'my-topical-branch' set up to track local branch 'master'.Switched to a new branch 'my-topical-branch'[perform your edits and commits]$ git format-patch --base=auto --cover-letter -o outgoing/ masteroutgoing/0000-cover-letter.patchoutgoing/0001-First-Commit.patchoutgoing/...

When you openoutgoing/0000-cover-letter.patch for editing, you willnotice that it will have thebase-commit: trailer at the verybottom, which provides the reviewer and the CI tools enough informationto properly performgitam without worrying about conflicts:

$ git checkout -b patch-review [base-commit-id]Switched to a new branch 'patch-review'$ git am patches.mboxApplying: First CommitApplying: ...

Please seemangit-format-patch for more information about thisoption.

Note

The--base feature was introduced in git version 2.9.0.

If you are not using git to format your patches, you can still includethe samebase-commit trailer to indicate the commit hash of the treeon which your work is based. You should add it either in the coverletter or in the first patch of the series and it should be placedeither below the--- line or at the very bottom of all othercontent, right before your email signature.

Make sure that base commit is in an official maintainer/mainline treeand not in some internal, accessible only to you tree - otherwise itwould be worthless.

Tooling¶

Many of the technical aspects of this process can be automated usingb4, documented at <https://b4.docs.kernel.org/en/latest/>. This canhelp with things like tracking dependencies, running checkpatch andwith formatting and sending mails.