Re: JIRA references in documentation?

[Kevin Sutter <kw...@gmail.com>]

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 <mi...@gmail.com>wrote:

> On Tue, Nov 24, 2009 at 2:03 PM, Pinaki Poddar <pp...@apache.org> 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 <dw...@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.
> >
>