Documentation/development-process/5.Posting

5 kernel.  Unsurprisingly, the kernel development community has evolved a set
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
20 consider posting in-progress work, or even making a git tree available so
23 When posting code which is not yet considered ready for inclusion, it is a
32 There are a number of things which should be done before you consider
44    benchmarks showing what the impact (or benefit) of your change is; a
48    for an employer, the employer likely has a right to the work and must be
51 As a general rule, putting in some extra thought before posting code almost
57 The preparation of patches for posting can be a surprising amount of work,
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
67 It may become necessary to make versions against -mm, linux-next, or a
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
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
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
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
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
103    result is a broken kernel, you will make life harder for developers and
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*
112  - It can be tempting to add a whole new infrastructure with a series of
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
128 not done quite yet.  Each patch needs to be formatted into a message which
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
145  - A blank line followed by a detailed description of the contents of the
149  - One or more tag lines, with, at a minimum, one Signed-off-by: line from
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.
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
167 needed additional information.  If the patch fixes a bug, cite the commit
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
175 be reading your changelog, the better that changelog (and the kernel as a
179 change to a revision control system.  It will be followed by:
192 detail in the SubmittingPatches document; what follows here is a brief
199  - Signed-off-by: this is a developer's certification that he or she has
202    which can be found in Documentation/SubmittingPatches.  Code without a
205  - Acked-by: indicates an agreement by another developer (often a
216  - Reported-by: names a user who reported a problem which is fixed by this
221  - Cc: the named person received a copy of the patch and had the
230 Before you mail your patches, there are a couple of other things you should
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
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,
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
279 When selecting recipients for a patch, it is good to have an idea of who
287 Patches need good subject lines.  The canonical format for a patch line is
294 Clearly, nn/mm can be omitted for a single, standalone patch.
296 If you have a significant series of patches, it is customary to send an
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