Re: JDOM2 Update

hi Noel.

brace yourself, a long mail... ;-)

On Thu, 11 Aug 2011 15:22:55 +0200, Noel Grandin <[email protected]> wrote:
> Rolf wrote:
>> In order to have a clear and documented migration path from JDOM to
JDOM2
>> we need to know and document all significant changes in the API.
> There is no need to keep track of this. There are various tools for
> generating an API diff between 2 versions of a
> software component.

'There is no need to keep track...'  is a fairly strong statement. Having
a 'reference' of the differences between JDOM and JDOM2 will be useful for
a number of reasons:
1. it indicates what motivation there could be to migrate
2. it indicates what challenges will be involved in the migration
3. it indicates that each 'deviation' has been carefully considered.

JDOM's stability is 'legendary', and is a 'feature'. This sort of
reference would give 'credibility' to JDOM2.

How the document is made is less significant, but, if each change actually
*is* carefully considered, then documenting it on the way should be
trivial.

I know that where I work a clear outline of what the changes/features in
JDOM2 are will make the difference between a migration project happening or
not.

As for the tools available, I am interested to hear more about those. I've
never investigated such things. Do you have recommendations? If nothing
else, it would be really interesting to verify/reconcile any manually
prepared document with a tool's results. I wonder if there are tools smart
enough to pick up that Element.addContent(null) is going to now throw
NullPointerException instead of IllegalArgumentException for example.

>> No work will be done on any 'generics' or other API modifications until
>> the JUnit tests have adequate coverage for regression purposes.
> That's a fine way to discourage interest. Most people don't like writing
> tests at best.
> Making us write tests for someone else's 3-year old code is just going
to
> stifle contributions.
> 

Perhaps you are right about stifling contributions, but if I could counter
your statements with:
1. the code is far older than 3 years!
2. the tests will have to be written at some point.... why not before? ...
or are you suggesting that the code should be untested? In theory, the
JDOM2 migration should change the tests very little.
3. writing tests for the code you are about to change makes you understand
the code you are going to change a whole lot better, and your changes will
be a better quality. Think of it like a 'reminder', or 'warmup' of what you
need to know to get it right.
4. people who are willing to put in the hardest work should be first in
line to be doing 'the fun stuff'. Put it another way, the people who care
enough to do the hard work are more likely to care about the final outcome.
5. the quality of JDOM2 will be directly related to the knowledge,
familiarity, and commitment of the contributors. I can't name a single
person who is 'intimately' familiar with JDOM's code. Even those people who
initially wrote it (apologies Jason, Elliotte, Brad, Brett, Laurent,
Victor, etc.) have to dust off the cobwebs of their memory banks before
they can (re-)understand the more intimate nuances of the code. The people
who write the JDOM tests will become the de-facto "experts".
6. as people go through the code writing the tests they will get ideas
about how things can be 'fixed' with Java5 concepts. These can all lead to
planning/discussing/'kicking' ideas before we actually write the changes.
All these ideas can be tracked on github, and the merits of conflicting
ideas can be thrashed out better than a simple 'ad-hoc' migration. People
who are familiar with the actual code (not just the concepts) will have
different opinions, valuable opinions.
7. this is an opportunity to become a key player in a respected tool where
your actual knowledge of JDOM can be learned 'on the job'. You could be the
one to bring JDOM back to the forefront of Java/XML libraries that works
well with Generics (none of the other libraries does anything resembling a
good job in this respect).

I think there is this idea that 'making JDOM2 generified is easy'. I have
done it once, and then recently I did it again, and came up with completely
different ideas (partly due to having 3 more experience with generics,
partly due to having a looser concept of compatibility). What I learned
from that is that there is definitely more than one way to do it. We need
'qualified' people to make the decisions as to which mechanisms are good,
will work, are best etc.

JDOM2 is more than just a chance to make it 'Generic'. It is an
opportunity 'fix' issues that affect the API, to introduce new concepts to
the API (XPath on each node like XOM?), etc.

Also, JDOM2 will be an opportunity of 'rapid development' (all things
being relative), where things that are not normally considered for JDOM
(like performance fixes, etc.) will be proposed, applied, etc. All those
idea's you've had are now fair game for discussion.

It has taken (by my count) 7 years to get from the point from the first
interest in Java5 compatibility, to actually getting something happening.
http://markmail.org/message/glxnqjcqkgi5mvpg

Doing it right is more important than doing it fast. I have done it 'fast'
once, and there are a lot of 'decisions' I made that need review,
discussion, alternatives, etc.

If you can be swayed by 'anecdotal' stuff, I am currently building
testcases for the code, and am running in to a lot of issues. Things that
the current testing of JDOM have not revealed, but my new tests have are.
Is it better to migrate a 'clean' code base, or would you rather migrate
the issues, and then fix the JDOM2 code?

Also, for example, the current 'MODS'/fixed/default issue has required me
to build test cases just to understand the existing code, to see why it has
the funny nuances it does, and how something solves/fixes a problem. If
those test cases had already existed then it would have been a lot quicker
for someone to respond to the initial issue.


Finally, having a plan is always better than having no plan. Having a plan
where the incentive and reward is at the end is a better plan. If you can
justify a better plan I am all ears.

If you are suspicious about whether there are people out there who will
still be encouraged to contribute, I have a lot of hope. For a start,
there's me. If there's one person then there will probably be more. 

Also, if no-one steps up, it will just take longer to get the tests done.
I am working through them, but I/we *will* get there. Then, if people want
to hop on the band wagon when the tests are built to work on the fun stuff,
then they'll be welcome too, but hopefully by then the big ideas will have
already been discussed, and some of the bigger decisions already made, etc.
At that point it should all be about implementing a new 'sub-plan' of what
JDOM2 should look like, and that sub-plan will have been fleshed out while
people get up-to-speed on the code. 

Anyway, enough rambling. If I gave the impression that I am hoping for
dedicated, committed people to help on the JDOM2 migration, then, actually,
that's a good thing, right?

Rolf
_______________________________________________
To control your jdom-interest membership:
http://www.jdom.org/mailman/options/jdom-interest/[email protected]