> From: Junio C Hamano <gitster@xxxxxxxxx>
>
> > From e87227498ef3d50dc20584c24c53071cce63c555 Mon Sep 17 00:00:00 2001
> > From: Dale Worley <worley@xxxxxxxxxxx>
> > Date: Tue, 7 May 2013 13:39:46 -0400
> > Subject: [PATCH] CodingGuidelines: make it clear which files in
> > Documentation/ are the sources
>
> These five lines are present in the output of the format-patch only
> to help you fill in the MUA's mail header (instead of typing the
> subject, you can cut and paste from here, for example); after you
> are done with the MUA headers, remove them and do not leave them in
> the body of the message.
I was thinking that that was the intention. But SubmittingPatches
makes it sound like the *entire* output of "git format-patch" is
intended to be the *body* of the e-mail message:
"git format-patch" command follows the best current practice to
format the body of an e-mail message. At the beginning of the
patch should come your commit 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.
In particular, while the line "From e87227..." appears to be the
typical Unix mailbox start-of-message line, it wasn't clear to me
whether it was supposed to be sent or not: If I do the obvious
cut-and-paste of the "From:", "Date:", and "Subject:" lines into the
headers of the e-mail message and copy the following lines into the
body, the "From e87227..." line will have no place to go. And perhaps
it is an important part of the patch, since "git format-patch" outputs
it?
If you could give me some guidance in regard to the "From e87227..."
line, that would be helpful. (I suppose I should try to improve that
paragraph of SubmittingPatches to prevent anyone else from having the
same misunderstanding.)
> > Signed-off-by: Dale R. Worley <worley@xxxxxxxxxxx>
>
> The title looks a bit too long. For a small and obviously correct
> patch like this, I do not think you would need anything in the log
> message, some of what you wrote below the three-dash line may
> deserve to be said here. Perhaps:
>
> Subject: [PATCH] CodingGuidelines: Documentation/*.txt are the sources
>
> People not familiar with AsciiDoc may not realize they are
> supposed to update *.txt files and not *.html/*.1 files when
> preparing patches to the project.
>
> But it invites a question. Why do people patching Git not to know *.txt
> are the sources in the first place? Generated *.html files are not
> even tracked.
Now that you mention it, I see the mistake I have made. I had
forgotten that I did a build of Git from that working copy, and so the
*.html and *.1 files might be generated files rather than tracked
files. And I hadn't yet learned that "git ls-files git-submodule.*"
would do about the same thing that "svn status git-submodule.*" does,
that is, tell the natures of the various files that are present.
> > Documentation/CodingGuidelines | 4 +++-
> > 1 files changed, 3 insertions(+), 1 deletions(-)
> >
> > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> > index 7e4d571..b8eef7c 100644
> > --- a/Documentation/CodingGuidelines
> > +++ b/Documentation/CodingGuidelines
> > @@ -238,7 +238,9 @@ For Python scripts:
> > Writing Documentation:
> >
> > Most (if not all) of the documentation pages are written in AsciiDoc
> > - and processed into HTML output and manpages.
> > + and processed into HTML output and manpages. This means that the *.txt
> > + files in this directory are usually the sources from which the
> > + corresponding *.html, *.1, and *.xml files are generated.
>
> Whenever you see somebody writing "This means that" or "In other
> words", it is a good habit to ask if the existing text can be
> improved so that it does not need such a follow-up clarification.
That's true. But it also appears to be a less risky approach to
someone who is editing the text and does not know its history.
> Most (if not all) of the documentation pages are written in the
> AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and
> processed into HTML and manpages (e.g. git.html and git.1 in the
> same directory).
>
> > Every user-visible change should be reflected in the documentation.
> > The same general rule as for code applies -- imitate the existing
Thank you for your help. I will revise my patch (and learning
exercise) and resubmit it.
Dale
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html