Revision as of 13:17, February 28, 2020 by Bgrenon (talk | contribs)
Jump to: navigation, search

Release Notes with JIRA Process

This document is part of the overall Release Note Process which is available in the Genesys Documentation Writer Guide.

This document focuses on the creation of Release Note (RN) drafts from JIRA (the Genesys bug-tracking system) to:

  • Documentation/RN wiki, in an automated way.
  • Legacy RN files in HTML format, in a semi-automated way.

Release Note with JIRA—Online Wiki Pages

Use the following instructions to create Release Note (RN) drafts from JIRA to online output format. Additionally, you can watch the video.


Release Note Generation Steps

At 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 wiki, you use the Wiki RN Extension that creates and/or updates pages in the wiki-based Release Note manual for your component. You need to supply information that is not available from JIRA (such as, Operating Systems for a given release) on special web forms.


Prerequisites:

  1. The Release Note manual for the component must exist on the Documentation wiki (docs.genesys.com) before you start the generation to wiki. Contact the Pubs RN Admin alias to create a Release Note manual for your component. Include a copy of, or a link to, the Packaging Specs.
  2. You must be logged in to docs.genesys.com for the generation to succeed.


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 Wiki

  1. If you haven’t already, log in to the Documentation site in a separate browser tab or window.
  2. In the Release Note View window, click Wiki Draft Generator under Choose a Release Note Format.
  3. In the Publish to Wiki section that appears, click the Submit button.
  4. In the RN Form window that appears, confirm or specify the following:
    • Component Release Note title
      Note: If your component does not appear in the list, contact the Technical Publications Wiki Admins alias to add the Release Note manual to the system.
    • Release number
    • Operating Systems
    • Date when Release Note is expected to be published
    Then, click Submit.
  5. On the Validate Known Issues form, make any adjustments to the wording or status of Known Issue items. By default, new JIRA wording is used for any issues that were previously documented in the wiki Release Note.
    The following color legend helps you to identify different issues:
    • Yellow--The issue already exists in the wiki RN, but either the wording or Version parameters changed since the last generation. Review the changes carefully.
    • Blue--The issue is brand-new for this wiki RN, so review the wording carefully.
    • Green--The issue already exists in the wiki RN, and it did not change since the last generation.
    Then, click Submit.

    As a result of this and the previous Steps, a new page for the release is added to the Release Note manual for the component; the Welcome page and, if necessary, the Known Issues page are updated with new release information.
  6. From the Special:RNForm page, click the links to navigate to the new and updated pages. Verify the generated content of the DRAFT pages, then click Edit at the top and Save each page. Make any editing and formatting adjustments as required, saving regularly.
  7. If necessary, update the TOC page.

    • If the TOC for your RN Manual looks correct on the left-hand side, going to the TOC page and saving it is optional. Because of a Ponydocs issue, the TOC page appears nearly empty after each new generation, which does not impact the appearance of the manual itself because the TOC code is preserved.
    • If the TOC appears to have extra or missing pages (for example, a 3-digit release page, such as 8.5.2, while your component only has 8.5.1 and 8.5.0 releases), edit the TOC page as follows:
    1. Select RN View Current TOC in the left-hand column.
    2. Select the Edit tab at top.
    3. Delete invalid topics from the TOC code and any empty lines following the topic. For the 8.5.2 release example, delete the line for the following topic: topic:component852
  8. When you are editing a newly created Component’s Release Note for the very first time, add the following information to the Welcome page:
    • Link to this Component’s Release Note for the prior release (for example, 8.1 HTML file), if applicable.
    • Documentation references for your particular product in the Additional Information section, preceding the generic list (that is, the SOE and any other System Guides).

After the draft is generated, make the Release Note available to the product team for review and follow the review/approval process.


Release Note Review

For online Release Notes (8.5 and later releases), use the same review process as for other wiki content. Note that your reviewers need permissions for the "RN" product rather than your typical product in order to see the draft versions of Release Note manual for your component.

  • If your reviewers have user accounts on the Documentation site, granting "Employees" permissions to their accounts should give them read access to RN DRAFT versions.


  • If your reviewers don’t have user accounts on the Documentation site, and if you don’t require your reviewers to submit comments in the wiki, a generic login account can be used for the purpose of RN review:
  • login name: RN_reviewer
  • password: genesys


