You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@openjpa.apache.org by Kevin Sutter <kw...@gmail.com> on 2009/11/24 16:16:01 UTC
JIRA references in documentation?
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
Re: JIRA references in documentation?
Posted by Donald Woods <dw...@apache.org>.
BTW - I now have the rsync setup as a real cron job on p.a.o to run 5
mins after every hour. Finally found the instructions on how to get it
working -
http://cwiki.apache.org/confluence/display/CWIKI/Index#Index-Canweusetheautoexportsiteaspartofourmainwebsite%3F
-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
>
Re: JIRA references in documentation?
Posted by 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.
> >
>
Re: JIRA references in documentation?
Posted by Michael Dick <mi...@gmail.com>.
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.
>
Re: JIRA references in documentation?
Posted by Pinaki Poddar <pp...@apache.org>.
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 <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.
Re: JIRA references in documentation?
Posted by Kevin Sutter <kw...@gmail.com>.
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
>>
>>
Re: JIRA references in documentation?
Posted by Donald Woods <dw...@apache.org>.
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
>