This is the mail archive of the
mailing list for the GCC project.
[PATCH][www] svnwrite.html: recommend giving checkin messages a title (was Re: Moving to git)
- From: David Malcolm <dmalcolm at redhat dot com>
- To: Jason Merrill <jason at redhat dot com>
- Cc: Segher Boessenkool <segher at kernel dot crashing dot org>, "gcc at gnu dot org" <gcc at gnu dot org>, Gerald Pfeifer <gerald at pfeifer dot com>
- Date: Fri, 21 Aug 2015 19:54:11 -0400
- Subject: [PATCH][www] svnwrite.html: recommend giving checkin messages a title (was Re: Moving to git)
- Authentication-results: sourceware.org; auth=none
- References: <55D61512 dot 8010002 at redhat dot com> <1440099112 dot 18943 dot 38 dot camel at surprise> <20150820223226 dot GA27127 at gate dot crashing dot org> <55D656B7 dot 9000707 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
> > 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.
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
<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
+<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]"
<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>
Sun Feb 8 08:02:13 1998 John Carr <email@example.com>
@@ -355,11 +367,12 @@ this particular case all three needed th
[/law/gcc/gcc] svn commit ChangeLog bitmap.c calls.c genattrtab.c
-<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>compiler patches for HOST_WIDE_INT = long long
* bitmap.c (bitmap_debug_file): HOST_PTR_PRINTF converts a pointer,
not a HOST_WIDE_INT.