[PATCH] SubmittingPatches: clarify some details of the patch format

2013-08-06 Thread Dale R. Worley
---
This is a first draft of a patch that clarifies a number of points
about how patches should be formatted that have tripped me up.  I have
re-filled a few of the paragraphs, which makes it hard to see from the
diff what I've changed.  This listing shows the changed words between
{ ... }:

 { This first line should be a separate paragraph, that is, it should be
followed by an empty line, which is then followed by the body of the
commit message } .

 { At the end of the commit message should be a Signed-off-by line giving
your name.  This can be added to the commit message automatically by
giving git commit the --signoff option.  This line has legal
implications, see Sign your work below } .

People on the Git mailing list need to be able to read and comment on
the changes you are submitting.  It is important for a developer to be
able to quote your changes, using standard e-mail tools, so that
they may comment on specific portions of your code.  For this reason,
all patches should be submitted inline { rather than as message
attachments } .  If your log message (including your name on the
Signed-off-by line) is not writable in ASCII, make sure that you send
off { the } message in the correct encoding.

git format-patch command follows the best current practice to
format the { patch for transmission as an e-mail message.  The files
that it outputs are sample e-mail messages in mh format.  The
initial lines are sample From, To, Date, and Subject headers, which
you will likely have to remove or revise, depending on how your MUA
operates } .

At the beginning of the patch should come your commit message ( { the
first line in the Subject header, the remainder in the body of the
message } ), ending with the Signed-off-by: lines, and a line that
consists of three dashes, followed by the diffstat information and the
patch itself.  If you are forwarding a patch from somebody else,
optionally, at the beginning of the e-mail message just before the
commit message starts, you can put a From:  line to name that
person.

You often want to add additional explanation about the patch,
other than the commit message itself.  Place such cover letter
material between the three-dash { line } and the diffstat. Git-notes
can also be inserted using the `--notes` option.

 From: Junio C Hamano gits...@pobox.com
 
 I am not sure if SubmittingPatches is a good place, though.
 The document is a guidance for people who contribute to _this_
 project.
 
 But the specialness of the first paragraph applies to any project
 that uses Git, so people other than those who contribute to this
 project should be aware of it.

All of that is true.  But what can we do to ensure that someone who
submits a patch does so with the right format?  The special treatment
of the first line is not a requirement.  See, e.g., the git-commit
manual page:

   Though not required, it’s a good idea to begin the commit message with
   a single short (less than 50 character) line summarizing the change,
   followed by a blank line and then a more thorough description. Tools
   that turn commits into email, for example, use the first line on the
   Subject: line and the rest of the commit in the body.

 Originally we literally used first line, but that made many things
 like shortlog output and patch Subject: useless when people write a
 block of text starting from the first line without a title.  Also
 after resurrecting such a text from e-mail, am couldn't tell if
 the first line on the Subject: is meant to be the first line of
 the same first paragraph (which is not what we encourage), or it is
 properly a single line title, and need a blank line before the first
 line of the body.  So quite a while ago, we changed the rule to take
 the first paragraph and use that in these places where we want to
 give a title of a patch.

And as you note, if organizing the first line this way was a
requirement, git-am would be able to unambiguously reconstruct the
commit message from an e-mail.  The only way to minimize errors in
this probject is to clearly specify what is required within this
project.

Dale


 Documentation/SubmittingPatches |   47 +-
 1 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d0a4733..e974dd7 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -85,6 +85,10 @@ identifier for the general area of the code being modified, 
e.g.
 If in doubt which identifier to use, run git log --no-merges on the
 files you are modifying to see the current conventions.
 
+This first line should be a separate paragraph, that is, it should be
+followed by an empty line, which is then followed by the body of the
+commit message.
+
 The body should provide a meaningful 

Re: [PATCH] SubmittingPatches: clarify some details of the patch format

