Good discussion, everyone. Based on this discussion, I've opened a JIRA [1] to track the proposed changes. It seems that with a few minor updates, we'll have a more consistent, useful section in our documentation. I did not assign an owner yet and I only targeted the 2.0.x release for now. Update the JIRA as needed. Thanks for the discussion.
Kevin [1] https://issues.apache.org/jira/browse/OPENJPA-1406 On Tue, Nov 24, 2009 at 9:36 PM, Michael Dick <[email protected]>wrote: > On Tue, Nov 24, 2009 at 2:03 PM, Pinaki Poddar <[email protected]> wrote: > > > > > 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. > > > > Good idea. Separating the compatibility changes by release, and then > category makes sense to me. > > I'm in favor of simplicity here : build and runtime make sense but it's not > obvious to me what would differentiate semantic behavior from runtime. > Internal changes should have no effect on applications and would be > documented in comments or just in the JIRA issue. If we see other trends > emerging we can add a category at a later date (for example we may want > subcategories for runtime). > > > > 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 > > > > I'd combine 2,3, and 4 into a single element. I think it will be rare that > we'll provide both a Compatibility option and a new API for example. This > section need not be the ultimate source for all documentation between > releases, so we should give an overview and link back to the detail in the > javadoc / properties documentation. > > > > 5) then comes 'please refer to OPENJPA-XXX' for further details on usage > > etc... > > > > +1, but there's no reason not to use a url. First time users shouldn't have > to go back to the homepage to find the link to the JIRA and search for a > given number (or just Google). Linking to the example code in svn when > applicable would be good too. > > > > 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. > > > > I agree, Donald, Dianne, Jeremy, and Ravi have done an excellent job here. > This was a much needed and appreciated addition to the manual. > > -mike > > > > > > > > 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. > > >
