/* Derby - Class org.apache.derbyBuild.ReleaseNotesGenerator Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */ package org.apache.derbyBuild; import java.io.*; import java.util.*; import org.w3c.dom.*; import java.net.URL; import org.apache.tools.ant.BuildException; /** *

* This tool generates Release Notes for a Derby release. See the USAGE * constant for details on how to run this tool standalone. It is recommended * that you freshly regenerate your BUG_LIST just before you run this tool. *

* *

* The tool is designed to be run from Derby's ant build scripts. The build * script will integrate the various steps of generating the release notes into * a single ant target. This includes generating the issue list by querying * the Apache JIRA instance. For this reason, the properties below must be * specified when invoking the ant target. You can specify them in * ant.properties, or on the command line.
* To run under ant, do the following: *

* * * Running the ant target successfully requires a working Internet connection * to the Apache JIRA instance, as well as a valid JIRA username/password and * the id of an existing JIRA filter. *

*

For more information on this tool, please see the JIRAs which introduced it: *

*

*/ public class ReleaseNotesGenerator extends GeneratorBase { ///////////////////////////////////////////////////////////////////////// // // CONSTANTS // ///////////////////////////////////////////////////////////////////////// private static final String USAGE = "Usage:\n" + "\n" + " java org.apache.derbyBuild.ReleaseNotesGenerator SUMMARY BUG_LIST OUTPUT_PAMPHLET\n" + "\n" + " where\n" + " SUMMARY Summary, a filled-in copy of releaseSummaryTemplate.xml.\n" + " BUG_LIST A report of issues addressed by this release, generated by the Derby JIRA SOAP client.\n" + " OUTPUT_PAMPHLET The output file to generate, typically RELEASE-NOTES.html.\n" + "\n" + "The ReleaseNoteGenerator attempts to connect to issues.apache.org in\n" + "order to read the detailed release notes that have been clipped to\n" + "individual JIRAs. Before running this program, make sure that you can\n" + "ping issues.apache.org.\n" + "\n" + "The ReleaseNoteGenerator assumes that the JIRA report contains\n" + "key, title, fix versions and attachment id elements for each Derby\n" + "issue. For each issue in with an attachment id element the\n" + "ReleaseNotesGenerator grabs the (latest) releaseNote.html file.\n" + "\n" + "For this reason, it is recommended that you freshly generate BUG_LIST\n" + "just before you run this tool.\n" ; // major sections private static final String OVERVIEW_SECTION = "Overview"; private static final String NEW_FEATURES_SECTION = "New Features"; private static final String BUG_FIXES_SECTION = "Bug Fixes"; private static final String ISSUES_SECTION = "Issues"; private static final String BUILD_ENVIRONMENT_SECTION = "Build Environment"; private static final String RELEASE_VERIFICATION_SECTION = "Verifying Releases"; // headlines private static final String ANT_HEADLINE = "Ant"; private static final String BRANCH_HEADLINE = "Branch"; private static final String COMPILER_HEADLINE = "Compiler"; private static final String JAVA6_HEADLINE = "Java 6"; private static final String JDK14_HEADLINE = "JDK 1.4"; private static final String MACHINE_HEADLINE = "Machine"; private static final String OSGI_HEADLINE = "OSGi"; // tags in summary xml private static final String SUM_ANT_VERSION = "antVersion"; private static final String SUM_COMPILER = "compilers"; private static final String SUM_JAVA6 = "java6"; private static final String SUM_JDK14 = "jdk1.4"; private static final String SUM_MACHINE = "machine"; private static final String SUM_NEW_FEATURES = "newFeatures"; private static final String SUM_OSGI = "osgi"; private static final String SUM_OVERVIEW = "overview"; private static final String SUM_RELEASE_VERIFICATION = "releaseVerification"; ///////////////////////////////////////////////////////////////////////// // // STATE // ///////////////////////////////////////////////////////////////////////// private ReleaseNoteReader releaseNoteReader = new ReleaseNoteReader(docBldr); // set on the command line or by ant private List missingReleaseNotes = new ArrayList(); public ReleaseNotesGenerator() throws Exception { } /** * Generate the release notes (for details on how to invoke this tool, see * the header comment on this class). * @param args command line arguments * @throws Exception */ public static void main(String[] args) throws Exception { ReleaseNotesGenerator me = new ReleaseNotesGenerator(); me._invokedByAnt = false; if (me.parseArgs(args)) { me.execute(); } else { me.println(USAGE); } } ///////////////////////////////////////////////////////////////////////// // // ANT Task BEHAVIOR // ///////////////////////////////////////////////////////////////////////// /** * This is Ant's entry point into this task. * @throws BuildException */ public void execute() throws BuildException { try { beginOutput(); buildOverview(); buildNewFeatures(); parseBugsList(); buildFixedBugsList(); buildReleaseNoteIssuesList(); buildEnvironment(); buildReleaseVerification(); replaceVariables(); printOutput(); printMissingReleaseNotes(); printErrors(); } catch (Throwable t) { t.printStackTrace(); throw new BuildException("Error running ReleaseNotesGenerator: " + t.getMessage(), t); } } ///////////////////////////////////////////////////////////////////////// // // MINIONS // ///////////////////////////////////////////////////////////////////////// /** * Start the RELEASE_NOTES html docment. */ private void beginOutput() throws Exception { String titleText = "Release Notes for Apache Derby " + releaseID; Element html = outputDoc.createElement(HTML); Element title = createTextElement(outputDoc, "title", titleText); Element body = outputDoc.createElement(BODY); // // Set language attribute for accessibility reasons. // See http://www.w3.org/TR/WCAG10/#gl-abbreviated-and-foreign // html.setAttribute( "lang", "en" ); outputDoc.appendChild(html); html.appendChild(title); html.appendChild(body); Element bannerBlock = createHeader(body, BANNER_LEVEL, titleText); buildDelta(bannerBlock); Element toc = createList(body); createSection(body, MAIN_SECTION_LEVEL, toc, OVERVIEW_SECTION, OVERVIEW_SECTION); createSection(body, MAIN_SECTION_LEVEL, toc, NEW_FEATURES_SECTION, NEW_FEATURES_SECTION); createSection(body, MAIN_SECTION_LEVEL, toc, BUG_FIXES_SECTION, BUG_FIXES_SECTION); createSection(body, MAIN_SECTION_LEVEL, toc, ISSUES_SECTION, ISSUES_SECTION); createSection(body, MAIN_SECTION_LEVEL, toc, BUILD_ENVIRONMENT_SECTION, BUILD_ENVIRONMENT_SECTION); createSection(body, MAIN_SECTION_LEVEL, toc, RELEASE_VERIFICATION_SECTION, RELEASE_VERIFICATION_SECTION); } ////////////////////////////////// // // Overview SECTION // ////////////////////////////////// /** * Build the Overview section. */ private void buildOverview() throws Exception { // copy the details out of the summary file into the overview section cloneChildren(summary.getElementByTagName(SUM_OVERVIEW), getSection(outputDoc, MAIN_SECTION_LEVEL, OVERVIEW_SECTION)); } ////////////////////////////////// // // New Features SECTION // ////////////////////////////////// /** * Build the New Features section. */ private void buildNewFeatures() throws Exception { // copy the details out of the summary file into the overview section cloneChildren(summary.getElementByTagName(SUM_NEW_FEATURES), getSection(outputDoc, MAIN_SECTION_LEVEL, NEW_FEATURES_SECTION)); } ////////////////////////////////// // // Bug List SECTION // ////////////////////////////////// private void parseBugsList() throws Exception { bugList = JiraIssue.createJiraIssueList(bugListFileName); // Parse the file for the release version and the previous version to // carry out sanity checks. BufferedReader in = new BufferedReader(new InputStreamReader( new FileInputStream(bugListFileName), "UTF-8")); String line; String prevVer = null; while ((line = in.readLine()) != null) { if (line.startsWith("// Previous release:")) { prevVer = line.split(":")[1].trim(); break; } } in.close(); if (prevVer == null) { System.out.println( "WARNING: Skipped previous release version sanity check."); } else if (!prevVer.equals(previousReleaseID)) { throw new IllegalStateException("previous release version " + "mismatch between releaseSummary.xml and bug list: " + previousReleaseID + " != " + prevVer); } } /** * Build the Bug List section. * @param gs state */ private void buildFixedBugsList() throws Exception { Element bugListSection = getSection(outputDoc, MAIN_SECTION_LEVEL, BUG_FIXES_SECTION ); String deltaStatement = "The following issues are addressed by Derby release " + releaseID + ". These issues are not addressed in the preceding " + previousReleaseID + " release."; addParagraph(bugListSection, deltaStatement); Element table = createTable (bugListSection, DEFAULT_TABLE_BORDER_WIDTH, new String[] { ISSUE_ID_HEADLINE, DESCRIPTION_HEADLINE }); // If we don't fix the width of the first column, the string // "DERBY-XXXX" is often broken up at the hyphen by some browsers. fixWidthOfFirstColumn(table); for ( Iterator i=bugList.iterator(); i.hasNext(); ) { JiraIssue issue = (JiraIssue) i.next(); //println("Fixed: "+ issue.getKey()); Element row = insertRow(table); Element linkColumn = insertColumn(row); Element descriptionColumn = insertColumn(row); Element hotlink = createLink(outputDoc, issue.getJiraAddress(), "DERBY-" + issue.getKey()); Text title = outputDoc.createTextNode(issue.getTitle()); linkColumn.appendChild(hotlink); descriptionColumn.appendChild(title); } } ////////////////////////////////// // // Issues SECTION // ////////////////////////////////// /** * Build the Issues section. */ private void buildReleaseNoteIssuesList() throws Exception { Element issuesSection = getSection(outputDoc, MAIN_SECTION_LEVEL, ISSUES_SECTION); String deltaStatement = "Compared with the previous release (" + previousReleaseID + "), Derby release " + releaseID + " introduces the following " + "new features " + "and incompatibilities. These merit your special attention."; addParagraph(issuesSection, deltaStatement); Element toc = createList(issuesSection); for (Iterator i=bugList.iterator(); i.hasNext(); ) { JiraIssue issue = (JiraIssue) i.next(); if (issue.hasReleaseNote()) { Node summaryText = null; Element details = null; try { URL url = new URL(issue.getReleaseNoteAddress()); InputStream is = url.openStream(); Document releaseNote = releaseNoteReader.getReleaseNote(is); summaryText = releaseNoteReader. getReleaseNoteSummary(releaseNote); details = releaseNoteReader. getReleaseNoteDetails(releaseNote); } catch (Throwable t) { errors.add(formatError("Unable to read or parse " + "release note for DERBY-" + issue.getKey(), t)); missingReleaseNotes.add(issue); continue; } String key = "Note for DERBY-" + issue.getKey(); //println("Release note: "+issue.getKey()+" - "+issue.getTitle()); Element paragraph = outputDoc.createElement(SPAN); paragraph.appendChild(outputDoc.createTextNode(key + ": ")); cloneChildren(summaryText, paragraph); insertLine(issuesSection); Element issueSection = createSection(issuesSection, ISSUE_DETAIL_LEVEL, toc, key, paragraph); cloneChildren(details, issueSection); } else if (issue.hasMissingReleaseNote()) { missingReleaseNotes.add(issue); } } } ////////////////////////////////// // // Build Environment SECTION // ////////////////////////////////// /** * Build the section describing the build environment. */ private void buildEnvironment() throws Exception { Element environmentSection = getSection(outputDoc, MAIN_SECTION_LEVEL, BUILD_ENVIRONMENT_SECTION ); String desc = "Derby release " + releaseID + " was built using the following environment:"; addParagraph(environmentSection, desc); Element list = createList(environmentSection); addHeadlinedItem(list, BRANCH_HEADLINE, "Source code came from the " + branch + " branch."); addHeadlinedItem(list, MACHINE_HEADLINE, summary.getTextByTagName(SUM_MACHINE)); addHeadlinedItem(list, ANT_HEADLINE, summary.getTextByTagName(SUM_ANT_VERSION)); addHeadlinedItem(list, COMPILER_HEADLINE, summary.getTextByTagName(SUM_COMPILER)); } ////////////////////////////////// // // Release Verification SECTION // ////////////////////////////////// /** * Build the Release Verification section. */ private void buildReleaseVerification() throws Exception { // copy the details out of the summary file into the release verification section cloneChildren(summary.getElementByTagName(SUM_RELEASE_VERIFICATION), getSection(outputDoc, MAIN_SECTION_LEVEL, RELEASE_VERIFICATION_SECTION)); } ////////////////////////////////// // // Print errors // ////////////////////////////////// /** * Print missing release notes */ private void printMissingReleaseNotes() throws Exception { if (missingReleaseNotes.isEmpty()) { return; } println("The following JIRA issues still need release notes or the " + "release notes provided are unreadable:"); for (Iterator i = missingReleaseNotes.iterator(); i.hasNext();) { JiraIssue issue = (JiraIssue) i.next(); println("\t" + issue.getKey() + "\t" + issue.getTitle()); } } ////////////////////////////////// // // ARGUMENT MINIONS // ////////////////////////////////// /** * Returns true if arguments parse successfully, false otherwise. */ private boolean parseArgs( String[] args ) throws Exception { if ( (args == null) || (args.length != 3) ) { return false; } int idx = 0; setSummaryFileName( args[ idx++ ] ); setBugListFileName( args[ idx++ ] ); setOutputFileName( args[ idx++ ] ); return true; } }