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