openjpa-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pinaki Poddar <ppod...@apache.org>
Subject Re: JIRA references in documentation?
Date Tue, 24 Nov 2009 20:03:25 GMT

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 <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
>>>
>>>
> 
> 


-----
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.

Mime
View raw message