Release notes guidelines¶

Alternatives¶

We can add these recommendations to the Project Team guide, Infra manual, or Reno documentation.

Despite of the fact that these locations may fit (mainly because they are targeted at developers who create release notes for projects), there are strong arguments in favor of the Contributor guide:

• Project Team guide mostly discusses adjusting a project’s repo to use the release management tool rather than release notes writing style.
• Infra manual contains only general workflow of contributing to OpenStack source code repositories rather than specific use-cases such as the release notes creation.
• Reno documentation - though it is fully dedicated to the release notes creation process and shaped for the developers (our main intended audience), this is just a tool that can be replaced in future with another release notes management tool with its own documentation.

To sum up, Contributor guide still remains the best place to document release notes writing style guidelines for a number of reasons:

• Release notes are part of documentation
• Contributor guide`s intended audience is documentation contributors.

Assignee(s)¶

Primary assignee:

Olga Gusarenko <ogusarenko>

Work Items¶

The work items include the following:

• Create the overview of Release notes sections, what include where.
• Develop the writing style guidelines (release notes specific). These include:
  • Verb forms
  • Sentence structures for different types of release notes (New features, Bug fixes, etc.)
  • Links inclusion
• Make up bad examples of release notes and rework them. Present them in a form of bad -> improved examples for better illustration.
• Create Reno overview for general understanding of how things work there and why Community uses it to manage release notes.
• Create subsection (“Additional resources”) that lists links, where different pieces of release notes related information can be found, with brief descriptions.
• Cross-references:
  • Project Team guide
  • Reno documentation
  • Infra manual
• Inform OpenStack developers about the release notes guidelines when published:
  • Through the openstack-dev mailing list
  • Add the release note to documentation release notes for Newton