Re: Commit instructions

[Paul Smith]

On Fri, 2013-10-18 at 16:50 +0300, Eli Zaretskii wrote:
> > From: Paul Smith <address@hidden>
> > Cc: address@hidden
> > Date: Fri, 18 Oct 2013 08:19:27 -0400
> > 
> > One question; I've seen this in other places as well but I don't
> > understand it: is there a purpose to indenting the body of the commit
> > message by one space?
> 
> It allows me to easily discern between the summary line and the
> details, and also makes it easier to search for the next commit when
> paging through the log.  Otherwise, there's nothing sacred about it.

The default log format will already indent the complete log message by 4
spaces, while leaving the header information flush left, so it's easy to
search (just find the next '^commit' for example).  At least that's how
it works for me.  Is your log output different?

|commit 52191d9d613819a77a321ad6c3ab16e1bc73c381
|Author: Paul Smith <address@hidden>
|Date:   2013-10-09 01:54:24 -0400
|
|    GNU Make release 4.0.
|
|commit dc9ae5e017e6a8c162a0e15d28c09ace49c33c3a
|Author: Paul Smith <address@hidden>
|Date:   2013-10-09 01:53:55 -0400
|
|    [SV 39709] Fix some typos.
|
|commit 723e0474286be3b200e01d695c3f63a30565fe1a
|Author: Eli Zaretskii <address@hidden>
|Date:   2013-10-07 19:16:11 +0300
|
|    Untabify posixfcn.c.

I don't care, I'm just curious.

> > Also, if we're going to be following ChangeLog conventions wouldn't each
> > section be preceded by a "*"?
> 
> I think it gets in the way when you want to read the changes, but if
> you want these, I won't object.

Either way.  The only reason to keep them is if you visit the ChangeLog
buffer in Emacs it will go into ChangeLog mode and get font-locked.  If
you use the "real" ChangeLog format with the "*" prefix then you get
nicely colorized ChangeLog entries, otherwise you don't.

> So I need to have a literal "Copyright-paperwork-exempt: Yes"
> somewhere in the commit message?

Looks like it, yes; at the beginning of a line.  According to the
script, it must match this RE:

   ^Copyright-paperwork-exempt:\s+[Yy]es$

> > I have been using the notation "[SV <bug#>]" in the commit summary line
> > to mark changes related to Savannah bugs, but that's just a style.
> 
> I'm accustomed to something like this:
> 
>   Fix SV bug#NNNN with doing this-and-that when such-and-such.
> 
> is that OK?

Sure.

> More importantly, will these references end up in the ChangeLog that
> is produced from git log?

Everything in the commit message (except for the "SPECIAL SYNTAX" lines
in my previous email) goes into the ChangeLog.  And with a very few
exceptions the commit log message is not modified at all.

You can run "make ChangeLog" to see what it will look like; the script
is written in Perl so it should work fine on Windows (you do need to a
"git clone" of the gnulib project though).  Let me know if there are
issues with this.