Hi Donald, Thanks for the background. Having an "issues" section for our release notes or release page like Derby provides isn't a bad idea. I just don't know if I like them in the documentation. Since they are limited to the (In)Compatibility section at the end of the documentation, at least they would be confined to a single section. But, we still need to ensure that the referenced JIRAs actually do provide the information that we say they do. And, providing a link to the actual JIRA would help.
Other thoughts or ideas? Kevin On Tue, Nov 24, 2009 at 12:12 PM, Donald Woods <[email protected]> wrote: > 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 >> >>
