Lines Matching refs:the
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;
9 more information can also be found in the files SubmittingPatches,
10 SubmittingDrivers, and SubmitChecklist in the kernel documentation
17 completely "ready." For simple patches, that is not a problem. If the
19 feedback from the community before the work is complete. So you should
24 good idea to say so in the posting itself. Also mention any major work
27 with the idea that they can help you drive the work in the right direction.
33 sending patches to the development community. These include:
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
40 - Make sure your code is compliant with the kernel coding style
44 benchmarks showing what the impact (or benefit) of your change is; a
45 summary of the results should be included with the patch.
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.
52 always pays back the effort in short order.
59 even in the short term.
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
64 point - a stable or -rc release - rather than branching off the mainline at
69 on the area of your patch and what is going on elsewhere, basing a patch
73 Only the most simple changes should be formatted as a single patch;
76 out how to do it in the way that the community expects. There are a few
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
83 discrete, self-contained changes, not the path you took to get to those
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
100 patch series is interrupted in the middle, the result should still be a
102 scenario when the "git bisect" tool is used to find regressions; if the
104 users who are engaging in the noble work of tracking down problems.
108 the most popular person on the kernel mailing list. A single patch can
113 patches, but to leave that infrastructure unused until the final patch
114 in the series enables the whole thing. This temptation should be
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
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
127 So now you have a perfect series of patches for posting, but the work is
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:
132 - An optional "From" line naming the author of the patch. This line is
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
145 - A blank line followed by a detailed description of the contents of the
147 what the patch does and why it should be applied to the kernel.
150 the author of the patch. Tags will be described in more detail below.
152 The items above, together, form the changelog for the patch. Writing good
157 whether the patch should be included, distributors and other maintainers
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
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
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
171 searching for a solution to the same problem. If the change is meant to
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
178 Needless to say, the changelog should be the text used when committing the
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
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.
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:
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
203 proper signoff cannot be merged into the mainline.
206 maintainer of the relevant code) that the patch is appropriate for
207 inclusion into the kernel.
209 - Tested-by: states that the named person has tested the patch and found
212 - Reviewed-by: the named developer has reviewed the patch for correctness;
213 see the reviewer's statement in Documentation/SubmittingPatches for more
217 patch; this tag is used to give credit to the (often underappreciated)
221 - Cc: the named person received a copy of the patch and had the
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.
233 - Are you sure that your mailer will not corrupt the patches? Patches
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
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
247 would make the code worse, don't do it.
251 the patch in their replies. Instead, just put the patch directly into your
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,
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.
263 - Other developers who have been working in the same area - especially
265 modified the files you are working on can be helpful.
267 - If you are responding to a bug report or a feature request, copy the
270 - Send a copy to the relevant mailing list, or, if nothing else applies,
271 the linux-kernel list.
273 - If you are fixing a bug, think about whether the fix should go into the
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.
280 you think will eventually accept the patch and get it merged. While it
283 subsystem maintainers who watch over specific parts of the kernel. Usually
285 obvious maintainer, Andrew Morton is often the patch target of last resort.
290 [PATCH nn/mm] subsys: one-line description of the patch
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.
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.
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
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