[PATCH] Document from line in patch format

[PATCH] Document from line in patch format

[Paul Jackson]

Document more details of patch format such as the "from" line
used to specify the patch author, and provide more references
for patch guidelines.

Signed-off-by: Paul Jackson <pj@sgi.com>

Index: 2.6.14-rc2-mm2/Documentation/SubmittingPatches
===================================================================
--- 2.6.14-rc2-mm2.orig/Documentation/SubmittingPatches
+++ 2.6.14-rc2-mm2/Documentation/SubmittingPatches
@@ -301,8 +301,47 @@ now, but you can do this to mark interna
 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:
+
+    The first line of the body contains a "from" line specifying
+    the author of the patch:
+
+        From: Original Author <author@email.com>
+
+    If the "from" line is missing, then the author of the patch will
+    be recorded in the source code revision history as whomever is
+    listed in the last "Signed-off-by:" line in the message when Linus
+    receives it.
+
+    The "from" line is followed by an empty line and then the body
+    of the explanation.
+
+    After the body of the explanation comes the "Signed-off-by:"
+    lines, and then a simple "---" line, and below that comes the
+    diffstat of the patch and then the patch itself.  The "---" line
+    and diffstat are optional, but helpful to readers of non-trivial
+    patches.
+
+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.
+
+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>
@@ -310,6 +349,14 @@ Andrew Morton, "The perfect patch" (tpp)
 Jeff Garzik, "Linux kernel patch submission format."
   <http://linux.yyz.us/patch-format.html>
 
+Jeff Garzik, "How to piss off a kernel subsystem maintainer"
+  <http://www.kroah.com/log/2005/03/31/>
+
+Kernel Documentation/CodingStyle
+  <http://lxr.linux.no/source/Documentation/CodingStyle>
+
+Linus Torvald's mail on the canonical patch format:
+  <http://lkml.org/lkml/2005/4/7/183>
 
 
 -----------------------------------

-- 
                          I won't rest till it's the best ...
                          Programmer, Linux Scalability
                          Paul Jackson <pj@sgi.com> 1.650.933.1373

Re: [PATCH] Document from line in patch format

[Antonino A. Daplas]

Paul Jackson wrote:
> Document more details of patch format such as the "from" line
> used to specify the patch author, and provide more references
> for patch guidelines.
> 
> Signed-off-by: Paul Jackson <pj@sgi.com>
> 
> Index: 2.6.14-rc2-mm2/Documentation/SubmittingPatches
> ===================================================================
> --- 2.6.14-rc2-mm2.orig/Documentation/SubmittingPatches
> +++ 2.6.14-rc2-mm2/Documentation/SubmittingPatches
> @@ -301,8 +301,47 @@ now, but you can do this to mark interna
>  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:
> +
> +    The first line of the body contains a "from" line specifying
> +    the author of the patch:
> +
> +        From: Original Author <author@email.com>
> +
> +    If the "from" line is missing, then the author of the patch will
> +    be recorded in the source code revision history as whomever is
> +    listed in the last "Signed-off-by:" line in the message when Linus
                     ^^^^ 
Shouldn't this be the first?

Tony

Re: [PATCH] Document from line in patch format

[Paul Jackson]

Tony wrote:
> > +    listed in the last "Signed-off-by:" line in the message when Linus
>                      ^^^^ 
> Shouldn't this be the first?

When I sent a patch with no "from" line, and two "Signed-off-by"
lines (the patch that prompted this excursion into documentation
excellence) Linus stated that the patch author ended up coming from
the second "Signed-off-by" line.

Perhaps it "should" be the first (actually - I tend to agree),
but it seems that it "is" the last.

-- 
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <pj@sgi.com> 1.925.600.0401

Re: [PATCH] Document from line in patch format

[Linus Torvalds]

On Sun, 2 Oct 2005, Paul Jackson wrote:

> Tony wrote:
> > > +    listed in the last "Signed-off-by:" line in the message when Linus
> >                      ^^^^ 
> > Shouldn't this be the first?
> 
> When I sent a patch with no "from" line, and two "Signed-off-by"
> lines (the patch that prompted this excursion into documentation
> excellence) Linus stated that the patch author ended up coming from
> the second "Signed-off-by" line.
> 
> Perhaps it "should" be the first (actually - I tend to agree),
> but it seems that it "is" the last.

