You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by Andrew McIntyre <mc...@gmail.com> on 2006/09/08 10:23:23 UTC
Re: Re: Release Notes
On 8/24/06, Daniel John Debrunner <dj...@apache.org> wrote:
>
> Does that mean the downloaded packages have no release notes? So if a
> release is made with known bugs, the only way to find that out is to go
> to the Apache Derby site and find the release notes there?
>
> This seems like an issue, it's typically to have this kind of
> information with the download, not separate. It's also based upon an
> assumption that internet access is easy, which is not true for all of
> the world. People may be getting Derby from CD/DVDs or bundled within
> other applications. Assuming there's an easy path back to the apacche
> site seems wrong.
Agreed. 10.1.3.1 was the first release where issues that affect
user-visible behavior had proper release notes and were documented
before the release happened. I fear that I set a bad precedent there.
I think that for 10.2 (and any other releases going forward, including
a possible 10.1.4 release), that any issues that are known and
documented at the time of the release should be documented in a
release notes file at the top of the installation tree in all of the
distributions, along with a pointer to the release page on the website
so users can be informed of late-breaking issues with that particular
release. Does that sound reasonable?
andrew
Re: Release Notes
Posted by Rick Hillegas <Ri...@Sun.COM>.
Thanks for this heads-up, Kathey.
Kathey Marsden wrote:
> I hope I am not hijacking this thread but I have a question about the
> release notes.
> The practice of marking multiple fix versions in Jira means that the
> Jira release notes for 10.2 also include all of issues that are fixed
> in 10.2 and previous releases. For example if an issue was marked
> fixed in 10.1.3.1 and 10.2 it shows up in the 10.2 release notes, but
> really should not.
>
> At one point I had proposed marking the arliest release where the
> fix has been made and forward ported to all higher rev maintenance
> branches and the trunk but Dan voiced some concerns which need
> discussion still.
> http://www.nabble.com/Jira-field-definition-clarification-for-Derby-tf2024859.html#a5567827
>
>
> How will this be issue be mitigated for the 10.2 release notes?
>
> Thanks
>
> Kathey
>
>
>
>
>>
>
Re: Re: Release Notes
Posted by Andrew McIntyre <mc...@gmail.com>.
On 9/8/06, Daniel John Debrunner <dj...@apache.org> wrote:
> Kathey Marsden wrote:
>
> > I hope I am not hijacking this thread but I have a question about the
> > release notes.
> > The practice of marking multiple fix versions in Jira means that the
> > Jira release notes for 10.2 also include all of issues that are fixed
> > in 10.2 and previous releases. For example if an issue was marked fixed
> > in 10.1.3.1 and 10.2 it shows up in the 10.2 release notes, but really
> > should not.
>
> I assuming the issues you are refering to were fixed in the trunk after
> the 10.1 branch creation and were also fixed in the 10.1 branch.
>
> Can you explain why they should not show up in the 10.2 release notes? I
> guess that assumption confuses me.
Agreed. To clarify with an example, if a user was upgrading from
10.0.2.1 to 10.2.1.x, shouldn't an item that was fixed in 10.2 and
then backported to 10.1 still be in the release notes for 10.2? I
think users who skipped the 10.1 release would still be interested in
seeing that an issue was fixed in the release they are upgrading to.
andrew
Re: Release Notes
Posted by Rajesh Kartha <ka...@gmail.com>.
> One could also have sections for each 10.1 release:
>
>
>Bugs fixed in 10.2.1.4
>
>DERBY-xxx
>
>Bugs fixed in 10.1.3.1 and 10.2.1.4
>
>DERBY-yyy
>...
>
>Bugs fixed in 10.1.2.3 and 10.2
>
>
>Not sure how far back one would go though.
>
>Dan.
>
>
>
>
I do think it could be useful to have such a section where bugs ported
to branches are also mentioned. And to make
it simple just mention the branch to which the port happened (not the
point release, to avoid multiple sections).
for e.g:
10.2 release notes:
--------------------
- Bugs fixed in 10.2 only
- Bugs fixed in 10.2 and 10.1
10.3 release notes:
---------------------
- Bugs fixed in 10.3 only
- Bugs fixed in 10.3 and 10.2
- Bugs fixed in 10.3 and 10.2 and 10.1
The link to JIRA issue is either way provided in the release notes so
finding the version of a branch with the fix won't be hard for anyone.
My $0.02.
-Rajesh
Re: Meaning of Release Notes, was: Release Notes
Posted by 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
Posted by 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
Meaning of Release Notes, was: Release Notes
Posted by 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: Release Notes
Posted by Daniel John Debrunner <dj...@apache.org>.
Kathey Marsden wrote:
> Daniel John Debrunner wrote:
>
>> I'm not sure, I was just trying to understand your reasoning as to why
>> bugs fixed in the code line would be excluded. The last release seems a
>> reasonable approach.
>
> My reasoning for not marking multiple versions is that the fix ends up
> getting rolled up into the Jira release notes for the next release.
> DERBY-176 for example is marked fixed in 10.2.1.0 and 10.3.0.0 (Thanks
> for the fix BTW!)
>
> It is in the Jira 10.2.1.0 release notes
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=11187&styleName=Html&projectId=10594&Create=Create
>
> (That makes sense to me)
>
> It is in the 10.3.0.0 release notes
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12310800&styleName=Html&projectId=10594&Create=Create
>
> (That doesn't make sense to me)
>
> but it will not be in the 10.4.0.0 release notes presumably the fix
> implicit because it is fixed in 10.3, but of course it was really fixed
> in a previous release. But why should it be in the 10.3 release notes
> then?
That's a good question, and I think it's more related to how version
numbers are handled and release notes generated. The Jira tracking
system should contain the correct information, and then work from that,
not make Jira incorrect to suite the release notes process.
Here's my logic for the fix in. When I fix a bug in the trunk I execute
sysinfo to see what version is says. So today for DERBY-1809 it says
10.3.0.0, so that's where it is fixed, and that's how I mark Jira.
Then if on Monday I merge it into the 10.2 trunk, I imagine sysinfo will
say 10.2.1.4 (?), so ideally that's what I will add as a fix in. Of
course the scheme fails a little because there is no fix in for 10.2.1.4.
I think also because this is an open-source project and anyone can build
off any codeline at any time for their own purposes, it makes sense for
Jira to be accurate, so they can look at what they have built and
determine the set of bugs fixed for them.
> My thought was that it should just be marked fixed 10.2.1.0 and then
> not show up in the 10.3 release notes at all.
How would we distinguish between a bug like that and one that has only
been fixed in 10.2.1.0?
> I just don't at all understand what the Jira release notes mean the way
> we work it now. I guess the main thing that we document what our
> release notes mean. If we use some other format and the Jira release
> note mechinism doesn't mean anything to us, then we should probably make
> that clear somewhere too.
Agreed,
Dan.
Re: Re: Release Notes
Posted by Andrew McIntyre <mc...@gmail.com>.
On 9/8/06, Kathey Marsden <km...@sbcglobal.net> wrote:
>
> My reasoning for not marking multiple versions is that the fix ends up
> getting rolled up into the Jira release notes for the next release.
> DERBY-176 for example is marked fixed in 10.2.1.0 and 10.3.0.0 (Thanks
> for the fix BTW!)
>
> It is in the Jira 10.2.1.0 release notes
> It is in the 10.3.0.0 release notes
> but it will not be in the 10.4.0.0 release notes presumably the fix
> implicit because it is fixed in 10.3, but of course it was really fixed
> in a previous release. But why should it be in the 10.3 release notes
> then?
>
> My thought was that it should just be marked fixed 10.2.1.0 and then
> not show up in the 10.3 release notes at all.
There's two problems that I see. One is that releases are not really
sequential on a time scale or even guaranteed to happen. A fix that
was made in 10.2 and merged to 10.1.4 will almost certainly be
released in 10.2 before 10.1.4. Wouldn't it make sense for 10.2 to
document the behavior, especially if it needs a proper release note?
In that case, it should really show up on JIRA queries for 10.2 issues
with the release notes check box. And what if 10.1.4 is never
released? If it is only documented as being fixed in 10.1.4 it will
never be seen in a set of released release notes.
The other problem that I could see is that the fix for the issue in
10.2 may not be the same fix that goes into 10.1 for various reasons,
because 10.2 may have changed significantly in the area of the fix and
so the fix may be implemented differenty, and it might require
different release note in 10.1 because the fixes are different. Having
it properly documented in both seems like a good idea.
That's why I tend to view Fix In in JIRA as datapoints that document
where - what branches - activity around the issue occurred, not when,
and why I think it would be advantageous in some circumstances to be
documented in more than one release.
andrew
Re: Release Notes
Posted by Kathey Marsden <km...@sbcglobal.net>.
Daniel John Debrunner wrote:
>I'm not sure, I was just trying to understand your reasoning as to why
>bugs fixed in the code line would be excluded. The last release seems a
>reasonable approach.
>
My reasoning for not marking multiple versions is that the fix ends up
getting rolled up into the Jira release notes for the next release.
DERBY-176 for example is marked fixed in 10.2.1.0 and 10.3.0.0 (Thanks
for the fix BTW!)
It is in the Jira 10.2.1.0 release notes
https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=11187&styleName=Html&projectId=10594&Create=Create
(That makes sense to me)
It is in the 10.3.0.0 release notes
https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12310800&styleName=Html&projectId=10594&Create=Create
(That doesn't make sense to me)
but it will not be in the 10.4.0.0 release notes presumably the fix
implicit because it is fixed in 10.3, but of course it was really fixed
in a previous release. But why should it be in the 10.3 release notes
then?
My thought was that it should just be marked fixed 10.2.1.0 and then
not show up in the 10.3 release notes at all.
I just don't at all understand what the Jira release notes mean the way
we work it now. I guess the main thing that we document what our
release notes mean. If we use some other format and the Jira release
note mechinism doesn't mean anything to us, then we should probably make
that clear somewhere too.
Kathey
Re: Release Notes
Posted by Daniel John Debrunner <dj...@apache.org>.
Kathey Marsden wrote:
> Daniel John Debrunner wrote:
>
>> Kathey Marsden wrote:
>>
>>
>>
>>> I hope I am not hijacking this thread but I have a question about the
>>> release notes.
>>> The practice of marking multiple fix versions in Jira means that the
>>> Jira release notes for 10.2 also include all of issues that are fixed
>>> in 10.2 and previous releases. For example if an issue was marked fixed
>>> in 10.1.3.1 and 10.2 it shows up in the 10.2 release notes, but really
>>> should not.
>>>
>>
>>
>> I assuming the issues you are refering to were fixed in the trunk after
>> the 10.1 branch creation and were also fixed in the 10.1 branch.
>>
>> Can you explain why they should not show up in the 10.2 release notes? I
>> guess that assumption confuses me.
>>
>>
>>
> I was assuming that what is in the release notes is everything that has
> been fixed since the last release, in our case
> case since since 10.1.3.1.
> You think it should be everything since the 10.1 branch originally
> branched? That doesn't seem that helpful to me as that is not even on a
> release boundary, but does seem to match our current process.
I'm not sure, I was just trying to understand your reasoning as to why
bugs fixed in the code line would be excluded. The last release seems a
reasonable approach. One could also have sections for each 10.1 release:
Bugs fixed in 10.2.1.4
DERBY-xxx
Bugs fixed in 10.1.3.1 and 10.2.1.4
DERBY-yyy
...
Bugs fixed in 10.1.2.3 and 10.2
Not sure how far back one would go though.
Dan.
Re: Release Notes
Posted by Kathey Marsden <km...@sbcglobal.net>.
Kathey Marsden wrote:
> That doesn't seem that helpful to me
Actually the current way is fine if it makes sense to everyone. No
need to justify for me.
Kathey
Re: Release Notes
Posted by Kathey Marsden <km...@sbcglobal.net>.
Daniel John Debrunner wrote:
>Kathey Marsden wrote:
>
>
>
>>I hope I am not hijacking this thread but I have a question about the
>>release notes.
>>The practice of marking multiple fix versions in Jira means that the
>>Jira release notes for 10.2 also include all of issues that are fixed
>>in 10.2 and previous releases. For example if an issue was marked fixed
>>in 10.1.3.1 and 10.2 it shows up in the 10.2 release notes, but really
>>should not.
>>
>>
>
>I assuming the issues you are refering to were fixed in the trunk after
>the 10.1 branch creation and were also fixed in the 10.1 branch.
>
>Can you explain why they should not show up in the 10.2 release notes? I
>guess that assumption confuses me.
>
>
>
I was assuming that what is in the release notes is everything that has
been fixed since the last release, in our case
case since since 10.1.3.1.
You think it should be everything since the 10.1 branch originally
branched? That doesn't seem that helpful to me as that is not even on a
release boundary, but does seem to match our current process.
Kathey
Re: Release Notes
Posted by Daniel John Debrunner <dj...@apache.org>.
Kathey Marsden wrote:
> I hope I am not hijacking this thread but I have a question about the
> release notes.
> The practice of marking multiple fix versions in Jira means that the
> Jira release notes for 10.2 also include all of issues that are fixed
> in 10.2 and previous releases. For example if an issue was marked fixed
> in 10.1.3.1 and 10.2 it shows up in the 10.2 release notes, but really
> should not.
I assuming the issues you are refering to were fixed in the trunk after
the 10.1 branch creation and were also fixed in the 10.1 branch.
Can you explain why they should not show up in the 10.2 release notes? I
guess that assumption confuses me.
Thanks,
Dan.
Re: Release Notes
Posted by Kathey Marsden <km...@sbcglobal.net>.
I hope I am not hijacking this thread but I have a question about the
release notes.
The practice of marking multiple fix versions in Jira means that the
Jira release notes for 10.2 also include all of issues that are fixed
in 10.2 and previous releases. For example if an issue was marked fixed
in 10.1.3.1 and 10.2 it shows up in the 10.2 release notes, but really
should not.
At one point I had proposed marking the arliest release where the fix
has been made and forward ported to all higher rev maintenance
branches and the trunk but Dan voiced some concerns which need
discussion still.
http://www.nabble.com/Jira-field-definition-clarification-for-Derby-tf2024859.html#a5567827
How will this be issue be mitigated for the 10.2 release notes?
Thanks
Kathey
>
Re: Release Notes
Posted by Rick Hillegas <Ri...@Sun.COM>.
I think this is reasonable.
Regards,
-Rick
Andrew McIntyre wrote:
> On 8/24/06, Daniel John Debrunner <dj...@apache.org> wrote:
>
>>
>> Does that mean the downloaded packages have no release notes? So if a
>> release is made with known bugs, the only way to find that out is to go
>> to the Apache Derby site and find the release notes there?
>>
>> This seems like an issue, it's typically to have this kind of
>> information with the download, not separate. It's also based upon an
>> assumption that internet access is easy, which is not true for all of
>> the world. People may be getting Derby from CD/DVDs or bundled within
>> other applications. Assuming there's an easy path back to the apacche
>> site seems wrong.
>
>
> Agreed. 10.1.3.1 was the first release where issues that affect
> user-visible behavior had proper release notes and were documented
> before the release happened. I fear that I set a bad precedent there.
>
> I think that for 10.2 (and any other releases going forward, including
> a possible 10.1.4 release), that any issues that are known and
> documented at the time of the release should be documented in a
> release notes file at the top of the installation tree in all of the
> distributions, along with a pointer to the release page on the website
> so users can be informed of late-breaking issues with that particular
> release. Does that sound reasonable?
>
> andrew