Documentation/process/5.Posting.rst

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