Re: changelog format

[Stefano Lattarini]

On 01/17/2012 02:32 PM, Thien-Thi Nguyen wrote:
> () Stefano Lattarini <address@hidden>
> () Tue, 17 Jan 2012 13:09:34 +0100
> 
>    thanks for having worked on this!  I like you proposal very
>    much, with only a couple of nits nit (find them below).
> 
> I appreciate your patience.
>
I appreciate your work :-)

>    > A link to another entry [...].  We recommend this
>    > over using a version control system commit identifier
>    >
>    I'd really, really like to see "in addition to" instead of "over"
>    used her, since VCS commit identifiers have at least an important
>    advantage of their own: they make it immediate for the reader to
>    refer to the linked entry, instead of having to rely on (say)
>    "git log --grep" or "git log --since=... --until=...".  This is
>    even more true for GUI interfaces to the VCS, where VCS commit
>    identifiers might be automatically turned in clickable links.
> 
> I agree that such conveniences are very compelling.  My fear
> is that people would use VCS commit identifiers exclusively;
>
Honestly I've been guilty of doing so for quite a long time now (and should
get rid of this bad habit ASAP).  But my (or others?) laziness/sloppiness is
IMHO no excuse to give in incorrect advice in the GCS.

> saying "in addition to" is not strong enough.  Any other ideas?
>
Maybe we could provide a "blessed" script that the developer could use in lieu
of "git describe" (or similar commands for other VCS) to get a GCS-conforming
string referring to a past commit.  The idea is that, instead of doing something
like this:

  $ git describe c592a00f
  v8.14-91-gc592a00

the developer could do something like this:

  $ gnu-vcs-describe c592a00f
  v8.14-91-c592a00 (2011-12-08, "ls: be responsive to interrupts ...")

WDYT?

>    I think it would be nice to also ad another example with a slightly
>    different style.  I propose this slightly edited version of the commit
>    message for the GNU coreutils commit 'c592a00f': [...]
> 
> Good idea.  What is the ChangeLog header for this?  Can i assume:
>   2011-12-08  Jim Meyering  <address@hidden>
> as per ‘git show c592a00f’?
>
Yes.

> (Meta-comment: This extra step shows
> how generated ChangeLog files are inconvenient to casual readers.)
>
How so?  Note that I've copied & pasted the above from the git output, not
from the corresponding generated ChangeLog.

> I note that there is more than one paragraph, so i guess i'll change
> the "short paragraph" to "paragraph(s)".
>
+1

Thanks,
  Stefano