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 <[email protected]>
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 <[email protected]>
+
+ 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 <[email protected]> 1.650.933.1373
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 <[email protected]>
>
> 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 <[email protected]>
> +
> + 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
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 <[email protected]> 1.925.600.0401
On 10/2/05, Paul Jackson <[email protected]> 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 <[email protected]>
>
> 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 <[email protected]>
> +
> + 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
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
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
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 <[email protected]> 1.925.600.0401
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 <[email protected]> 1.925.600.0401
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 <[email protected]> 1.925.600.0401