Referring to JIRA issue that contains a bunch of test cases/code commits from user documentation does not appear to be a user-friendly approach. The documentation should cover (in order of appearance) each incompatibity in a template such as:
0) classification of the incompatibility (is it going to break compilation, runtime, semantic behavior, internal etc). We should discuss categories of incompatibilities to come up with a good set. 1) semantic difference of the same API between OpenJPA 2.0 and previous version(s) 2) sometimes a previous API is replaced by OpenJPA 2.0 but the old semantics is retained in a new API method with a different name or slightly different signature. If that is the case, then refer to the new modified API 3) openjpa.Compatibility options to use OpenJPA 2.0 API with previous behavior, if applicable 4) If compatibility options are not available, then other alternative course to emulate past behavior 5) then comes 'please refer to OPENJPA-XXX' for further details on usage etc... The current documentation is broadly following the above template -- but some more uniformity across each incompatibility is required. But overall the aggregation of the information by Donald/release manager is commendable and in the right direction. Kevin Sutter wrote: > > 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 >>> >>> > > ----- Pinaki -- View this message in context: http://n2.nabble.com/JIRA-references-in-documentation-tp4058419p4060780.html Sent from the OpenJPA Developers mailing list archive at Nabble.com.
