Table of Contents

Writing a Release Note

Good release notes are essential for users as they upgrade from one release to the next. Here's the procedure the Derby team uses to maintain useful release notes:

Some additional discussion regarding this process can be found in DERBY-2570.

Generating the Release Documentation

As part of producing a Derby release, the Release Manager creates RELEASE-NOTES.html, a web page which lives in the top directory of the branch codeline, next to the STATUS and CHANGES (up to version 10.3) files. This file ships with the release distributions and is also incorporated into the release download page on the Apache website. RELEASE-NOTES.html describes Derby's key capabilities and it summarizes the delta between the new release and some previous release--usually the last release produced by the community. The Issues section of RELEASE-NOTES.html includes the releaseNotes.html files which were attached to significant JIRAs.

To generate RELEASE-NOTES.html, the Release Manager first prepares the environment:

Note: For versions older than 10.8, these instructions may be different. For instance, at one point, generating the release notes involves using the class java/build/org/apache/derbyBuild/ReportParser. You needed to tweak this report because the shape of JIRA reports changes significantly between Derby releases. Fortunately, it is easy to write one of these parsers. See ReportParser$April_2010 as an example. For more information on producing this report for older branches, see the header comment on ReportParser$April_2010 on a branch that has it.

Then the Release Manager builds RELEASE-NOTES.html:

cd tools/release
ant -Drelnotes.src.reports=/path/to/report_directory 
    -Djira.user=<jira user name>
    -Djira.password=<password for that user>
    -Drelease.version=<version of the release in JIRA> (the JIRA filter ID to select those issues fixed in this release)

If you forget or have not set any of these settings, the release notes build will fail and you will be informed of which element you've missed.

By default the tool will use JQL to query JIRA. If the query fails for some reason, you can create you own custom filter in JIRA and point the tool at it by specifying To find the filter id, save the JIRA query as a filter, and then use the number following the id in the url window when the search has been issued.

You can also specify reportDisqualifications=true to see the issues that are disqualified. Currently, the only cause for a disqualification is that the fix for an issue has already been included in a previous version in the ancestry chain.

Depending on the size of the reports to handle, you may need to set ANT_OPTS, for instance to -Xms100m -Xmx200m. You may obviously also put relnotes.src.reports in if you prefer.

On Windows when you try to commit you may get the message <code> svn: Inconsistent line ending style </code>. To resolve this Kathey went into emacs and removed the ^M's. Myrna's solution was to install cygwin's dos2unix & unix2dos and use them in sequence. Lily's solution is run perl command "perl -p -e 's/\r$//' < RELEASE-NOTES.html > ~/RELEASE-NOTES.html

ReleaseNoteProcess (last edited 2016-10-02 18:54:50 by BryanPendleton)