Meaning of Release Notes, was: Release Notes

[Rick Hillegas <Ri...@Sun.COM>]

The original thread seems to have split into at least three topics:

1) Should we bundle Release Notes with our zips? I believe the consensus 
was yes.

2) What does it mean to mark a JIRA as fixed in multiple releases? This 
topic has sparked a lot of useful discussion.

3) What issues should go into the Release Notes for a particular release?

I'm forking off a new thread to continue discussing topic (3). I think 
we want to end up with the following situation: If a customer leap-frogs 
several intervening releases, then the customer should be able to 
reconstruct the composite delta by studying the Release Notes for all of 
the releases along an upgrade trajectory.

I am content with this simple model: the Release Notes just describe the 
delta between the current release and some previous release. We're 
golden provided that the customer can trace an upgrade trajectory 
through that previous release.

The tricky bit would be an oddball release like 10.1.7, which follows 
10.2 in wall-clock-time but precedes 10.2 in upgrade-time. Who describes 
the delta between 10.1.7 and 10.2? I don't feel we have to answer this 
question today but we should keep it in mind if we decide to issue an 
oddball release.

That is what I was hoping to do for 10.2:

i) State in the Release Notes that we're only describing the delta 
between 10.1.3 and 10.2.
ii) Then document that delta. Of course, as Kathey points out, this is 
easier said than done given the discussion about topic (2).

Please let me know if you think this is not adequate.

Thanks,
-Rick

Re: Meaning of Release Notes, was: Release Notes

[Andrew McIntyre <mc...@gmail.com>]

On 9/11/06, Rick Hillegas <Ri...@sun.com> wrote:
>
> I am content with this simple model: the Release Notes just describe the
> delta between the current release and some previous release. We're
> golden provided that the customer can trace an upgrade trajectory
> through that previous release.

+1, always a good idea to be explicit about what you are documenting
and I think this covers all the necessary bases.

> The tricky bit would be an oddball release like 10.1.7, which follows
> 10.2 in wall-clock-time but precedes 10.2 in upgrade-time. Who describes
> the delta between 10.1.7 and 10.2?

The answer is: whomever makes the 10.1.7 release, since they are the
ones who have the information to describe the delta between 10.1.7 and
the 10.1.6 (and any other - 12.17.x, 11.2.3.2, 10.3.x, etc.) releases
that have already been made in the interim.

> That is what I was hoping to do for 10.2:
>
> i) State in the Release Notes that we're only describing the delta
> between 10.1.3 and 10.2.
> ii) Then document that delta. Of course, as Kathey points out, this is
> easier said than done given the discussion about topic

I think the only change I would make to the above is that the delta is
between 10.2.1.x and 10.1.3.1, since that's the latest official 10.1
release at this time. Since there are already changes merged (and
marked in JIRA) as Fix In 10.1.3.2, you need that last digit in the
version number to distinguish what you're documenting as being in the
official release 10.1.3.1 as opposed to the as-yet unreleased 10.1.3.2
and/or 10.1.4.x.

There's a discussion to be had there about when it's appropriate to
bump the third part of the version, but I'm willing to save it for a
later date.

andrew

Re: Meaning of Release Notes, was: Release Notes

[Kathey Marsden <km...@sbcglobal.net>]

Rick Hillegas wrote:

> That is what I was hoping to do for 10.2:
>
> i) State in the Release Notes that we're only describing the delta 
> between 10.1.3 and 10.2.
> ii) Then document that delta. Of course, as Kathey points out, this is 
> easier said than done given the discussion about topic (2).
>
> Please let me know if you think this is not adequate.
>
This sounds good to me Rick.

Kathey