[jdom-interest] JDOM2 Update

[Rolf]

Hi Everyone.

Just to bring everyone up to date with JDOM2.

The current plan is described on the wiki page:
https://github.com/hunterhacker/jdom/wiki/JDOM-2.0

The initial steps are described as:

   1. Migrate the code from CVS to GitHub (keeping all the history).
   2. Create a branch for 2.0
   3. Do the basic package renames.
   4. Fix the test case that's currently failing
(test_TCM__void_setExpandEntities_boolean)
   5. Upgrade the JUnit libraries and tests
   6. Use Cobertura to build up the JUnit test cases to get much better
coverage of the junit tests on JDOM (currently have only got 40% coverage
of the org.junit code from the JUnit test cases....). Fix any issues that
arise in untested code.
   7. Modify the core code and the test harness together to implement the
changes - document what changes are made so that we can get a list of rules
for migration from JDOM 1 to JDOM 2.
   8. Confirm any deviations from 'compatibility' with the jdom-interest
list to ensure that all changes are reasonable.
   9. Complete the migration, ensure all JavaDoc is complete. All Tests
are run, and code test coverage is 'complete'.



The initial preparation steps (set up github, branches, basic package
rename, etc.) are done. See JDOM's new home at
https://github.com/hunterhacker/jdom

What that means is that the current JDOM2 state is:

JDOM2 looks exactly like JDOM, except it has a new package name, and all
the JUnit tests now are based on JUnit 4.8.2.

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.

The most comprehensive way to do that is to ensure that the current JDOM
is well covered with unit tests, and that as we perform the JDOM2
migration, we ensure that all unit tests pass, and if there are any reasons
to change the API, the unit tests get modified to adapt, and the deviation
is documented.

In other words, in order to have the best possible JDOM2 it's important to
ensure that JDOM itself is very well covered for regression tests.


This is where JDOM2 is at the moment: building JUnit tests basically for
JDOM 1.1.1

No work will be done on any 'generics' or other API modifications until
the JUnit tests have adequate coverage for regression purposes.

In order to track the progress of the regression testing, the tool
'Cobertura' is being used to track the JUnit code coverage, and there is an
ant target 'coverage' that will do that for us.

Currently the core JDOM code has about 40% coverage. This number should be
better than 95% before any real 'fun' work can begin.


My expectation is that the JUnit coverage will probably amount to about
half of the real work of the JDOM2 process.


In light of the above, this is also an invitation for assistance in doing
the hard work of building the best and most comprehensive testing we can.

Once that is done we can get on with the fun part of doing the actual
migration (with the security of the unit tests to keep us on track).



In order to set the expectations for JDOM2, I anticipate that any code
submission should be accompanied with as comprehensive JUnit testing as
possible. No changes will be accepted on existing code unless there are
first JUnit tests for that code. No patches/pulls/commits will be allowed
if they result in failing tests.


In order to facilitate the patching/submission process I am happy to
accept contributions in any reasonable format.... but, changes should be in
as small a 'chunk' as reasonably possible though, in order to make merging
and tracking as simple as possible. All changes will be attributed
appropriately.

If you intend to get busy writing JUnit test cases, please drop me a note
so that I can co-ordinate with others writing tests so that there is no
duplication of effort.

If you have any comments, questions, suggestions, please speak up!

Thanks all, happy coding.

Rolf