1.. _development_posting:
2
3Posting patches
4===============
5
6Sooner or later, the time comes when your work is ready to be presented to
7the community for review and, eventually, inclusion into the mainline
8kernel.  Unsurprisingly, the kernel development community has evolved a set
9of conventions and procedures which are used in the posting of patches;
10following them will make life much easier for everybody involved.  This
11document will attempt to cover these expectations in reasonable detail;
12more information can also be found in the files
13:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`,
14:ref:`Documentation/process/submitting-drivers.rst  <submittingdrivers>`
15and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
16
17
18When to post
19------------
20
21There is a constant temptation to avoid posting patches before they are
22completely "ready."  For simple patches, that is not a problem.  If the
23work being done is complex, though, there is a lot to be gained by getting
24feedback from the community before the work is complete.  So you should
25consider posting in-progress work, or even making a git tree available so
26that interested developers can catch up with your work at any time.
27
28When posting code which is not yet considered ready for inclusion, it is a
29good idea to say so in the posting itself.  Also mention any major work
30which remains to be done and any known problems.  Fewer people will look at
31patches which are known to be half-baked, but those who do will come in
32with the idea that they can help you drive the work in the right direction.
33
34
35Before creating patches
36-----------------------
37
38There are a number of things which should be done before you consider
39sending 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
57As a general rule, putting in some extra thought before posting code almost
58always pays back the effort in short order.
59
60
61Patch preparation
62-----------------
63
64The preparation of patches for posting can be a surprising amount of work,
65but, once again, attempting to save time here is not generally advisable
66even in the short term.
67
68Patches must be prepared against a specific version of the kernel.  As a
69general rule, a patch should be based on the current mainline as found in
70Linus's git tree.  When basing on mainline, start with a well-known release
71point - a stable or -rc release - rather than branching off the mainline at
72an arbitrary spot.
73
74It may become necessary to make versions against -mm, linux-next, or a
75subsystem tree, though, to facilitate wider testing and review.  Depending
76on the area of your patch and what is going on elsewhere, basing a patch
77against these other trees can require a significant amount of work
78resolving conflicts and dealing with API changes.
79
80Only the most simple changes should be formatted as a single patch;
81everything else should be made as a logical series of changes.  Splitting
82up patches is a bit of an art; some developers spend a long time figuring
83out how to do it in the way that the community expects.  There are a few
84rules 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
127Working to create the perfect patch series can be a frustrating process
128which takes quite a bit of time and thought after the "real work" has been
129done.  When done properly, though, it is time well spent.
130
131
132Patch formatting and changelogs
133-------------------------------
134
135So now you have a perfect series of patches for posting, but the work is
136not done quite yet.  Each patch needs to be formatted into a message which
137quickly and clearly communicates its purpose to the rest of the world.  To
138that 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
162The items above, together, form the changelog for the patch.  Writing good
163changelogs is a crucial but often-neglected art; it's worth spending
164another moment discussing this issue.  When writing a changelog, you should
165bear in mind that a number of different people will be reading your words.
166These include subsystem maintainers and reviewers who need to decide
167whether the patch should be included, distributors and other maintainers
168trying to decide whether a patch should be backported to other kernels, bug
169hunters wondering whether the patch is responsible for a problem they are
170chasing, users who want to know how the kernel has changed, and more.  A
171good changelog conveys the needed information to all of these people in the
172most direct and concise way possible.
173
174To that end, the summary line should describe the effects of and motivation
175for the change as well as possible given the one-line constraint.  The
176detailed description can then amplify on those topics and provide any
177needed additional information.  If the patch fixes a bug, cite the commit
178which introduced the bug if possible (and please provide both the commit ID
179and the title when citing commits).  If a problem is associated with
180specific log or compiler output, include that output to help others
181searching for a solution to the same problem.  If the change is meant to
182support other changes coming in later patch, say so.  If internal APIs are
183changed, detail those changes and how other developers should respond.  In
184general, the more you can put yourself into the shoes of everybody who will
185be reading your changelog, the better that changelog (and the kernel as a
186whole) will be.
187
188Needless to say, the changelog should be the text used when committing the
189change 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
195You should avoid including changes to irrelevant files (those generated by
196the build process, for example, or editor backup files) in the patch.  The
197file "dontdiff" in the Documentation directory can help in this regard;
198pass it to diff with the "-X" option.
199
200The tags already briefly mentioned above are used to provide insights how
201the patch came into being. They are described in detail in the
202:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
203document; what follows here is a brief summary.
204
205One tag is used to refer to earlier commits which introduced problems fixed by
206the patch::
207
208	Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
209
210Another tag is used for linking web pages with additional backgrounds or
211details, for example a report about a bug fixed by the patch or a document
212with a specification implemented by the patch::
213
214	Link: https://example.com/somewhere.html  optional-other-stuff
215
216Many maintainers when applying a patch also add this tag to link to the
217latest public review posting of the patch; often this is automatically done
218by tools like b4 or a git hook like the one described in
219'Documentation/maintainer/configure-git.rst'.
220
221A third kind of tag is used to document who was involved in the development of
222the patch. Each of these uses this format::
223
224	tag: Full Name <email address>  optional-other-stuff
225
226The tags in common use are:
227
228 - Signed-off-by: this is a developer's certification that he or she has
229   the right to submit the patch for inclusion into the kernel.  It is an
230   agreement to the Developer's Certificate of Origin, the full text of
231   which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
232   Code without a proper signoff cannot be merged into the mainline.
233
234 - Co-developed-by: states that the patch was co-created by several developers;
235   it is a used to give attribution to co-authors (in addition to the author
236   attributed by the From: tag) when multiple people work on a single patch.
237   Every Co-developed-by: must be immediately followed by a Signed-off-by: of
238   the associated co-author.  Details and examples can be found in
239   :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
240
241 - Acked-by: indicates an agreement by another developer (often a
242   maintainer of the relevant code) that the patch is appropriate for
243   inclusion into the kernel.
244
245 - Tested-by: states that the named person has tested the patch and found
246   it to work.
247
248 - Reviewed-by: the named developer has reviewed the patch for correctness;
249   see the reviewer's statement in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
250   for more detail.
251
252 - Reported-by: names a user who reported a problem which is fixed by this
253   patch; this tag is used to give credit to the (often underappreciated)
254   people who test our code and let us know when things do not work
255   correctly.
256
257 - Cc: the named person received a copy of the patch and had the
258   opportunity to comment on it.
259
260Be careful in the addition of tags to your patches: only Cc: is appropriate
261for addition without the explicit permission of the person named.
262
263
264Sending the patch
265-----------------
266
267Before you mail your patches, there are a couple of other things you should
268take care of:
269
270 - Are you sure that your mailer will not corrupt the patches?  Patches
271   which have had gratuitous white-space changes or line wrapping performed
272   by the mail client will not apply at the other end, and often will not
273   be examined in any detail.  If there is any doubt at all, mail the patch
274   to yourself and convince yourself that it shows up intact.
275
276   :ref:`Documentation/process/email-clients.rst <email_clients>` has some
277   helpful hints on making specific mail clients work for sending patches.
278
279 - Are you sure your patch is free of silly mistakes?  You should always
280   run patches through scripts/checkpatch.pl and address the complaints it
281   comes up with.  Please bear in mind that checkpatch.pl, while being the
282   embodiment of a fair amount of thought about what kernel patches should
283   look like, is not smarter than you.  If fixing a checkpatch.pl complaint
284   would make the code worse, don't do it.
285
286Patches should always be sent as plain text.  Please do not send them as
287attachments; that makes it much harder for reviewers to quote sections of
288the patch in their replies.  Instead, just put the patch directly into your
289message.
290
291When mailing patches, it is important to send copies to anybody who might
292be interested in it.  Unlike some other projects, the kernel encourages
293people to err on the side of sending too many copies; don't assume that the
294relevant people will see your posting on the mailing lists.  In particular,
295copies should go to:
296
297 - The maintainer(s) of the affected subsystem(s).  As described earlier,
298   the MAINTAINERS file is the first place to look for these people.
299
300 - Other developers who have been working in the same area - especially
301   those who might be working there now.  Using git to see who else has
302   modified the files you are working on can be helpful.
303
304 - If you are responding to a bug report or a feature request, copy the
305   original poster as well.
306
307 - Send a copy to the relevant mailing list, or, if nothing else applies,
308   the linux-kernel list.
309
310 - If you are fixing a bug, think about whether the fix should go into the
311   next stable update.  If so, stable@vger.kernel.org should get a copy of
312   the patch.  Also add a "Cc: stable@vger.kernel.org" to the tags within
313   the patch itself; that will cause the stable team to get a notification
314   when your fix goes into the mainline.
315
316When selecting recipients for a patch, it is good to have an idea of who
317you think will eventually accept the patch and get it merged.  While it
318is possible to send patches directly to Linus Torvalds and have him merge
319them, things are not normally done that way.  Linus is busy, and there are
320subsystem maintainers who watch over specific parts of the kernel.  Usually
321you will be wanting that maintainer to merge your patches.  If there is no
322obvious maintainer, Andrew Morton is often the patch target of last resort.
323
324Patches need good subject lines.  The canonical format for a patch line is
325something like:
326
327::
328
329	[PATCH nn/mm] subsys: one-line description of the patch
330
331where "nn" is the ordinal number of the patch, "mm" is the total number of
332patches in the series, and "subsys" is the name of the affected subsystem.
333Clearly, nn/mm can be omitted for a single, standalone patch.
334
335If you have a significant series of patches, it is customary to send an
336introductory description as part zero.  This convention is not universally
337followed though; if you use it, remember that information in the
338introduction does not make it into the kernel changelogs.  So please ensure
339that the patches, themselves, have complete changelog information.
340
341In general, the second and following parts of a multi-part patch should be
342sent as a reply to the first part so that they all thread together at the
343receiving end.  Tools like git and quilt have commands to mail out a set of
344patches with the proper threading.  If you have a long series, though, and
345are using git, please stay away from the --chain-reply-to option to avoid
346creating exceptionally deep nesting.
347