^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. _development_posting:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) Posting patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Sooner or later, the time comes when your work is ready to be presented to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) the community for review and, eventually, inclusion into the mainline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) kernel. Unsurprisingly, the kernel development community has evolved a set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) of conventions and procedures which are used in the posting of patches;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) following them will make life much easier for everybody involved. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) document will attempt to cover these expectations in reasonable detail;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) more information can also be found in the files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) When to post
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) There is a constant temptation to avoid posting patches before they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) completely "ready." For simple patches, that is not a problem. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) work being done is complex, though, there is a lot to be gained by getting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) feedback from the community before the work is complete. So you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) consider posting in-progress work, or even making a git tree available so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) that interested developers can catch up with your work at any time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) When posting code which is not yet considered ready for inclusion, it is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) good idea to say so in the posting itself. Also mention any major work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) which remains to be done and any known problems. Fewer people will look at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) patches which are known to be half-baked, but those who do will come in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) with the idea that they can help you drive the work in the right direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Before creating patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) There are a number of things which should be done before you consider
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) sending patches to the development community. These include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) - Test the code to the extent that you can. Make use of the kernel's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) debugging tools, ensure that the kernel will build with all reasonable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) combinations of configuration options, use cross-compilers to build for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) different architectures, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) - Make sure your code is compliant with the kernel coding style
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) guidelines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) - Does your change have performance implications? If so, you should run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) benchmarks showing what the impact (or benefit) of your change is; a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) summary of the results should be included with the patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) - Be sure that you have the right to post the code. If this work was done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) for an employer, the employer likely has a right to the work and must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) agreeable with its release under the GPL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) As a general rule, putting in some extra thought before posting code almost
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) always pays back the effort in short order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Patch preparation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) The preparation of patches for posting can be a surprising amount of work,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) but, once again, attempting to save time here is not generally advisable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) even in the short term.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Patches must be prepared against a specific version of the kernel. As a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) general rule, a patch should be based on the current mainline as found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) Linus's git tree. When basing on mainline, start with a well-known release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) point - a stable or -rc release - rather than branching off the mainline at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) an arbitrary spot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) It may become necessary to make versions against -mm, linux-next, or a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) subsystem tree, though, to facilitate wider testing and review. Depending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) on the area of your patch and what is going on elsewhere, basing a patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) against these other trees can require a significant amount of work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) resolving conflicts and dealing with API changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) Only the most simple changes should be formatted as a single patch;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) everything else should be made as a logical series of changes. Splitting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) up patches is a bit of an art; some developers spend a long time figuring
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) out how to do it in the way that the community expects. There are a few
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) rules of thumb, however, which can help considerably:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) - The patch series you post will almost certainly not be the series of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) changes found in your working revision control system. Instead, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) changes you have made need to be considered in their final form, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) split apart in ways which make sense. The developers are interested in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) discrete, self-contained changes, not the path you took to get to those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) - Each logically independent change should be formatted as a separate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) patch. These changes can be small ("add a field to this structure") or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) large (adding a significant new driver, for example), but they should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) conceptually small and amenable to a one-line description. Each patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) should make a specific change which can be reviewed on its own and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) verified to do what it says it does.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) - As a way of restating the guideline above: do not mix different types of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) changes in the same patch. If a single patch fixes a critical security
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) bug, rearranges a few structures, and reformats the code, there is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) good chance that it will be passed over and the important fix will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) lost.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) - Each patch should yield a kernel which builds and runs properly; if your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) patch series is interrupted in the middle, the result should still be a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) working kernel. Partial application of a patch series is a common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) scenario when the "git bisect" tool is used to find regressions; if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) result is a broken kernel, you will make life harder for developers and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) users who are engaging in the noble work of tracking down problems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) - Do not overdo it, though. One developer once posted a set of edits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) to a single file as 500 separate patches - an act which did not make him
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) the most popular person on the kernel mailing list. A single patch can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) be reasonably large as long as it still contains a single *logical*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) change.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) - It can be tempting to add a whole new infrastructure with a series of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) patches, but to leave that infrastructure unused until the final patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) in the series enables the whole thing. This temptation should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) avoided if possible; if that series adds regressions, bisection will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) finger the last patch as the one which caused the problem, even though
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) the real bug is elsewhere. Whenever possible, a patch which adds new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) code should make that code active immediately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) Working to create the perfect patch series can be a frustrating process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) which takes quite a bit of time and thought after the "real work" has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) done. When done properly, though, it is time well spent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) Patch formatting and changelogs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) So now you have a perfect series of patches for posting, but the work is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) not done quite yet. Each patch needs to be formatted into a message which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) quickly and clearly communicates its purpose to the rest of the world. To
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) that end, each patch will be composed of the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) - An optional "From" line naming the author of the patch. This line is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) only necessary if you are passing on somebody else's patch via email,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) but it never hurts to add it when in doubt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) - A one-line description of what the patch does. This message should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) enough for a reader who sees it with no other context to figure out the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) scope of the patch; it is the line that will show up in the "short form"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) changelogs. This message is usually formatted with the relevant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) subsystem name first, followed by the purpose of the patch. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) gpio: fix build on CONFIG_GPIO_SYSFS=n
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) - A blank line followed by a detailed description of the contents of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) patch. This description can be as long as is required; it should say
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) what the patch does and why it should be applied to the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) - One or more tag lines, with, at a minimum, one Signed-off-by: line from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) the author of the patch. Tags will be described in more detail below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) The items above, together, form the changelog for the patch. Writing good
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) changelogs is a crucial but often-neglected art; it's worth spending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) another moment discussing this issue. When writing a changelog, you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) bear in mind that a number of different people will be reading your words.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) These include subsystem maintainers and reviewers who need to decide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) whether the patch should be included, distributors and other maintainers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) trying to decide whether a patch should be backported to other kernels, bug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) hunters wondering whether the patch is responsible for a problem they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) chasing, users who want to know how the kernel has changed, and more. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) good changelog conveys the needed information to all of these people in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) most direct and concise way possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) To that end, the summary line should describe the effects of and motivation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) for the change as well as possible given the one-line constraint. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) detailed description can then amplify on those topics and provide any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) needed additional information. If the patch fixes a bug, cite the commit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) which introduced the bug if possible (and please provide both the commit ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) and the title when citing commits). If a problem is associated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) specific log or compiler output, include that output to help others
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) searching for a solution to the same problem. If the change is meant to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) support other changes coming in later patch, say so. If internal APIs are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) changed, detail those changes and how other developers should respond. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) general, the more you can put yourself into the shoes of everybody who will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) be reading your changelog, the better that changelog (and the kernel as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) whole) will be.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) Needless to say, the changelog should be the text used when committing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) change to a revision control system. It will be followed by:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) - The patch itself, in the unified ("-u") patch format. Using the "-p"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) option to diff will associate function names with changes, making the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) resulting patch easier for others to read.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) You should avoid including changes to irrelevant files (those generated by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) the build process, for example, or editor backup files) in the patch. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) file "dontdiff" in the Documentation directory can help in this regard;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) pass it to diff with the "-X" option.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) The tags mentioned above are used to describe how various developers have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) been associated with the development of this patch. They are described in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) detail in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) document; what follows here is a brief summary. Each of these lines has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) the format:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) tag: Full Name <email address> optional-other-stuff
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) The tags in common use are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) - Signed-off-by: this is a developer's certification that he or she has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) the right to submit the patch for inclusion into the kernel. It is an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) agreement to the Developer's Certificate of Origin, the full text of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) Code without a proper signoff cannot be merged into the mainline.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) - Co-developed-by: states that the patch was co-created by several developers;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) it is a used to give attribution to co-authors (in addition to the author
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) attributed by the From: tag) when multiple people work on a single patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) Every Co-developed-by: must be immediately followed by a Signed-off-by: of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) the associated co-author. Details and examples can be found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) - Acked-by: indicates an agreement by another developer (often a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) maintainer of the relevant code) that the patch is appropriate for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) inclusion into the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) - Tested-by: states that the named person has tested the patch and found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) it to work.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) - Reviewed-by: the named developer has reviewed the patch for correctness;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) see the reviewer's statement in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) for more detail.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) - Reported-by: names a user who reported a problem which is fixed by this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) patch; this tag is used to give credit to the (often underappreciated)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) people who test our code and let us know when things do not work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) correctly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) - Cc: the named person received a copy of the patch and had the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) opportunity to comment on it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) Be careful in the addition of tags to your patches: only Cc: is appropriate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) for addition without the explicit permission of the person named.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) Sending the patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) Before you mail your patches, there are a couple of other things you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) take care of:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) - Are you sure that your mailer will not corrupt the patches? Patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) which have had gratuitous white-space changes or line wrapping performed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) by the mail client will not apply at the other end, and often will not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) be examined in any detail. If there is any doubt at all, mail the patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) to yourself and convince yourself that it shows up intact.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) :ref:`Documentation/process/email-clients.rst <email_clients>` has some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) helpful hints on making specific mail clients work for sending patches.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) - Are you sure your patch is free of silly mistakes? You should always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) run patches through scripts/checkpatch.pl and address the complaints it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) comes up with. Please bear in mind that checkpatch.pl, while being the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) embodiment of a fair amount of thought about what kernel patches should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) look like, is not smarter than you. If fixing a checkpatch.pl complaint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) would make the code worse, don't do it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) Patches should always be sent as plain text. Please do not send them as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) attachments; that makes it much harder for reviewers to quote sections of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) the patch in their replies. Instead, just put the patch directly into your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) When mailing patches, it is important to send copies to anybody who might
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) be interested in it. Unlike some other projects, the kernel encourages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) people to err on the side of sending too many copies; don't assume that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) relevant people will see your posting on the mailing lists. In particular,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) copies should go to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) - The maintainer(s) of the affected subsystem(s). As described earlier,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) the MAINTAINERS file is the first place to look for these people.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) - Other developers who have been working in the same area - especially
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) those who might be working there now. Using git to see who else has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) modified the files you are working on can be helpful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) - If you are responding to a bug report or a feature request, copy the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) original poster as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) - Send a copy to the relevant mailing list, or, if nothing else applies,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) the linux-kernel list.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) - If you are fixing a bug, think about whether the fix should go into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) next stable update. If so, stable@vger.kernel.org should get a copy of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) the patch. Also add a "Cc: stable@vger.kernel.org" to the tags within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) the patch itself; that will cause the stable team to get a notification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) when your fix goes into the mainline.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) When selecting recipients for a patch, it is good to have an idea of who
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) you think will eventually accept the patch and get it merged. While it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) is possible to send patches directly to Linus Torvalds and have him merge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) them, things are not normally done that way. Linus is busy, and there are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) subsystem maintainers who watch over specific parts of the kernel. Usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) you will be wanting that maintainer to merge your patches. If there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) obvious maintainer, Andrew Morton is often the patch target of last resort.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) Patches need good subject lines. The canonical format for a patch line is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) something like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) [PATCH nn/mm] subsys: one-line description of the patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) where "nn" is the ordinal number of the patch, "mm" is the total number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) patches in the series, and "subsys" is the name of the affected subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) Clearly, nn/mm can be omitted for a single, standalone patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) If you have a significant series of patches, it is customary to send an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) introductory description as part zero. This convention is not universally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) followed though; if you use it, remember that information in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) introduction does not make it into the kernel changelogs. So please ensure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) that the patches, themselves, have complete changelog information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) In general, the second and following parts of a multi-part patch should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) sent as a reply to the first part so that they all thread together at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) receiving end. Tools like git and quilt have commands to mail out a set of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) patches with the proper threading. If you have a long series, though, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) are using git, please stay away from the --chain-reply-to option to avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) creating exceptionally deep nesting.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags