htmlrn

Release Note Generation Steps

On a high level, you first need to select from JIRA all the issues that are relevant to the release you are documenting; then ensure that all the issues that need to be documented have the Release Note field populated; and, finally, use the Release Note View to compile the Release Note entry.

To move the content from the Release Note View to an HTML file, you then manually copy the HTML source of the generated Release Note entry and Known Issues section and paste them into an existing RN file for your component. You need to add a release row in the Table of Contents section, including the information that is not available from JIRA (such as, Operating Systems for a given release).

Prerequisites:

1. The Release Note file in HTML format must exist for the component.

Gathering Your Content in JIRA

To select relevant issues from JIRA:

1. Select your project in JIRA.
2. Under Summary in the left pane, select Issues, and then click All Issues.
3. On the Issue Navigator page, under Filters, select a correct filter.
   • If a filter for this particular release is defined, select it and proceed to Step 4.
   • If a filter is defined for a previous release of the product, select it, modify it appropriately, save it (or Save As), and proceed to Step 4.
   • If no filter has yet been created for a particular component release, select All Issues and build a new filter to gather all applicable features, fixes, and open issues. You can save the filter and reuse/modify it later for the same/new release of the same component. You can also share the filter with your team or ask Project Managers and/or Development Managers to share their filters with you.
     
   JIRA Filtering capabilities enable you to select the issues that are considered for Release Notes, by various criteria: type (Defects, New Features, etc.); priority (Blocker, Critical, Major, etc.); status (Open, Closed, etc.); version (Affects Version/s, Fix Version/s); time (range of dates when issues were Created or Resolved); or content of a particular field ("Release Note" field is not empty, for example). Recommended filtering settings depend on your use case. See the section on Sample Filters for guidelines.
4. Review the issues that were selected from JIRA and are now displayed on the Issue Navigator page. Check that they have Release Note information.
   
   The Release Note field must be populated for an issue to appear in the Release Note View. If an issue must be included in the RN, but is missing a Release Note field, work with your team to edit the issue and add information to the Release Note field.
   
   Note: You can modify the appearance of your Issue Navigator page in JIRA so that the Release Note field is included among the visible columns. To do so, on the Issue Navigator page, click the Columns icon in the right top corner and search for the Release Note column. Select the Release Notes column to add it to the list configuration either as a default view or particularly for this filter. Drag and drop the column headings to change the order of appearance, if necessary.
5. Open the Export menu that you can access from the Export icon at the right top corner.
6. Select Release Note View.
   
   Tip: Right-click the view name (Release Note View) to see a command to open the view in a new tab or a new window. Otherwise, the Release Note View will replace the list of issues in your browser, and you’ll have to use the Back button if you need to return to the issues list on the Issue Navigator page.
7. In the Release Note View that opens, verify that issues are placed in correct sections.
   
   Note: Do not fill parameters in the top section of the Release Note View just yet.
   
   For wiki Release Notes, check the tabs in the Selected Issues section:
   • Improvements tab, for resolved Epics, New Features, and Improvements.
   • Corrections tab, for resolved Defects and Tasks.
   • Known Issues tab, for open Defects and Tasks.
     
   For legacy (HTML) Release Notes, check the Release Note Preview:
   • New in This Release section, for resolved Epics, New Features, and Improvements.
   • Corrections and Modifications section, for resolved Defects and Tasks.
   • Known Issues and Recommendations section, for open Defects and Tasks.
8. Verify that the wording is correct for each issue. To edit the descriptions, choose one of these three methods:
   • (Recommended) To ensure that the latest wording is in JIRA, return to Issue Navigator in JIRA and edit the wording in the Release Note field for a particular issue. Then, repeat Steps 5 through 7.
   • To change an issue description only for the generated Release Note, update the text in the Selected Issues section of the Release Note View. (See also the Version Check section.)
   • Otherwise, plan on correcting the wording in the Release Note draft when you are revising it in wiki or, for legacy HTML Release Notes, in your Editing tool.
   Important

   Keep in mind that wiki RN generation overwrites the content of the DRAFT 7-digit release page (such as, 8.5.100.03) when you generate the same RN draft multiple times. Capturing the latest wording in JIRA ensures that you don't lose any revisions that you made in wiki if you have to generate a new draft for the same 7-digit release. Note that you can always trace your in-wiki edits through the history tab on the 7-digit release page.
9. When the content is finalized and you are ready to transfer it to the Release Note draft, fill out or update all fields in the form in the Release Note Generator (the top section of the Release Note View).

Moving Content from JIRA to HTML

1. Click Refresh Preview to update the Preview section and verify that everything looks correct.
2. Click the Generate HTML Code button.
3. Copy the source code of the release entry from the Release Note Entry HTML box and paste this content into the Releases section within the Release Note HTML file for your component.
4. Copy the source code of the known issues from the Known Issues and Recommendations HTML box, if applicable, and paste this content into the Known Issues and Recommendations section within the Release Note HTML file. Change the order of the new items, if necessary.
5. In the Release Note HTML file, update the Contents table to include the newly added release entry, marking the operating systems that are applicable to this particular release.
6. Revise, edit, and format any descriptions, if you have not updated the descriptions directly in JIRA.

Release Note Review

For HTML Release Notes (8.1 and prior releases, as well as some components in 8.5 release), use the usual review process that works for your team. It is recommended that you upload the review drafts in your product’s folder on the Tech Pubs Review site in Alfresco and send out the link, rather than sending an attachment. This way, your reviewers can always find an up-to-date version in the same location.