Differences between revisions 19 and 20
Revision 19 as of 2010-10-11 08:43:23
Size: 5068
Editor: gmp-ea-fw-1b
Comment: fixed broken markup
Revision 20 as of 2011-09-06 22:52:53
Size: 5605
Comment:
Deletions are marked like this. Additions are marked like this.
Line 27: Line 27:
 * '''Install Maven''' - Install a recent version of Maven and add the bin directory to your path
Line 30: Line 31:
   * `fixedBugsList.xml` - This is the list of issues addressed by the release. To generate this file you need to use the appropriate search or filter in Jira. You will typically need to create a new filter for each release. The criteria for `fixedBugsList.xml` will be something like fixversion=<branch or all release candidate versions>, resolution=fixed and type=bug. For more information on producing this report, see the header comment on !ReportParser$April_2010. Save this report to disk. In some browsers you can then right-click this link and select "Save link as..." from the resulting menu. Make sure you change the name to `fixedBugsList.xml` and save it in the location pointed to by `relnotes.src.reports` as described below.
 * '''Tweak''' - You will need to write your own implementation of !ReportParser. That is 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.
   * `fixedBugsList.xml` - This is the list of issues addressed by the release. To generate this file you need to save a filter for the appropriate search in Jira. You will typically need to create a new filter for each release. The criteria for `fixedBugsList.xml` will be something like fixversion=<branch or all release candidate versions>, resolution=fixed and type=bug. Save this report to disk. In some browsers you can then right-click this link and select "Save link as..." from the resulting menu. Make sure you change the name to `fixedBugsList.xml` and save it in the location pointed to by `relnotes.src.reports` as described below.

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.
Line 37: Line 40:
ant -Drelnotes.src.reports=/path/to/report_directory genrelnotes 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>
    -Djira.filter.id=<id of the search filter>
   genrelnotes
Line 39: Line 47:

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.

To find the jira filter id, I saved the JIRA query as a filter, and then used the number following the id in the url window when the search was issued.
Line 42: Line 54:
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. Please note that the Release Manager should run the JIRA report to generate `fixedBugsList.xml` freshly just before typing `ant genrelnotes`. 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.
Line 44: Line 56:
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. Lily's solution is run perl command "perl -p -e 's/\r$//' < RELEASE-NOTES.html > ~/RELEASE-NOTES.html 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

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:

  • For JIRAs which need a release note, you should turn on the "Release Note Needed" flag and attach a file called releaseNote.html.

  • The template for releaseNote.html lives in tools/release/templates/releaseNote.html (svn repos).

  • Before attaching your release note, make sure that the release processes can digest it. Add classes and $ANT_HOME/lib/ant.jar to your classpath and run the lint tool, ReleaseNoteReader, on your note as follows:

    java org.apache.derbyBuild.ReleaseNoteReader RELEASE_NOTE_FILE
    where RELEASE_NOTE_FILE is the name of the file which holds your release note.
  • As you improve the wording of your release note, you simply attach a new version of releaseNote.html. The release documentation will include the last version of the release note.

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:

  • Install Maven - Install a recent version of Maven and add the bin directory to your path

  • Build - Builds the branch codeline in order to compile the ReleaseNotesGenerator program.

  • Summarize - Fills in a summary of the release. This involves filling in the top level releaseSummary.xml file, based on the instructions in its template file tools/release/templates/releaseSummaryTemplate.xml.

  • Report - Generates a JIRA report:

    • fixedBugsList.xml - This is the list of issues addressed by the release. To generate this file you need to save a filter for the appropriate search in Jira. You will typically need to create a new filter for each release. The criteria for fixedBugsList.xml will be something like fixversion=<branch or all release candidate versions>, resolution=fixed and type=bug. Save this report to disk. In some browsers you can then right-click this link and select "Save link as..." from the resulting menu. Make sure you change the name to fixedBugsList.xml and save it in the location pointed to by relnotes.src.reports as described below.

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>
    -Djira.filter.id=<id of the search filter>
   genrelnotes

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.

To find the jira filter id, I saved the JIRA query as a filter, and then used the number following the id in the url window when the search was issued.

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 ant.properties if you prefer.

Please note that the Release Manager should run the JIRA report to generate fixedBugsList.xml freshly just before typing ant genrelnotes. 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 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 2018-03-24 22:43:44 by RichardHillegas)