openjpa-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Donald Woods <dwo...@apache.org>
Subject Re: JIRA references in documentation?
Date Tue, 24 Nov 2009 18:12:58 GMT
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
> 

Mime
View raw message