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

[David Malcolm <dmalcolm at redhat dot com>]

On Thu, 2015-08-20 at 18:37 -0400, Jason Merrill wrote:
> On 08/20/2015 06:32 PM, Segher Boessenkool wrote:
> > On Thu, Aug 20, 2015 at 03:31:52PM -0400, David Malcolm wrote:
> >> If we're going to migrate to git (I hope so), can we also please
> >> *slightly* revise the policy on commit messages, to add meaningful
> >> titles to commits?
> >>
> >> Currently:
> >> https://www.gnu.org/software/gcc/svnwrite.html#checkin says:
> >>
> >> "The log message for that checkin should be the complete ChangeLog entry
> >> for the change."
> >>
> >> and the subsection "Commit the changes to the central repository" below
> >> https://www.gnu.org/software/gcc/svnwrite.html#example
> >> has an example showing this.
> >>
> >>
> >> 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.

> > And many bonus points
> > if we don't have to repeat the changelog in the commit message (it's in
> > the commit already, the bugzilla hook could just pull it from out there).
> >
> > Or we could have another discussion about if we want to have changelogs
> > at all...
> 
> That's a good question, but I think it's definitely independent.
> 
> Jason
> 

? htdocs/.#index.html.1.940
? htdocs/index.html.~1.940.~
? htdocs/svnwrite.html.~1.34.~
Index: htdocs/svnwrite.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/svnwrite.html,v
retrieving revision 1.34
diff -u -p -r1.34 svnwrite.html
--- htdocs/svnwrite.html	6 Apr 2015 12:15:18 -0000	1.34
+++ htdocs/svnwrite.html	21 Aug 2015 21:40:10 -0000
@@ -210,13 +210,20 @@ when performing checkins to avoid accide
 code.</p>
 
 <p>We prefer that each SVN checkin be of a complete, single logical
-change, which may affect multiple files.  The log message for that
-checkin should be the complete ChangeLog entry for the change.  This
-makes it easier to correlate changes across files, and minimizes the
+change, which may affect multiple files.  This makes it easier to
+correlate changes across files, and minimizes the
 time the repository is inconsistent.  If you have several unrelated
 changes, you should check them in with separate SVN commit
 commands.</p>
 
+<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>
+
 <ol>
 <li>Sync your sources with the master repository via "<code>svn
 update</code>" before attempting a checkin; this will save you a little
@@ -253,7 +260,12 @@ an error occurs and it will not check in
 <h2><a name="example">Example check-in session</a></h2>
 
 <p>Here's an actual check-in session for a patch John Carr recently
-sent to the GCC list.  This was the ChangeLog for his change:</p>
+sent to the GCC list.</p>
+
+<p>His patch was sent in a mail titled
+<pre>compiler patches for HOST_WIDE_INT = long long</pre></p>
+
+<p>This was the ChangeLog for his change:</p>
 
 <blockquote><pre>
 Sun Feb  8 08:02:13 1998  John Carr  &lt;jfc@mit.edu>
@@ -355,11 +367,12 @@ this particular case all three needed th
 [/law/gcc/gcc] svn commit ChangeLog bitmap.c calls.c genattrtab.c
 </pre></blockquote>
 
-<p>My editor starts and I enter the log message; the lines starting
+<p>My editor starts and I enter the title and log message; the lines starting
 with <code>This line, and those below, will be ignored</code> are automatically 
 added by SVN and will be automatically removed:</p>
 
-<blockquote><pre>
+<blockquote><pre>compiler patches for HOST_WIDE_INT = long long
+
         * bitmap.c (bitmap_debug_file): HOST_PTR_PRINTF converts a pointer,
         not a HOST_WIDE_INT.