On Tue, Dec 20, 2005 at 07:45:30AM -0800, jerry gay wrote: > 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.
Admittedly, your updating of ChangeLog is what motivated this thread. I
keep a list of modifications in a file named Changes as part of all of my
CPAN distributions but doing such a thing is really a burden for a
project as large as Parrot. I think that your working too hard. ;)
This is something that can be automated.
I also agree that some discipline with respect to the format of changeset
metadata is good but I don't agree with all of your points.
> 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]')
I don't agree with this point because the commit message should be taken
in the context of the file(s) being modified. An example GNU format
ChangeLog entry (actually generated from the Parrot tree) for a language
changeset would look:
2005-12-16 05:22 allison
* trunk, trunk/MANIFEST, trunk/MANIFEST.SKIP,
trunk/config/gen/makefiles/punie.in,
trunk/languages/punie/demo.p1, trunk/languages/punie/lib,
trunk/languages/punie/lib/PunieGrammar.pir,
trunk/languages/punie/lib/punie.g,
trunk/languages/punie/pge_compile.pir,
trunk/languages/punie/punie.pir: Refactor Punie so it uses a
pre-compiled PGE grammar.
Another example of a lengthy commit message not being required when put
in context:
2005-12-17 19:35 jhoblitt
* trunk/MANIFEST: sorted
> ~ 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')
I think that sort of metadata is more appropriate for an RT ticket. A
commit messages should describe primarily * what* is being changed
instead of *why* the change is being made. Of course, including the
*why* doesn't hurt but I don't believe it should be part of our
guidelines.
> ~ details (if appropriate) should be provided in a bullet-list format
> for easy reading
> (eg. '* added handle jiggling to flush all buffers')
I don't really like that either but that's really just a matter of
style.
> i hope this (incomplete) list is helpful. if these guidelines are
> followed, a generated changelog will be valuable without getting in
> the way.
I agree with all of your other points. Somebody should write this up
and add it to the tree. Perhaps under docs/dev?
Cheers,
-J
--
pgpTEvFDz82aD.pgp
Description: PGP signature
