About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / development-process / 5.Posting


Based on kernel version 4.8. Page generated on 2016-10-06 23:10 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog