openjpa-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Dick <michael.d.d...@gmail.com>
Subject Re: JIRA references in documentation?
Date Wed, 25 Nov 2009 03:36:00 GMT
On Tue, Nov 24, 2009 at 2:03 PM, Pinaki Poddar <ppoddar@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 <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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message