openjpa-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kevin Sutter <kwsut...@gmail.com>
Subject Re: JIRA references in documentation?
Date Tue, 24 Nov 2009 19:16:28 GMT
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 <dwoods@apache.org> 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
>>
>>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message