Differences between revisions 8 and 9
Revision 8 as of 2008-03-18 09:47:39
Size: 3930
Editor: gmp-ea-fw-1
Comment:
Revision 9 as of 2008-03-18 10:02:54
Size: 4212
Editor: gmp-ea-fw-1
Comment:
Deletions are marked like this. Additions are marked like this.
Line 12: Line 12:
 * Before attaching your release note, make sure that the release processes can digest it. 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.
 * Before attaching your release note, make sure that the release processes can digest it. Run the lint tool, [https://svn.apache.org/repos/asf/db/derby/code/trunk/java/build/org/apache/derbyBuild/ReleaseNoteReader.java 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.
Line 19: Line 22:
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 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. 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` 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.
Line 21: Line 24:
To generate RELEASE-NOTES.html, the Release Manager first prepares the environment: To generate `RELEASE-NOTES.html`, the Release Manager first prepares the environment:
Line 23: Line 26:
 * '''Build''' - Builds the branch codeline in order to compile the ReleaseNotesGenerator program.  * '''Build''' - Builds the branch codeline in order to compile the [https://svn.apache.org/repos/asf/db/derby/code/trunk/java/build/org/apache/derbyBuild/ReleaseNotesGenerator.java ReleaseNotesGenerator] program.
Line 26: Line 29:
   * fixedBugsList.xml - This is the list of issues addressed by the release
   * releaseNotesList.xml - This is the list of issues bearing detailed releaseNotes.html explanations.
 To generate these two files 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=<release candidate> and resolution=fixed and type=bug. For `releaseNotesList.xml` you also need to check release note checkbox.
 After running the search in Jira the you will see a link called "XML" above the search results. In some browsers you can then right-click this link a select 'Save link as..." from the resulting menu. Make sure you change the name (to `fixedBugsList.xml` or `releaseNotesList.xml` as appropriate), and save it in the location pointed to by `relnotes.src.reports` as described below.
   * `fixedBugsList.xml` - This is the list of issues addressed by the release
   * `releaseNotesList.xml` - This is the list of issues bearing detailed releaseNotes.html explanations.
 To generate these two files 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 `releaseNotesList.xml` you also need to check the release note checkbox.
 After running the search in Jira the you will see a link called "XML" above the search results. 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` or `releaseNotesList.xml` as appropriate), and save it in the location pointed to by `relnotes.src.reports` as described below.

Table of Contents TableOfContents(3)

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:

}}}

  • 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 [https://issues.apache.org/jira/browse/DERBY-2570 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 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:

  • Build - Builds the branch codeline in order to compile the [https://svn.apache.org/repos/asf/db/derby/code/trunk/java/build/org/apache/derbyBuild/ReleaseNotesGenerator.java 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 two xml JIRA reports:

    • fixedBugsList.xml - This is the list of issues addressed by the release

    • releaseNotesList.xml - This is the list of issues bearing detailed releaseNotes.html explanations.

    To generate these two files 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 releaseNotesList.xml you also need to check the release note checkbox. After running the search in Jira the you will see a link called "XML" above the search results. 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 or releaseNotesList.xml as appropriate), and save it in the location pointed to by relnotes.src.reports as described below.

Then the Release Manager builds RELEASE-NOTES.html:

  • relnotes.src.reports - In ant.properties, this variable should point at the directory which holds the two xml JIRA reports.

  • cd - Change directory to tools/release.

  • ant - Run ant like so: "ant genrelnotes"

    • Depending on the size of the reports to handle, you may need to set ANT_OPTS, for instance to -Xms100m -Xmx200m

Please note that the Release Manager should run the JIRA reports 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.

ReleaseNoteProcess (last edited 2018-03-24 22:43:44 by RichardHillegas)