On 01/17/2012 02:32 PM, Thien-Thi Nguyen wrote: > () Stefano Lattarini <[email protected]> > () 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 <[email protected]> > 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
