[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>

[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>
Paul Jackson · Linus Torvalds
1 parent d70ddac1bf
Showing 1 changed file with 69 additions and 1 deletions Side-by-side Diff
Documentation/SubmittingPatches
@@ -301,15 +301,83 @@
 point out some special detail about the sign-off. 
  
  
+12) The canonical patch format
  
-12) More references for submitting patches
+The canonical patch subject line is:
  
+    Subject: [PATCH 001/123] [<area>:] <explanation>
+
+The canonical patch message body contains the following:
+
+  - A "from" line specifying the patch author.
+
+  - An empty line.
+
+  - The body of the explanation, which will be copied to the
+    permanent changelog to describe this patch.
+
+  - The "Signed-off-by:" lines, described above, which will
+    also go in the changelog.
+
+  - A marker line containing simply "---".
+
+  - Any additional comments not suitable for the changelog.
+
+  - The actual patch (diff output).
+
+The Subject line format makes it very easy to sort the emails
+alphabetically by subject line - pretty much any email reader will
+support that - since because the sequence number is zero-padded,
+the numerical and alphabetic sort is the same.
+
+See further details on how to phrase the "<explanation>" in the
+"Subject:" line in Andrew Morton's "The perfect patch", referenced
+below.
+
+The "from" line must be the very first line in the message body,
+and has the form:
+
+        From: Original Author <author@example.com>
+
+The "from" line specifies who will be credited as the author of the
+patch in the permanent changelog.  If the "from" line is missing,
+then the "From:" line from the email header will be used to determine
+the patch author in the changelog.
+
+The explanation body will be committed to the permanent source
+changelog, so should make sense to a competent reader who has long
+since forgotten the immediate details of the discussion that might
+have led to this patch.
+
+The "---" marker line serves the essential purpose of marking for patch
+handling tools where the changelog message ends.
+
+One good use for the additional comments after the "---" marker is for
+a diffstat, to show what files have changed, and the number of inserted
+and deleted lines per file.  A diffstat is especially useful on bigger
+patches.  Other comments relevant only to the moment or the maintainer,
+not suitable for the permanent changelog, should also go here.
+
+See more details on the proper patch format in the following
+references.
+
+
+13) More references for submitting patches
+
 Andrew Morton, "The perfect patch" (tpp).
   <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt>
  
 Jeff Garzik, "Linux kernel patch submission format."
   <http://linux.yyz.us/patch-format.html>
  
+Greg KH, "How to piss off a kernel subsystem maintainer"
+  <http://www.kroah.com/log/2005/03/31/>
+
+Kernel Documentation/CodingStyle
+  <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle>
+
+Linus Torvald's mail on the canonical patch format:
+  <http://lkml.org/lkml/2005/4/7/183>
  
  
 -----------------------------------
...	...	@@ -301,15 +301,83 @@
301	301	point out some special detail about the sign-off.
302	302
303	303
	304	+12) The canonical patch format
304	305
305		-12) More references for submitting patches
	306	+The canonical patch subject line is:
306	307
	308	+ Subject: [PATCH 001/123] [<area>:] <explanation>
	309	+
	310	+The 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	+
	328	+The Subject line format makes it very easy to sort the emails
	329	+alphabetically by subject line - pretty much any email reader will
	330	+support that - since because the sequence number is zero-padded,
	331	+the numerical and alphabetic sort is the same.
	332	+
	333	+See further details on how to phrase the "<explanation>" in the
	334	+"Subject:" line in Andrew Morton's "The perfect patch", referenced
	335	+below.
	336	+
	337	+The "from" line must be the very first line in the message body,
	338	+and has the form:
	339	+
	340	+ From: Original Author <author@example.com>
	341	+
	342	+The "from" line specifies who will be credited as the author of the
	343	+patch in the permanent changelog. If the "from" line is missing,
	344	+then the "From:" line from the email header will be used to determine
	345	+the patch author in the changelog.
	346	+
	347	+The explanation body will be committed to the permanent source
	348	+changelog, so should make sense to a competent reader who has long
	349	+since forgotten the immediate details of the discussion that might
	350	+have led to this patch.
	351	+
	352	+The "---" marker line serves the essential purpose of marking for patch
	353	+handling tools where the changelog message ends.
	354	+
	355	+One good use for the additional comments after the "---" marker is for
	356	+a diffstat, to show what files have changed, and the number of inserted
	357	+and deleted lines per file. A diffstat is especially useful on bigger
	358	+patches. Other comments relevant only to the moment or the maintainer,
	359	+not suitable for the permanent changelog, should also go here.
	360	+
	361	+See more details on the proper patch format in the following
	362	+references.
	363	+
	364	+
	365	+13) More references for submitting patches
	366	+
307	367	Andrew Morton, "The perfect patch" (tpp).
308	368	<http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt>
309	369
310	370	Jeff Garzik, "Linux kernel patch submission format."
311	371	<http://linux.yyz.us/patch-format.html>
312	372
	373	+Greg KH, "How to piss off a kernel subsystem maintainer"
	374	+ <http://www.kroah.com/log/2005/03/31/>
	375	+
	376	+Kernel Documentation/CodingStyle
	377	+ <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle>
	378	+
	379	+Linus Torvald's mail on the canonical patch format:
	380	+ <http://lkml.org/lkml/2005/4/7/183>
313	381
314	382
315	383	-----------------------------------