What if the Release Number Changes?

If the release number of your release note changes, use the Modify Release Note feature to update your draft. The release number appears in the release note's URL and TOC. Changing the release number involves updating several pages, creating a new page, and deleting the old page. We added the "Modify Release Note" feature to simplify this process.

If you adjust the seven-digit release number, the "Modify Release Note" function makes the following changes in the DRAFT version only:

  1. Creates a new release note draft and copies over the existing content.
  2. Replaces all instances of the old seven-digit release number with the new number on the page.
  3. Updates the Available Releases table on the Welcome page.
  4. Deletes the old release note page.

If you adjust the publishing date, release type, or supported operating systems, the tool:

  1. Makes the requested changes on the draft release page.
  2. Makes the same changes in the Available Releases table on the Welcome page.
Warning
The tool does not update release numbers on the Known Issues page. After running the tool, you may need to update Fixed In and Found In numbers on the Known Issues page.

Using the Modify Release Note Feature

  1. Open your release note draft and click the Modify Release Note button.
    The Modify Release Note button.
  2. You should now see the Modify Release Note Draft form. From this form, you can adjust the release number, release type, release date, and/or supported OS of your release note.
  3. Click Modify to save your changes. If the release number matches the release number of an existing release note draft, you will be warned that you will overwrite the existing content.
  4. When the tool finishes the update, you will see a confirmation page with links to the updated overview page and your updated release note.



Release Note with JIRA—HTML Files


Use the following instructions to create Release Note (RN) drafts from JIRA to HTML output format.


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.



Sample Filters


This section describes the RN plug-in logic and covers use of JIRA filters for a few typical use cases, which you may need to adjust based on the way your team is using JIRA.

For comprehensive information about filtering and search capabilities that JIRA offers, see Atlassian Help

Note: The examples are intended to illustrate the syntax rather than to produce accurate results at any point in time. Because the status of JIRA issues changes continuously, the results of certain filter expressions may differ for the products used in the examples.

RN Plug-in Logic

Issue Placement

The table below illustrates how different JIRA issues are sorted into the three sections in a Release Note. Issues of the types that are not listed are not included into Release Note View.

Note: For any JIRA issue to appear in the generated RN, the issue must have a populated Release Note field.

A combination of the type and status determines the default placement of an issue in the generated RN.

RN Section Name JIRA Issue Type JIRA Issue Status
New In This Release Epic, Improvement, New Feature Closed, Code Done, Verified, Resolved
Corrections and Modifications Task, Defect Closed, Code Done, Resolved
Known Issues and Recommendations Task, Defect Open, In Progress, Reopened.

Resolved or Closed with Resolution: Will Not Fix

Hot Fixes

Hot Fixes Use Case 1: Patch Request

This use case assumes that a Hot Fix is tracked in JIRA by means of a Patch Request issue, and that all the software changes that are relevant to this Hot Fix are tracked in JIRA as Epics, Improvements, Defects, and Tasks and are linked to the Patch Request issue.

To create a filter, specify the following text in Advanced Search.

Syntax:

