Re: [PATCHv2] CodingGuidelines: make it clear which files in Documentation/ are the sources

From: Junio C Hamano <redacted>

quoted

From e87227498ef3d50dc20584c24c53071cce63c555 Mon Sep 17 00:00:00 2001
From: Dale Worley <redacted>
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.)

quoted

Signed-off-by: Dale R. Worley <redacted>

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.

quoted

 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).

quoted

  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