db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Oystein Grovlen - Sun Norway <Oystein.Grov...@Sun.COM>
Subject Re: 10.3 Release Notes
Date Tue, 10 Jul 2007 12:33:31 GMT
Myrna van Lunteren wrote:
 > One of the hardest and most time-consuming things in preparing the
 > release was creating the Release Notes.
 > We have the release notes generator...But it presumes xml reports to
 > have been magically created, and it does not have a mechanism to
 > identify the new features.

I acknowledge that making release notes are a time consuming task, and
making release notes will always be a compromise between effort and
quality. I guess the question we should ask is how can we get
sufficient accuracy without making the work too time-consuming.

In addition to the issues you raise, I feel that one major problem
with generated release notes is that the summaries for JIRA issues
often do say much about what have been fixed.  I guess there are two
alternatives we can try to improve that:
  1. Urge the responsible developer to make sure the summary is
     descriptive.
  2. Only include issues with specific release notes attached.  This
     means that one will require such release notes all for issues that
     should be mentioned in the release note, not just for issues with
     application impact.

Alternative 2 implies that the responsible developer for an issue will
also be given the responsibility to decide whether an issue should be
included in the release note or not.

Maybe we should make the rule that only issues with the release note
required field checked will be included in the release note.  This
would free the release manager from the burden of deciding what should
be part of the release note, at the risk of reduced quality due to
developers not marking their issues the way they are supposed to.

 > In past releases, we had the 'CHANGES' file, but because it seemed to
 > list the same bugs as the Release-Notes I removed it. This may have
 > been the wrong thing to do...(every apache project needs to log the
 > changes somehow).

The advantage of a CHANGES file is that not everything needs to be
included in the release note.  It gives more freedom to create a
release notes that is useful to Derby users.

 >
 > A big problem is also lack of standard usage in JIRA.
 > Take sub-tasks - include them or not? What if the master task is still
 > open because of 1 or 2 sub issues or tasks are still open? (e.g. 1478,
 > although that's an improvement, not a bug).
 > In other master issues, changes have gone in for both the master task
 > and the subtask. What to do?
 > Should issues get forced closed, with more work continuing in a
 > subsequent bug while work is still going on when changes *have* gone
 > in?
 > How about issues where there are links, rather than subtasks,
 > indicating one issue is 'part of' another; should the ones that are
 > 'part of' not go in the release notes?
 >
 > Another concern is our practice for 'affects'. Because it is not
 > required to annotate whether a bug is confirmed to exist or not in a
 > previous release, or, for that matter, to even annotate the 'affects'
 > at all, some bugs marked affects 10.3 might have been around before...
 > So, creating a list of only bugs that existed before and have been
 > fixed now, is particularly hard to compile in an automated way.

I think if it was well defined how release notes were generated, one
could give more responsibility to individual developers and make them
do the necessary work to make an issue appear in the release note.
(E.g., Developer: "The bug I fixed is not listed in the release note!"
Release Manager: "You need to mark it as affects 10.2 to make it show
up").

I think it would also help if the Release Manager, several times in
the weeks prior to a release generated the release note and posted it
on derby-dev and urged the developers to check that the issues they
have been working on is properly listed.

 >
 > Note, by the way, that Dan brought up a similar concern re the release
 > notes (DERBY-2840).
 >
 > Anyway, if we need another release round, I can modify the release notes.
 > Otherwise, I'm inclined to leave them as is...Is that OK?

I am not going to insist on anything, but I feel that a list of fixed
bugs that are automatically generated based on what affects earlier
releases would be much more useful (even if it may be less accurate)
than the current list.

 >
 > If we do change them, what *should* be in them, then?
 >
 > I gather:
 > - A section for 'new features' - without splitting into categories
 >    The ReleaseNotesGenerator needs to be adjusted for this new
 >    section

Yes, definitely.  For future releases, I suggest that we generate this
based on issues that are marked as new features and that has an
attached release note.  This release note should then describe the
implemented feature.  For this release, it seems that some new
features are marked improvement, instead.  I feel that any changes in
functionality or interfaces (small or large) should be marked as 'new
features'.

 > - A section for bug fixes - I assume only type bug and improvement?

I am not sure about improvements.  Many of them are code internal
issues (e.g., renaming of class, restructuring of code) which is not
very relevant to users.

 > With only those that do *not* have 'affects
 > 10.3.0.0/10.3.1.0/10.3.1.1'?

I think this should be "only those that *do* have affects 10.2
releases".  We do not want to leave out issues that are marked as both
affecting both 10.2 and 10.3.

 > Excluding any test issues, web site components...? Should build
 > issues be in?

Personally, I do not care for build issues.  Documentation issues
seems to be documented at a too detailed level.  I do not think users
care want to be informed about corrections of typos etc (at least not
through references to JIRA issues), but would like to know about new
"Documentation features" (e.g., a new manual, a new topic, a
significantly improved coverage of a topic).

 > - Reinstate the CHANGES file, which basically will be a listing of
 > *all* issues with fix in 10.3.* (at this time).

Sounds good.

On previous (closed-source) projects I have worked on, it has often
been an issue whether the release notes needs to be generated when the
release candidate is built or if we can edit them afterwards.
Generally, QA and Release Engineering did not like the idea of later
repackaging the release to include the release notes since it meant
that the delivered packages would not be the same as the one that
was tested.  Engineering, on the other hand, having fixed bugs etc
until the final deadline, would like to be able to use the test period
to work on the release notes.  Sometimes we solved this by putting the
release notes on the web instead of in the delivered packages, but I
guess we have already decided that we will not do it this way for
Derby.  This problem is even bigger with automatically generated
release notes since many developers, unless they generate them
themselves, will not look at the release notes until it is too late to
change them.

Thanks for all your work with this release,

-- 
Øystein

Mime
View raw message