issue in linkedIssues(<JIRA#>)

where <JIRA#> is the JIRA issue number for the Patch Request.

Example:

issue in linkedIssues("SIP-14601")

This filter returns all JIRA issues that are currently linked to the Patch Request issue. (In the example, it is a Patch Request for SIP Server.)

The same filter can be defined for a Hot Fix that is created as a Story in JIRA, as long as all relevant issues are linked to the Story issue.

Note: If any Improvement issues are included in the Hot Fix (for example, a new configuration option), they will appear in the New in This Release section in the generated Release Note.

Hot Fixes Use Case 2: No Patch Request

This use case assumes that a Hot Fix is tracked in JIRA by means of an issue other than Patch Request, but that a specific release number is used for the Fix Version/s field of each issue that has been corrected in the Hot Fix.

To create a filter, specify the project and fixVersion parameter.

Syntax:

project = <project_name> AND fixVersion = "<version>"

Example 1:

project = SS AND fixVersion = "statserv_8.1.000.43"

Example 2:

project = ICON AND fixVersion = "8.1.100.35"

This filter returns all JIRA issues that are currently Fixed or Code Done in the specified release number.

Note: If the product indicator is omitted in a freeze version in JIRA (such as statserv_ in the example), you may receive issues from other projects in your list. If this happens, fine-tune the filter to exclude other projects.

Hot Fixes Use Case 3: New Known Issues

Typically, the number of Known Issues that are added to a Hot Fix Release Note is low, and the JIRA numbers for these issues are communicated by the team. To include these issues into the filter, specify the issue IDs at the end of the search expression.

Syntax:

OR Key = <JIRA#>

Example:

The Stat Server filter used in Use Case 2 changes as follows to account for two new open issues:

project = SS AND fixVersion = "statserv_8.1.000.43" OR Key = SS-5529 OR Key = SS-5584

This filter returns two open JIRA issues in addition to the issues fixed in statserv_8.1.000.43 release (as long as they are still have an Open status).

General Release

General Release Use Case 1: Genesys Project

This use case assumes that a General Release is tracked in JIRA by means of a Genesys Project issue, and that all the software changes that are relevant to this General Release are tracked in JIRA as New Features, Improvements, Defects, and Tasks and are linked to the Genesys Project issue.

To create a filter, specify the following text in Advanced Search.

Syntax:

issue in linkedIssues(<JIRA#>)

where <JIRA#> is the JIRA issue number for the Genesys Project.

Example:

issue in linkedIssues("GIM-7746")

This filter returns all JIRA issues that are currently linked to the Genesys Project issue. (In the example, it is the v813 Genesys Info Mart Genesys Project.)

General Release Use Case 2: No Genesys Project

This use case assumes that a General Release is tracked in JIRA by means other than a Genesys Project issue. For a project like that, you can search for relevant fixes by defining a component, a range of Fix Versions, and/or a range of Resolved dates in your filter.

This use case can apply to a JIRA Project that covers multiple software components, with each component requiring a separate Release Note. In this situation, you can modify the filter from General Release Use Case 1 to return only the issues that relevant for a particular component.

General Release Use Case 3: New Known Issues

At the time of a General Release, it makes sense to review all the outstanding issues at the product team level and assess their addition to the component’s Release Note as Known Issues and Recommendations.

All Open Issues

To create a filter for Known Issues, specify the project name, applicable issue types, and issue status (include issues in Code Done or Reopened status, so that they are not lost).

Syntax:

project = <project_name> AND resolution = Unresolved AND "Release Note" is not empty ORDER BY updated DESC

Example:

project = GIM AND resolution = Unresolved AND "Release Note" is not empty ORDER BY updated DESC

The above filter returns all open issues ("Unresolved") that have Release Note information.

Note: To see all the open issues, regardless of Release Note information, remove the AND "Release Note" is not empty parameter from the search expression.

Customer-Reported Issues

You can limit the issues to those that were reported by the customer by filtering on the Customer Related flag, as follows.

Syntax:

project = <project_name> AND resolution = Unresolved AND "Release Note" is not empty AND "Customer Related?" = Yes ORDER BY updated DESC

Example:

project = GIM AND resolution = Unresolved AND "Release Note" is not empty AND "Customer Related?" = Yes ORDER BY updated DESC

Priority Issues

Additionally, your team may decide to focus on blocking, critical, and major customer defects only, for the Release Note purposes.

Syntax:

project = <project_name> AND resolution = Unresolved AND "Release Note" is not empty AND priority in (Blocker, Critical, Major) AND "Customer Related?" = Yes ORDER BY updated DESC

Example:

project = GIM AND resolution = Unresolved AND "Release Note" is not empty AND priority in (Blocker, Critical, Major) AND "Customer Related?" = Yes ORDER BY updated DESC

Recently Opened Issues

You can further limit the issues to those that were opened recently by filtering on the time when the issues were created. Specify the number of days during which issues may have been opened in the recent past, or use the date of the last General Release as the starting point in this filter.

Syntax:

created >= "-<N>d"

Example:

project = "SIP Server" AND created >= "-30d" AND "Release Note" is not empty ORDER BY updated DESC

Syntax:

created >= "YYYY/MM/DD"

Example:

project = "SIP Server" AND created >= "2014/09/30" AND "Release Note" is not empty ORDER BY updated DESC

Combining Fixes and Known Issues

You can build complex filters by combining various parameters into a single search expression. Moreover, one filter can combine an expression that searches for fixed issues with an expression that searches for open issues. When you do that, be careful about the choice of operators and the order of parameters. For more information about filters, click Syntax Help when you are in the Advanced Search view.

Complex Filter Example

Examples in this section illustrate how complex filters work. Example 1 provides filtering by date for open (Unresolved) issues that have Release Note information in JIRA. Example 2 provides filtering for issues that are linked to a Patch Request. Example 3 combines Example 1 with Example 2. Note the order of the two expressions and the use of the operator OR in Example 3.

Syntax:

<Filter 1> OR <Filter 2>

Example 1:

project = "SIP Server" AND created >= "2014/09/30" AND resolution = Unresolved AND "Release Note" is not empty ORDER BY updated DESC

Example 2:

issue in linkedIssues("SIP-14601")

Example 3 (Combined):

project = "SIP Server" AND created >= "2014/09/30" AND resolution = Unresolved AND "Release Note" is not empty OR issue in linkedIssues("SIP-14601") ORDER BY updated DESC



Checking the Versions

Use the Version Check logic to adjust visibility and placement of issues in the generated RN for projects in which fixes are not necessarily included into a current release. This situation is typical for a Continuous Delivery model in which issues that are fixed in the next code branch are pulled from JIRA because of their type and status; however, they are not delivered until a future release. For such cases, the plug-in compares the Fix Version in JIRA against the Release Number you specify in the form.

  • If the Release Number is equal to, or is greater than, the Fix Version, the issue placement does not change.
  • If the Release Number is less than the Fix Version, you are given a choice whether to include the issue into the RN.
  1. To activate the Version Check logic, fill out the parameters in the top section of the Release Note View, including the release number.
  2. Click the Version Check button in the Issue Selection section.
  3. Review the updated list of issues on the three tabs:
    • On the Improvements tab, any New Features and Improvements with a Fix Version higher than the specified Release Number no longer appear.
    • On the Corrections tab, any Defects and Tasks with a Fix Version higher than the specified Release Number have the Include check box cleared. If a given issue needs to be included in the Corrections and Modifications, select the Include check box. If the issue needs to be included in the Known Issues section, click the Move to Known Issues button.
    • On the Known Issues tab, any Defects and Tasks with a Fix Version higher than the specified Release Number have the Fixed In field cleared.
In the Selected Issues section, you can modify the issue description or Found In and Fixed In version numbers, if necessary. Note, however, that these changes are not propagated back to JIRA issues.

Publishing Release Notes

For 8.1 and prior releases (and those 8.5 RNs that are not yet converted to wiki format), use the established publication process for Release Notes in HTML format.

For 8.5 and later releases, use the publication process described below for wiki Release Notes.

For both HTML and wiki Release Notes:

  • Pubs Editors must approve the format prior to publication.
  • The writer must publish a Release Note Freeze Form in XING, unless the RN is associated with v9.0 (formerly G-NINE) and has been decoupled from the IP.


Publishing a Release Note

The triggers for Release Note publication for General, Update, and Hot Fix releases are described in the overall Release Note Process.


To publish an online Release Note for a new release:

  1. Receive approval from the team (particularly, Development Manager and QA Manager) on the technical content of the Release Note page for the 7-digit release, Welcome page for the Component Release Note, and Known Issues page for the component.
  2. Receive a peer-edit and apply any copy-editing corrections to the pages.
  3. Receive a format approval from Pubs Editors.
  4. Make sure you are logged in to the Documentation wiki.
  5. On the DRAFT Release Note page for the 7-digit release, select the publish release note tab.
  6. On the Genesys Release Note Generator page that appears, confirm the publication of the 7-digit Release Note page. Click Publish Draft.
  7. The Genesys Release Note Generator: Publish Draft—Complete page appears. Here, right-click and Open in New Tab/Window the following links:
    1. The Release Note for the 7-digit release. On the page that opens, verify that the content was moved from the DRAFT version to the final RN Manual. Click Edit and Save the page.
    2. The Welcome page for the Component’s Release Note. On the page that opens, verify that the content was moved from the DRAFT version to the final RN Manual, including the link to the new 7-digit release. Click Edit and Save the page.
  8. If you made any manual changes to the TOC in the Draft version, they don’t carry over. Repeat the required TOC updates in the published version. For example, add or remove 3-digit release pages for 8.5.1, 8.5.2, etc. releases, if required.
  9. To publish Known Issues, go to the DRAFT Known Issues page and select the publish known issues tab.
    Note: Yes, the Known Issues page has to be explicitly published because publication of the 7-digit release page does not include Known Issues. This separation enables you to update Known Issues independently of a release.
  10. On the Genesys Release Note Generator page that appears, confirm the publication of the Known Issues page. Click Publish.
  11. The Genesys Release Note Generator: Publish Known Issues—Complete page appears. Here, right-click and Open in New Tab/Window the Known Issues link. On the page that opens, verify that the content was moved from the DRAFT to the final version. Click Edit and Save the page.

    12. Note: If you receive an error during the publication process, check whether the RN was published despite the error. To do so, navigate to the final version of your 7-digit release page by replacing the DRAFT version number with the final number (such as, 8.5.x) in the URL. If the page does not exist, contact the Pubs RN Admin alias to publish your RN manually.

Your wiki Release Note has been published.

After publishing the online, wiki Release Note, do the following:

  • Publish the Release Note freeze form in XING, unless the RN is associated with v9.0 (formerly G-NINE) and has been decoupled from the IP.
  • Verify that the Release Notes link from your product landing page on the Documentation site points to the Welcome page of the Component’s Release Note.

Updating a Previously Published Release Note

If you need to make any changes to a previously published Release Note, including an additional operating system or updated release type, always make the change in the DRAFT version of the Release Note first. Then follow the same process as for Publishing a Release Note.


Publishing/Updating Known Issues

If you need to make any changes to a previously published Known Issues page (including an additional issue, updated description, or Found In/Fixed In version), always make the change in the DRAFT version of the Known Issues page first. Then follow steps 8 through 10 of the process for Publishing a Release Note.


Q&A

This section lists frequently asked questions and some outstanding issues.

Q1: What is the process around updates to RN field for Closed issues?
A1: While it is a good practice to keep the final, approved wording for issues in JIRA, there is no automated process to achieve this currently. If you want to update the Release Note field after an issue is closed, you can do so manually.

Q2: How do I filter by resolution values?
A2: If necessary, you can use specific resolution values to include or exclude certain issues, by using the AND resolution = <resolution> parameter. Below are the JIRA values for this parameter.

Example:

project = GMS AND resolution = "Will Not Fix"

Below are the JIRA values for the resolution parameter as applicable to the Resolved and Closed status, respectively.

Resolved:

  • Fixed (system default)
  • SIT Pass
  • Will Not Fix
  • Duplicate
  • Not a Bug

Closed:

  • Fixed (system default)
  • Will Not Fix
  • Duplicate
  • Not a Bug

Q3: Are there any additional recommendations for filtering?
A3: If sample filters don’t satisfy your project needs, start building a filter in Basic mode. Once a basic filter is working, switch to Advanced Search if you want to add more complex parameter combinations to the filter. The Syntax Help icon (which looks like a question mark) in the Advanced filter view takes you to JIRA documentation regarding various search and filtering functions. Short video tutorials on the subjects are also available on the Atlassian site.

Q4: Can the RN Plug-in read the Component Name from JIRA?
A4: For most filters, the product name must be specified in the search expression that defines the filter. However, the component name is not necessarily the same as the product name, and the RN Plug-in does not retrieve the component name from each particular issue. It is the responsibility of the writer to check or enter the correct component name in the HTML Generator form. The Wiki Generator form allows you to quickly choose the component from a drop-down list—just start typing the first letters of the component’s name.

Q5: How does a writer track product issues to identify those issues that were documented as Known Issues in prior releases and are fixed now?
A5: It is recommended to copy the approved KI text back into the JIRA Release Note field, for future reference. After the issue is fixed, you need to update the Release Note field to describe the correction. During subsequent generations, the script compares the wording of a KI in the RN with the description of a new fix it gets from JIRA. You can choose to leave the old wording on the Known Issues page so that it is not overwritten with the description of the correction.

Q6: Does RN Plug-in populate the Found In version for Known Issues?
A6: Yes, as long as it is specified in JIRA. Be careful, however, in the cases when the Found In version is internal, as only publicly available version numbers are supposed to appear in the published RN.

Q7: Is General Release Use Case 2 (No Genesys Project) a valid use case?
A7: This use case is provided for completeness. We are monitoring the use of JIRA by different teams; and, if the use case is determined unnecessary, the information will be removed or replaced, as appropriate.

Q8: How do you order items in Issue Navigator so that the most recent issues appear first (or last) in Release Note View?
A8: The ORDER BY parameter can be used as the last parameter in a filter definition. Assuming that the lower values for issue numbers identify the oldest issues, the descending order for issues numbers can be defined with the following syntax:

ORDER BY KEY Desc

The syntax for making the oldest issues to appear at the top of the list is the same, with the last word replaced with Asc.

Q9: Is the new RN Plug-in something everyone needs to download/install on their computers?
A9: The Release Note Plug-in is available as part of JIRA, and there is no need to install it separately.

Q10: I do not see the RN field in the issue I’m working on. How can I find/add it?
A10: The Release Note field is not visible until some text is added to it. As long as the issue is of the correct type (for example, a defect), the Release Note field becomes available for input during the Create, Edit, Resolve, or Close operation. Once the text is added, the field and its content become visible in the issue view.

Q11: Can I use HTML tags to have more options with formatting RN text in wiki?
A11: Some HTML tags are allowed in MediaWiki, and our MediaWiki platform is most likely to support them. The JIRA RN plug-in is expected to pass the supported HTML code to the generated wiki RNs. If you need to use typical HTML formatting (such as lists or font treatment), you can code the format in the RN entry text in JIRA. Consult the official list of supported HTML tags: http://www.mediawiki.org/wiki/Help:Formatting#HTML_tags

Q12: What URL do I, as a writer, send to my reviewers?
A11: This is up to you and to the team, as long as you’re referring your reviewers to the DRAFT RN pages. If you want to ensure that the team checks all three pages (7-digit release page, Welcome page for the RN manual, and Known Issues page), you can list the three URLs separately in your review request. For the initial release, sending the URL for the Welcome page gets the reviewers into the right manual. For subsequent releases, most writers only send the URL for the new 7-digit release and most reviewers find their way to the Known Issues and Welcome pages.

Q13: How do I, as a writer, move my HTML Release Note to wiki?
A13: For 8.1 release, you can continue using HTML format for release notes until further notice. In fact, the JIRA Plug-in supports generation of HTML code and can still be helpful for RN updates in HTML. If the Release Note for your 8.5 component has already been published in HTML format, you need to select the time when to move it to the wiki. Do understand that a component’s Release Note for the same release family (such as 8.5.x) must not exist in two formats simultaneously. Thus, when you move to wiki, you are required to convert the existing HTML RN to wiki pages. When you contact the Release Notes Administrator with a request to create a new wiki Release Note to replace an existing HTML RN for your component, ask for any automation suggestions.

Q14: What if the release number of my wiki release note changes? Do I need to start over from JIRA?
A14: If the release number of your draft wiki release note changes, use the Update RN feature to update your release note. See What if the Release Number Changes? under the Online tab of the Release Notes with JIRA Process.

Comments or questions about this documentation? Contact us for support!