[jdom-interest] How to upgrade

[Jason Hunter]

> When we released beta 8, we didn't provide a document on how to upgrade, and
> I think this was a mistake. We're still making backwards-incompatible
> changes, and we shouldn't expect people to be following this list and making
> a note of each onei. We need one place where they can go to see what changes
> they'll need to make to their code in order to upgrade. This would be
> different from changes.txt because it'll only show incompatible changes, and
> it'll briefly describe what to do about each one. Ideally I'd like to see
> this both on the JDOM website and in the distribution.

I agree, it'd be a very good thing to have.  I think it's more obvious
with b8 because there are more subtle changes.  Previously things were
pretty obvious.

> Does this sound OK? I'd be happy to write this up for b7 -> b8 and/or for
> subsequent releases. 

Excellent!

> What's the best way to keep track of what's going to
> need to go in here? Jason, how diligent are you about changes.txt? I.e. do
> you think that every incompatible change should be mentioned in there
> somewhere, so that it can be our source?

I'm very diligent about changes.txt.  I base it on the CVS logs and
records, and the reason my check-in messages are verbose is primarily to
help the changes.txt file later.  Note that some of the things I don't
record in changes.txt are, for example, bug fixes in features that were
added after the previous beta -- because those aren't really changes
since the last beta.  I think some protected method changes may sneak by
without being recorded also.  Otherwise I try to be exhaustive.

-jh-