[PATCHv4] Document from line in patch format

[PATCHv4] Document from line in patch format

[Paul Jackson]

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>

---

Fixed path to Coywolf's Documentation/CodingStyle                               

--- 2.6.14-rc2-mm2.orig/Documentation/SubmittingPatches
+++ 2.6.14-rc2-mm2/Documentation/SubmittingPatches
@@ -301,8 +301,71 @@ 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:
+
+  - 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.  As a compatibility
+hack, some of the patch handling tools take lines beginning with
+"diff -" or "Index: " as alternative forms of the "---" marker.
+The recommended form is "---".
+
+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>
@@ -310,6 +373,14 @@ Andrew Morton, "The perfect patch" (tpp)
 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>
 
 
 -----------------------------------

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

Re: [PATCHv4] Document from line in patch format

[Pete Zaitcev]

On Sun, 2 Oct 2005 18:01:42 -0700 (PDT), Paul Jackson <pj@sgi.com> wrote:

> +    Subject: [PATCH 001/123] [<area>:] <explanation>

An attack of rabid square brackets! :-)

Linus' original e-mail made it quite clear that the area does not
need its own brackets, but this detail seems to have been lost.

-- Pete

Re: [PATCHv4] Document from line in patch format

[Paul Jackson]

Peter wrote:
> Linus' original e-mail made it quite clear that the area does not
> need its own brackets, but this detail seems to have been lost.

I missed that part in Linus's original email.  I kinda thought
the second set of square brackets was ugly, but who was I to
criticize the Master's aesthetic sense <grin>?

I'll go back now and reread that email.

I sense PATCHv5 coming on, soon.

Thanks for catching this.

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

Re: [PATCHv4] Document from line in patch format

[Junio C Hamano]

> +    Subject: [PATCH 001/123] [<area>:] <explanation>

What's funny is that the first pair is literal and the second
one is syntactic.  Perhaps you may want to do an EBNF ;-)?

SUBJECT ::= "Subject: [PATCH" NUMBER "/" NUMBER "]" [ AREA ":" ] EXPLANATION

Although the current explanation tells careful readers that
"From: " in the body is optional, by mentioning what happens if
it is not found, I think it is clearer if you said it upfront.

Maybe something along the lines of:

    The body of the message should be structured as follows.

    - an optional in-body "From: " line (plus an empty line for
      readability), if the author is different from the e-mail
      patch forwarder/sender; followed by

    - the explanation to be recorded as the commit log message;
      followed by

    - an empty line, and signed-off-by lines; followed by

    - mandatory three-dash '---' line; followed by

    - optional non-diff metainformation -- justification message
      to the maintainer, diffstat etc.

    - actual patch material.

I do not know if Linus wants to advertise this, but in addition
to the in-body "From: ", the e-mail patch application tool from
GIT also understands in-body "Date: ", if the patch forwarder
wants to preserve original authorship datestamp in the commit
the maintainer eventually makes out of your e-mail.  Without it,
the "Date: " of the forwarder's e-mail is used as the authorship
datestamp.

Re: [PATCHv4] Document from line in patch format

[Paul Jackson]

Junio wrote:
> Perhaps you may want to do an EBNF ;-)?

Hopefully not required here.

See my subsequent patch - I think it is simple and clear:

  [PATCH] Document patch subject line better

I started a new patch series, since Linus had already picked
up my prior changes.

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