Documentation/process/5.Posting.rst

13 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
14 and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
18 ------------
24 consider posting in-progress work, or even making a git tree available so
30 patches which are known to be half-baked, but those who do will come in
35 -----------------------
40  - Test the code to the extent that you can.  Make use of the kernel's
42    combinations of configuration options, use cross-compilers to build for
45  - Make sure your code is compliant with the kernel coding style
48  - Does your change have performance implications?  If so, you should run
50    summary of the results should be included with the patch.
52  - Be sure that you have the right to post the code.  If this work was done
60 Patch preparation
61 -----------------
68 general rule, a patch should be based on the current mainline as found in
69 Linus's git tree.  When basing on mainline, start with a well-known release
70 point - a stable or -rc release - rather than branching off the mainline at
73 It may become necessary to make versions against -mm, linux-next, or a
75 on the area of your patch and what is going on elsewhere, basing a patch
79 Only the most simple changes should be formatted as a single patch;
85  - The patch series you post will almost certainly not be the series of
89    discrete, self-contained changes, not the path you took to get to those
92  - Each logically independent change should be formatted as a separate
93    patch.  These changes can be small ("add a field to this structure") or
95    conceptually small and amenable to a one-line description.  Each patch
99  - As a way of restating the guideline above: do not mix different types of
100    changes in the same patch.  If a single patch fixes a critical security
105  - Each patch should yield a kernel which builds and runs properly; if your
106    patch series is interrupted in the middle, the result should still be a
107    working kernel.  Partial application of a patch series is a common
112  - Do not overdo it, though.  One developer once posted a set of edits
113    to a single file as 500 separate patches - an act which did not make him
114    the most popular person on the kernel mailing list.  A single patch can
118  - It can be tempting to add a whole new infrastructure with a series of
119    patches, but to leave that infrastructure unused until the final patch
122    finger the last patch as the one which caused the problem, even though
123    the real bug is elsewhere.  Whenever possible, a patch which adds new
126 Working to create the perfect patch series can be a frustrating process
131 Patch formatting and changelogs
132 -------------------------------
135 not done quite yet.  Each patch needs to be formatted into a message which
137 that end, each patch will be composed of the following:
139  - An optional "From" line naming the author of the patch.  This line is
140    only necessary if you are passing on somebody else's patch via email,
143  - A one-line description of what the patch does.  This message should be
145    scope of the patch; it is the line that will show up in the "short form"
147    subsystem name first, followed by the purpose of the patch.  For
154  - A blank line followed by a detailed description of the contents of the
155    patch.  This description can be as long as is required; it should say
156    what the patch does and why it should be applied to the kernel.
158  - One or more tag lines, with, at a minimum, one Signed-off-by: line from
159    the author of the patch.  Tags will be described in more detail below.
161 The items above, together, form the changelog for the patch.  Writing good
162 changelogs is a crucial but often-neglected art; it's worth spending
166 whether the patch should be included, distributors and other maintainers
167 trying to decide whether a patch should be backported to other kernels, bug
168 hunters wondering whether the patch is responsible for a problem they are
174 for the change as well as possible given the one-line constraint.  The
176 needed additional information.  If the patch fixes a bug, cite the commit
181 support other changes coming in later patch, say so.  If internal APIs are
190  - The patch itself, in the unified ("-u") patch format.  Using the "-p"
192    resulting patch easier for others to read.
195 the build process, for example, or editor backup files) in the patch.  The
197 pass it to diff with the "-X" option.
200 the patch came into being. They are described in detail in the
201 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
205 the patch::
207 … 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
210 details, for example an earlier discussion which leads to the patch or a
211 document with a specification implemented by the patch::
213 	Link: https://example.com/somewhere.html  optional-other-stuff
215 Many maintainers when applying a patch also add this tag to link to the
216 latest public review posting of the patch; often this is automatically done
218 'Documentation/maintainer/configure-git.rst'.
220 If the URL points to a public bug report being fixed by the patch, use the
223 	Closes: https://example.com/issues/1234  optional-other-stuff
231 the patch. Each of these uses this format::
233 	tag: Full Name <email address>  optional-other-stuff
237  - Signed-off-by: this is a developer's certification that he or she has
238    the right to submit the patch for inclusion into the kernel.  It is an
240    which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
243  - Co-developed-by: states that the patch was co-created by several developers;
244    it is a used to give attribution to co-authors (in addition to the author
245    attributed by the From: tag) when multiple people work on a single patch.
246    Every Co-developed-by: must be immediately followed by a Signed-off-by: of
247    the associated co-author.  Details and examples can be found in
248    :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
250  - Acked-by: indicates an agreement by another developer (often a
251    maintainer of the relevant code) that the patch is appropriate for
254  - Tested-by: states that the named person has tested the patch and found
257  - Reviewed-by: the named developer has reviewed the patch for correctness;
258 …see the reviewer's statement in :ref:`Documentation/process/submitting-patches.rst <submittingpatc…
261  - Reported-by: names a user who reported a problem which is fixed by this
262    patch; this tag is used to give credit to the (often underappreciated)
266    can be used instead of Closes: if the patch fixes a part of the issue(s)
269  - Cc: the named person received a copy of the patch and had the
274 Reported-by: is fine most of the time as well, but ask for permission if
278 Sending the patch
279 -----------------
284  - Are you sure that your mailer will not corrupt the patches?  Patches
285    which have had gratuitous white-space changes or line wrapping performed
287    be examined in any detail.  If there is any doubt at all, mail the patch
290    :ref:`Documentation/process/email-clients.rst <email_clients>` has some
293  - Are you sure your patch is free of silly mistakes?  You should always
294    run patches through scripts/checkpatch.pl and address the complaints it
302 the patch in their replies.  Instead, just put the patch directly into your
311  - The maintainer(s) of the affected subsystem(s).  As described earlier,
314  - Other developers who have been working in the same area - especially
318  - If you are responding to a bug report or a feature request, copy the
321  - Send a copy to the relevant mailing list, or, if nothing else applies,
322    the linux-kernel list.
324  - If you are fixing a bug, think about whether the fix should go into the
326    the patch.  Also add a "Cc: stable@vger.kernel.org" to the tags within
327    the patch itself; that will cause the stable team to get a notification
330 When selecting recipients for a patch, it is good to have an idea of who
331 you think will eventually accept the patch and get it merged.  While it
336 obvious maintainer, Andrew Morton is often the patch target of last resort.
338 Patches need good subject lines.  The canonical format for a patch line is
343 	[PATCH nn/mm] subsys: one-line description of the patch
345 where "nn" is the ordinal number of the patch, "mm" is the total number of
347 Clearly, nn/mm can be omitted for a single, standalone patch.
355 In general, the second and following parts of a multi-part patch should be
359 are using git, please stay away from the --chain-reply-to option to avoid