Well, the JIRA pointers were my idea...
The thought being, that if someone is concerned with a particular
migration issue, then they obviously are working with their application
source code and should have no problems looking at our SVN commits to
see the exact junits that demonstrate the behavioral differences between
1.x and 2.0.
The descriptions could probably use some more text, like documenting
that a method returns IllegalArgumentException now instead of a
XYZException, which would remove the need for the JIRA links, but we
should then create a Migration section in the release notes which point
to these JIRAs, like the Derby team does for their releases (which they
call Issues due to them being migration issues) -
http://db.apache.org/derby/releases/release-10.5.3.0.cgi#Issues
-Donald
Kevin Sutter wrote:
Hi,
While I was looking for some information in our documentation in trunk, I
came across several references to JIRAs. The section on Incompatibilities
[1] really stuck out for me. I'm not thrilled with this approach. For a
few reasons...
o It forces customers to go find some other tool (JIRA) to look up
additional information. We've found several Users and even some Dev mailing
list contributors that don't know anything about JIRA.
o It makes us look "lazy". Instead of completing the documentation, we're
telling customers to go on a scavenger hunt.
o Some of the references are basically worthless. For example, in the
section on detach [2], there is a reference to OPENJPA-1215 for more
testcases that document the situation. But, there are no patches or commits
on this JIRA, so the reference is bogus.
Now that you know my thoughts on this approach, I'd like to hear your
comments and ideas. If agreeable, then I'd also like to solicit volunteers
to get this cleaned up.
Thanks,
Kevin
[1]
http://openjpa.apache.org/builds/latest/docs/manual/manual.html#jpa_2.0_incompatibilities
[2]
http://openjpa.apache.org/builds/latest/docs/manual/manual.html#migration_detach_behavior
