Hi Thien-Thi, thanks for having worked on this! I like you proposal very much, with only a couple of nits nit (find them below).
On 01/17/2012 12:26 PM, Thien-Thi Nguyen wrote: > () [email protected] (Karl Berry) > () Fri, 23 Dec 2011 15:47:40 -0800 > > I don't know if any of the (few) other people on bug-standards are > interested, but in any case, if you want a (public :) archive of the > thread, feel free to keep cc-ing the list. > > OK. Please find below a proposed patch to standards.texi. > > ___________________________________________________________________ > > A link to another entry > should be expressed as a date and an optional title, if the date is > insufficient to uniquely identify the precedent. 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. > Here is a slightly-edited example from the Serveez top-level ChangeLog: > [SNIP] 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': ls: be responsive to interrupts when color-listing large directories This change fixes coreutils bug#10243. Starting with commit adc30a83, when using --color, ls inhibited interrupts to avoid corrupting the state of an output terminal. However, for very large directories, that inhibition rendered ls uninterruptible for too long, including a potentially long period even before any output is generated. * src/ls.c: Two phases of processing are time-consuming enough that they can provoke this: the readdir loop and the printing loop. The printing was supposed to be covered by a call to process_signals in (print_name_with_quoting): ... but that call was mistakenly guarded by a condition that might be false for many or even all files being processed. Call process_signals unconditionally. (print_dir): Also call process_signals in the readdir loop. * NEWS (Bug fixes): Mention it. Report by Arkadiusz Miskiewicz. Thanks, Stefano
