Re: [PATCH][www] svnwrite.html: recommend giving checkin messages a title (was Re: Moving to git)

[David Malcolm <dmalcolm at redhat dot com>]

On Sat, 2015-08-22 at 05:55 -0500, Segher Boessenkool wrote:
> On Fri, Aug 21, 2015 at 07:54:11PM -0400, David Malcolm wrote:
> > > >> In the git world, the first line of the commit message has special
> > > >> meaning, being treated as the "title" of the commit.
> > > >
> > > > It would be nice if we could use a real commit message, not just a short
> > > > title line; for example, people who prepare their patches in git already
> > > > have that, and use it with format-patch as you say.
> > > 
> > > I think that's what David was suggesting; a short title line, followed 
> > > by a blank line, followed by a more substantive commit message.
> > > 
> > > This change doesn't need to be tied to the git transition; it could 
> > > happen either before or after.
> > 
> > Attached is a patch for the website which advises doing this when                                        
> > committing.

I'm sorry that this was badly worded; "which" in the above was meant to
refer to the patch, not the website.

The purpose of the patch is to make a slight change to the policy (to
add titles), as well as to document the new policy.

> > +<p>The log message for a checkin should be a single line giving a
> > +descriptive title for the checkin, followed by a blank line, followed by
> > +the complete ChangeLog entry for the change.  This is the git convention;
> > +giving titles to checkins makes life easier for developers using git
> > +mirrors of SVN.  Typically the descriptive title should be the "Subject"
> > +line of the relevant gcc-patches thread (without any "[PATCH]" or "[PING]"
> > +prefixes).</p>
> 
> It advises to *not* have an explanatory text, and it says that *not*
> having it is the Git convention (which of course is not true).

I'm having trouble parsing this.  What did you mean by "it" in the three
places you used it here?   By "explanatory text", were you referring to
the descriptive title, or to the text after the blank line?

(I haven't had my coffee yet this morning, so my apologies if I'm
misreading things...)

Dave