2013-08-06 Thread Junio C Hamano
wor...@alum.mit.edu (Dale R. Worley) writes:

 ---
 This is a first draft of a patch that clarifies a number of points
 about how patches should be formatted that have tripped me up.  I have
 re-filled a few of the paragraphs, which makes it hard to see from the
 diff what I've changed.  This listing shows the changed words between
 { ... }:

  { This first line should be a separate paragraph, that is, it should be
 followed by an empty line, which is then followed by the body of the
 commit message } .

Correct; I tend to prefer phrasing that avoid that is, though.

the first line should be followed by an empty line to form a
separate paragraph on its own and give a summary of the change.

  { At the end of the commit message should be a Signed-off-by line giving
 your name.  This can be added to the commit message automatically by
 giving git commit the --signoff option.  This line has legal
 implications, see Sign your work below } .

OK.

 People on the Git mailing list need to be able to read and comment on
 the changes you are submitting.  It is important for a developer to be
 able to quote your changes, using standard e-mail tools, so that
 they may comment on specific portions of your code.  For this reason,
 all patches should be submitted inline { rather than as message
 attachments } .  If your log message (including your name on the
 Signed-off-by line) is not writable in ASCII, make sure that you send
 off { the } message in the correct encoding.

OK.

 git format-patch command follows the best current practice to
 format the { patch for transmission as an e-mail message.  The files
 that it outputs are sample e-mail messages in mh format.  The

Not mh, but mbox.

 initial lines are sample From, To, Date, and Subject headers, which
 you will likely have to remove or revise, depending on how your MUA
 operates } .

Correct.  They are designed to be moved to your MUA header fields
(so they will disappear from the body but you do not have to type
them to your MUA).

 At the beginning of the patch should come your commit message ( { the
 first line in the Subject header, the remainder in the body of the
 message } ), ending with the Signed-off-by: lines, and a line that
 consists of three dashes, followed by the diffstat information and the
 patch itself.  If you are forwarding a patch from somebody else,
 optionally, at the beginning of the e-mail message just before the
 commit message starts, you can put a From:  line to name that
 person.

... followed by an empty line?

 You often want to add additional explanation about the patch,
 other than the commit message itself.  Place such cover letter
 material between the three-dash { line } and the diffstat. Git-notes
 can also be inserted using the `--notes` option.

OK.

 From: Junio C Hamano gits...@pobox.com
 
 I am not sure if SubmittingPatches is a good place, though.
 The document is a guidance for people who contribute to _this_
 project.
 
 But the specialness of the first paragraph applies to any project
 that uses Git, so people other than those who contribute to this
 project should be aware of it.

 All of that is true.  But what can we do to ensure that someone who
 submits a patch does so with the right format?  The special treatment
 of the first line is not a requirement.  See, e.g., the git-commit
 manual page:

Though not required, it’s a good idea to begin the commit message with
a single short (less than 50 character) line summarizing the change,
followed by a blank line and then a more thorough description. Tools
that turn commits into email, for example, use the first line on the
Subject: line and the rest of the commit in the body.

This is one of the thing I explained in the Originally we literally
used background story in the previous message.  The paragraph's
use the first line is no longer correct, afaik.

We take the first paragraph and make it a logical single line if/as
necessary, using RFC2822 header folding to put it on the Subject:
line.

This project requires you to have a short single-line paragraph as
the first paragraph of the log message, and stating it in SubP
document is good.

 -People on the Git mailing list need to be able to read and
 -comment on the changes you are submitting.  It is important for
 -a developer to be able to quote your changes, using standard
 -e-mail tools, so that they may comment on specific portions of
 -your code.  For this reason, all patches should be submitted
 -inline.  If your log message (including your name on the
 -Signed-off-by line) is not writable in ASCII, make sure that
 -you send off a message in the correct encoding.
 +People on the Git mailing list need to be able to read and comment on
 +the changes you are submitting.  It is important for a developer to be
 +able to quote your