ChangeLog entries

[Mark Wielaard]

Hi,

I would really like everybody to follow the ChangeLog entry guidelines
given in:
http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html

I will try to update out hacking document with some of the style guides
later. But maybe a couple of examples are more clear. So here is how I
would like to see some of the ChangeLog entries of today:

>         * java/awt/font/OpenType.java: Remove 'public static final'
>         from OpenType tags, reverting the change of 2003-08-11.  See
>         Classpath discussion list of 2003-08-11.

This should just state:

        * java/awt/font/OpenType.java: Remove 'public static final' from
        all member fields.

The explanation why should either be in the code or (more appropriate in
this case be added to our hacking document.

>         * java/io/ObjectOutputStream.java : allow putFields be called more 
> than
> once

Don't make lines longer then 80 characters. And this explains the effect
of the change, which should be in a comment in the code if appropriate.
The ChangeLog should just explain what changed:

        * java/io/ObjectOutputStream.java (putFields): Don't call
        markFieldsWritten(). Only create new PutField when
        currentPutField is null.
        (writeFields): Call markFieldsWritten().

Also this patch included more then just the above. It also cleaned up
some exceptions. Which is nice, but should probably be a separate patch
and the change should be documented in the ChangeLog.

(Sidenote. Since Throwables can now be chained it is a good idea to use
Throwable.setCause() and not just add the String representation of a
exception to another exception.)

Hope these examples help. And I do appreciate the fact that writing
ChangeLog entries, using a coding style that is not "your own" and the
CVS, patch and diff tools do take some time to getting used to. So don't
feel like you have to do it perfect right away or that contributions
aren't welcome if they aren't 'perfect'. We all learn by doing and
interacting with each other. And over time I might actually learn to be
a bit less uptight maintainer :)

One more thing. I really want to have a pretty open check-in policy. But
this means that you should be extra careful if you check something in.
If at all in doubt or if you think that something might need extra
explaining since it is not completely obvious please make a little
announcement about the change on the main classpath mailinglist. And if
you do commit something without discussing it first and another GNU
Classpath hackers asks for extra explanation or suggests to revert a
certain commit then please reply to the request by explaining why
something should be so or if you agree to revert it. (Just reverting
immediately is OK without discussion, but then please don't mix it with
other changes.)

All the above is really meant to make sure that GNU Classpath will be
maintainable in the long run and to give all the projects that are now
using GNU Classpath an accurate view of the changes we make to the code
and to see what changed when.

If you think that the above "project rules" are impractical or will
hinder contributions please contact me. I am happy to do code cleanups
and/or write ChangeLog entries for submissions (although that can mean
that your contribution takes a bit longer to get into the main tree).
And we can always setup a classpath-patches mailinglist to really
discuss and/or approve of each change before it gets committed, but I
think that will add to much bureaucracy at the moment.

Cheers,

Mark