Release Notes Guidelines

Initial Major Version Release

For each major version-specific release note file that you create, observe the following guidelines:

• Use one of the following formats for the title of the release note:

  Format	Example
  If the release has a version number, use that in the title.	.. _opsmgr-server-4.0.13: |onprem| Server 4.0.13 ~~~~~~~~~~~~~~~~~~~~~~ *Released on 2019-07-04* - Removing whitelist from Admin (General > Users) now possible. Displays error message when Authentication expires - **Agent Upgrades:** :ref:`automation-5.4.20.5541`, :ref:`backup-6.8.7.1024`
  If the release does not have a version number, use the API contract version and date.	API | contract version | updates, January 07, 2017
  If you are documenting a named or initial release, indicate the initial release in the title. You can precede release with a type, such as EA or UA.	API |contract version | release, September 14, 2017 API |contract version | EA release, September 14, 2017

• Use the following main sections in the release notes:

  • What's new

  • Resolved issues

  • Known issues

  • Documentation changes

  Note

  Anything previously labeled as "enhancements" can be included either in "What's new" or "Resolved issues" as appropriate.

• Include the "What's new," "Resolved issues," and "Known issues" sections in every RN file, even if you have no content for one of those sections. If one of these sections has no content for a release, use the |no changes| variable for the body text. This variable inserts the boilerplate text "None for this release." For example:

  Known issues
  ````````````
  ``|no changes|``

• Include the "Documentation changes" section only if you have significant content changes, such as adding an extended example, a tutorial, or new content. If you have no significant content changes for a release, omit that section entirely.

• Order your RN files from latest to earliest, so that the latest is always "on top." For example, the release notes for version 1.1 should precede the release notes for version 1.0 in the hierarchy.

Formatting

• Use sentence-style capitalization for all headings, including the title of the file (see the examples in the preceding section). The only exception to this rule is the high-level title of the release notes section, which is Release Notes.

• If a section has several items, for example there are several resolved issues to document, provide the descriptions in a bullet list. You do not need to precede the bullet list with an introductory sentence, unless one is necessary for clarity.

• If you have only one item to document in a section, do not show it as a bullet item. Show it as regular text.

• Use the punctuation guidelines for lists at List Items.

• As needed, use the guidelines at Text Formatting.

Wording

You do not need to include an introductory paragraph for each file. The one that exists for the "Release Notes" section as a whole is sufficient. You can begin each file with the "What's new" heading. However, you can include an introductory paragraph if necessary—for example, if you want to state that the release notes correspond to a particular type of release, such as a Limited Availability release, or you need to introduce the first release of a major version.

If you refer to content in another part of the API document, provide a link to the specific section.

Use the following guideline when creating items in each section:

Editing Existing Release Notes

In cases where existing release notes were not accurate at the time of publication, change the content to make it accurate. You can make the following types of changes:

• Fix typos

• Correct links that were wrong at the time of publication

• Correct incorrect statements to reflect what was correct at the time of publication