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 <j...@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.
