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:

Then the Release Manager builds RELEASE-NOTES.html:

{{{cd tools/release ant -Drelnotes.src.reports=/path/to/report_directory genrelnotes}}}

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.

Please note that the Release Manager should run the JIRA report to generate fixedBugsList.xml freshly just before typing ant genrelnotes. The release manager may need to re-tweak the custom implementation of ReportParser too. This is because, during the release period, new issues may be fixed and included in the release and the text for individual release notes may be improved. Stale reports overlook the new issues and improved notes.

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 jar up RELEASE-NOTES.html, ftp to a linux machine, run dos2unix, then unix2dos on the Release notes (i.e., saving with a different name each time), jar the release notes back up, ftp back to windows, then commit will work.