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

onlinern


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.
Comments or questions about this documentation? Contact us for support!