Documentation/process/5.Posting.rst

8 kernel.  Unsurprisingly, the kernel development community has evolved a set
13 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
14 and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
18 ------------
20 There is a constant temptation to avoid posting patches before they are
21 completely "ready."  For simple patches, that is not a problem.  If the
22 work being done is complex, though, there is a lot to be gained by getting
24 consider posting in-progress work, or even making a git tree available so
27 When posting code which is not yet considered ready for inclusion, it is a
30 patches which are known to be half-baked, but those who do will come in
35 -----------------------
37 There are a number of things which should be done before you consider
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
49    benchmarks showing what the impact (or benefit) of your change is; a
52  - Be sure that you have the right to post the code.  If this work was done
53    for an employer, the employer likely has a right to the work and must be
56 As a general rule, putting in some extra thought before posting code almost
61 -----------------
63 The preparation of patches for posting can be a surprising amount of work,
67 Patches must be prepared against a specific version of the kernel.  As a
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
76 against these other trees can require a significant amount of work
79 Only the most simple changes should be formatted as a single patch;
80 everything else should be made as a logical series of changes.  Splitting
81 up patches is a bit of an art; some developers spend a long time figuring
82 out how to do it in the way that the community expects.  There are a few
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
94    large (adding a significant new driver, for example), but they should be
95    conceptually small and amenable to a one-line description.  Each patch
96    should make a specific change which can be reviewed on its own and
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
101    bug, rearranges a few structures, and reformats the code, there is a
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
109    result is a broken kernel, you will make life harder for developers and
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
115    be reasonably large as long as it still contains a single *logical*
118  - It can be tempting to add a whole new infrastructure with a series of
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
127 which takes quite a bit of time and thought after the "real work" has been
132 -------------------------------
134 So now you have a perfect series of patches for posting, but the work is
135 not done quite yet.  Each patch needs to be formatted into a message which
139  - An optional "From" line naming the author of the patch.  This line is
143  - A one-line description of what the patch does.  This message should be
144    enough for a reader who sees it with no other context to figure out the
154  - A blank line followed by a detailed description of the contents of the
158  - One or more tag lines, with, at a minimum, one Signed-off-by: line from
162 changelogs is a crucial but often-neglected art; it's worth spending
163 another moment discussing this issue.  When writing a changelog, you should
164 bear in mind that a number of different people will be reading your words.
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
169 chasing, users who want to know how the kernel has changed, and more.  A
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
178 and the title when citing commits).  If a problem is associated with
180 searching for a solution to the same problem.  If the change is meant to
184 be reading your changelog, the better that changelog (and the kernel as a
188 change to a revision control system.  It will be followed by:
190  - The patch itself, in the unified ("-u") patch format.  Using the "-p"
197 pass it to diff with the "-X" option.
201 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
202 document; what follows here is a brief summary.
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
217 by tools like b4 or a git hook like the one described in
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
225 Some bug trackers have the ability to close issues automatically when a
226 commit with such a tag is applied. Some bots monitoring mailing lists can
233 	tag: Full Name <email address>  optional-other-stuff
237  - Signed-off-by: this is a developer's certification that he or she has
240    which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
241    Code without a proper signoff cannot be merged into the mainline.
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
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
264    correctly. Note, this tag should be followed by a Closes: tag pointing to
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
279 -----------------
281 Before you mail your patches, there are a couple of other things you should
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
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
296    embodiment of a fair amount of thought about what kernel patches should
297    look like, is not smarter than you.  If fixing a checkpatch.pl complaint
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
325    next stable update.  If so, stable@vger.kernel.org should get a copy of
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
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
347 Clearly, nn/mm can be omitted for a single, standalone patch.
349 If you have a significant series of patches, it is customary to send an
355 In general, the second and following parts of a multi-part patch should be
356 sent as a reply to the first part so that they all thread together at the
357 receiving end.  Tools like git and quilt have commands to mail out a set of
358 patches with the proper threading.  If you have a long series, though, and
359 are using git, please stay away from the --chain-reply-to option to avoid