No. If there is no "From:" at the top of the body, the authorship is taken 
from the "From:" from the _email_.

Which _usually_ matches the last Signed-off-line:, of course. But can be 
anything.

		Linus

Re: [PATCH] Document from line in patch format

[Paul Jackson]

Linus wrote:
> No. If there is no "From:" at the top of the body, the authorship is taken 
> from the "From:" from the _email_.

So _that_ is the real reason it's called the "from" line,
not the "author" line.

Now it is making more sense.

New patch v2 coming soon.

-- 
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <pj@sgi.com> 1.925.600.0401

Re: [PATCH] Document from line in patch format

[Coywolf Qi Hunt]

On 10/2/05, Paul Jackson <pj@sgi.com> wrote:
> Document more details of patch format such as the "from" line
> used to specify the patch author, and provide more references
> for patch guidelines.
>
> Signed-off-by: Paul Jackson <pj@sgi.com>
>
> Index: 2.6.14-rc2-mm2/Documentation/SubmittingPatches
> ===================================================================
> --- 2.6.14-rc2-mm2.orig/Documentation/SubmittingPatches
> +++ 2.6.14-rc2-mm2/Documentation/SubmittingPatches
> @@ -301,8 +301,47 @@ now, but you can do this to mark interna
>  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:
> +
> +    The first line of the body contains a "from" line specifying
> +    the author of the patch:
> +
> +        From: Original Author <author@email.com>
> +
> +    If the "from" line is missing, then the author of the patch will
> +    be recorded in the source code revision history as whomever is
> +    listed in the last "Signed-off-by:" line in the message when Linus
> +    receives it.
> +
> +    The "from" line is followed by an empty line and then the body
> +    of the explanation.
> +
> +    After the body of the explanation comes the "Signed-off-by:"
> +    lines, and then a simple "---" line, and below that comes the
> +    diffstat of the patch and then the patch itself.  The "---" line
> +    and diffstat are optional, but helpful to readers of non-trivial
> +    patches.
> +
> +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.
> +
> +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>
> @@ -310,6 +349,14 @@ Andrew Morton, "The perfect patch" (tpp)
>  Jeff Garzik, "Linux kernel patch submission format."
>    <http://linux.yyz.us/patch-format.html>
>
> +Jeff Garzik, "How to piss off a kernel subsystem maintainer"
> +  <http://www.kroah.com/log/2005/03/31/>
> +
> +Kernel Documentation/CodingStyle
> +  <http://lxr.linux.no/source/Documentation/CodingStyle>

There's another one more updated at http://sosdg.org/~coywolf/lxr/source/

> +
> +Linus Torvald's mail on the canonical patch format:
> +  <http://lkml.org/lkml/2005/4/7/183>
>

--
Coywolf Qi Hunt

Re: [PATCH] Document from line in patch format

[Paul Jackson]

Coywolf Qi Hunt wrote:
> There's another one more updated at http://sosdg.org/~coywolf/lxr/source/

Excellent - thank-you for continuing to provide us a current
Linux Cross-Reference (LXR).

An updated PATCHv2 coming soon.

-- 
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <pj@sgi.com> 1.925.600.0401

Re: [PATCH] Document from line in patch format

[Greg KH]

On Sat, Oct 01, 2005 at 11:21:35PM -0700, Paul Jackson wrote:
>  
> +Jeff Garzik, "How to piss off a kernel subsystem maintainer"
> +  <http://www.kroah.com/log/2005/03/31/>

That was written by me, not Jeff...

thanks,

greg k-h

Re: [PATCH] Document from line in patch format

[Paul Jackson]

Greg wrote:
> That was written by me, not Jeff...

Duh - you are obviously right.

I guess you will have one more item to add to your list:
  * Attribute work to the wrong author

(once again brought to you by the letters S, G, and I,
just to keep up tradition ').

A new patch forthcoming ...

-- 
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <pj@sgi.com> 1.925.600.0401