aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorPaul Jackson <pj@sgi.com>2005-10-02 21:01:42 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2005-10-02 21:28:09 -0400
commit75f8426c17bc091260a6f7536ba10767596e15eb (patch)
tree8858ac4d497ed8a37bc307fbd8f5b80e81dd4a06 /Documentation
parentd70ddac1bf3a8b102996588010ca87018c3a4a04 (diff)
[PATCH] Document from line in patch format
Document more details of patch format such as the "from" line and the "---" marker line, and provide more references for patch guidelines. Signed-off-by: Paul Jackson <pj@sgi.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/SubmittingPatches70
1 files changed, 69 insertions, 1 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 7f43b040311e..1d96efec5e8f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -301,8 +301,68 @@ now, but you can do this to mark internal company procedures or just
301point out some special detail about the sign-off. 301point out some special detail about the sign-off.
302 302
303 303
30412) The canonical patch format
304 305
30512) More references for submitting patches 306The canonical patch subject line is:
307
308 Subject: [PATCH 001/123] [<area>:] <explanation>
309
310The canonical patch message body contains the following:
311
312 - A "from" line specifying the patch author.
313
314 - An empty line.
315
316 - The body of the explanation, which will be copied to the
317 permanent changelog to describe this patch.
318
319 - The "Signed-off-by:" lines, described above, which will
320 also go in the changelog.
321
322 - A marker line containing simply "---".
323
324 - Any additional comments not suitable for the changelog.
325
326 - The actual patch (diff output).
327
328The Subject line format makes it very easy to sort the emails
329alphabetically by subject line - pretty much any email reader will
330support that - since because the sequence number is zero-padded,
331the numerical and alphabetic sort is the same.
332
333See further details on how to phrase the "<explanation>" in the
334"Subject:" line in Andrew Morton's "The perfect patch", referenced
335below.
336
337The "from" line must be the very first line in the message body,
338and has the form:
339
340 From: Original Author <author@example.com>
341
342The "from" line specifies who will be credited as the author of the
343patch in the permanent changelog. If the "from" line is missing,
344then the "From:" line from the email header will be used to determine
345the patch author in the changelog.
346
347The explanation body will be committed to the permanent source
348changelog, so should make sense to a competent reader who has long
349since forgotten the immediate details of the discussion that might
350have led to this patch.
351
352The "---" marker line serves the essential purpose of marking for patch
353handling tools where the changelog message ends.
354
355One good use for the additional comments after the "---" marker is for
356a diffstat, to show what files have changed, and the number of inserted
357and deleted lines per file. A diffstat is especially useful on bigger
358patches. Other comments relevant only to the moment or the maintainer,
359not suitable for the permanent changelog, should also go here.
360
361See more details on the proper patch format in the following
362references.
363
364
36513) More references for submitting patches
306 366
307Andrew Morton, "The perfect patch" (tpp). 367Andrew Morton, "The perfect patch" (tpp).
308 <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> 368 <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt>
@@ -310,6 +370,14 @@ Andrew Morton, "The perfect patch" (tpp).
310Jeff Garzik, "Linux kernel patch submission format." 370Jeff Garzik, "Linux kernel patch submission format."
311 <http://linux.yyz.us/patch-format.html> 371 <http://linux.yyz.us/patch-format.html>
312 372
373Greg KH, "How to piss off a kernel subsystem maintainer"
374 <http://www.kroah.com/log/2005/03/31/>
375
376Kernel Documentation/CodingStyle
377 <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle>
378
379Linus Torvald's mail on the canonical patch format:
380 <http://lkml.org/lkml/2005/4/7/183>
313 381
314 382
315----------------------------------- 383-----------------------------------