On 12/20/05, Joshua Hoblitt <[EMAIL PROTECTED]> wrote: > In it's current form ChangeLog is little more than a pointer to NEWS. > This is really defeating the purpose of what ChangeLog is supposed to > contain; detailed information about changes. It is also more or less > redundant with the function of NEWS. However, I am not proposing that > people start adding detailed information to ChangeLog. I think it is > entirely reasonable to machine generate this file with svn2cl[1] before > each release. Comments? > i've recently started updating changelog during my directory reorg, as i was told it would make it easier to generate the debian package (so it is useful.) automatic generation sounds great, but it's no good without clear commit messages. one or two word commit messages should be shunned in favor of brief yet clear descriptions of the change, including which parrot components are affected.
here are some guidelines for good commit messages, from my observations: ~ languages should prefix the message with the language name/nickname (eg. 'tcl: added compiled [frobnitz]') ~ if the work is against a ticket, the ticket number and title should be included in the message (eg. '[#3141592] [PATCH] add moonphase op) ~ if the work is being committed for someone without ci rights, a courtesy message should be included (eg. 'Courtesy of Alex the Parrot <[EMAIL PROTECTED]>') ~ if the commit is platform dependent, or has been tested on one or more platforms, say it (eg. 'tested successfully on i386-linux-gcc-4.0 and win32-msvc-7.1') ~ details (if appropriate) should be provided in a bullet-list format for easy reading (eg. '* added handle jiggling to flush all buffers') i hope this (incomplete) list is helpful. if these guidelines are followed, a generated changelog will be valuable without getting in the way. ~jerry
