Usage¶

Creating New Release Notes¶

The reno command line tool is used to create a new release note file in the correct format and with a unique name. The new subcommand combines a random suffix with a “slug” value to create the file with a unique name that is easy to identify again later.

$ reno new slug-goes-here
Created new notes file in releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml

Within OpenStack projects, reno is often run via tox instead of being installed globally. For example

$ tox -e venv -- reno new slug-goes-here
venv develop-inst-nodeps: /mnt/projects/release-notes-generation/reno
venv runtests: commands[0] | reno new slug-goes-here
Created new notes file in releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml
  venv: commands succeeded
  congratulations :)
$ git status
Untracked files:
  (use "git add <file>..." to include in what will be committed)

    releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml

The --edit option opens the new note in a text editor.

$ reno new slug-goes-here --edit
... Opens the editor set in the EDITOR environment variable, editing the new file ...
Created new notes file in releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml

By default, the new note is created under ./releasenotes/notes. The --rel-notes-dir command-line flag changes the parent directory (the notes subdirectory is always appended). It’s also possible to set a custom template to create notes (see Configuring Reno ).

Editing a Release Note¶

The note file is a YAML file with several sections. All of the text is interpreted as having reStructuredText formatting. The permitted sections are configurable (see below) but default to the following list:

prelude

General comments about the release. Prelude sections from all notes in a release are combined, in note order, to produce a single prelude introducing that release. This section is always included, regardless of what sections are configured.

features

A list of new major features in the release.

issues

A list of known issues in the release. For example, if a new driver is experimental or known to not work in some cases, it should be mentioned here.

upgrade

A list of upgrade notes in the release. For example, if a database schema alteration is needed.

deprecations

A list of features, APIs, configuration options to be deprecated in the release. Deprecations should not be used for something that is removed in the release, use upgrade section instead. Deprecation should allow time for users to make necessary changes for the removal to happen in a future release.

critical

A list of fixed critical bugs.

security

A list of fixed security issues.

fixes

A list of other fixed bugs.

other

Other notes that are important but do not fall into any of the given categories.

Any sections that would be blank should be left out of the note file entirely.

---
prelude: >
    Replace this text with content to appear at the
    top of the section for this release.
features:
  - List new features here, or remove this section.
issues:
  - List known issues here, or remove this section.
upgrade:
  - List upgrade notes here, or remove this section.
deprecations:
  - List deprecation notes here, or remove this section
critical:
  - Add critical notes here, or remove this section.
security:
  - Add security notes here, or remove this section.
fixes:
  - Add normal bug fixes here, or remove this section.
other:
  - Add other notes here, or remove this section.

---
prelude: |
  This paragraph will
  retain its newlines
  when the value is passed to the
  reStructuredText parser, which
  will then merge them into
  a single paragraph without
  breaks.

  | These
  | lines
  | are prefixed
  | with | so the reStructuredText
  | parser will retain
  | the line breaks.
features:
  This note is a simple string, and does not retain its
  formatting when it is rendered in HTML. rst markup here
  may break the YAML parser, since the string is not escaped.
fixes:
  - Use YAML lists to add multiple items to the same section.
  - Another fix could be listed here.
other:
  - |
    This bullet item includes a paragraph and a nested list,
    which works because the content of the YAML list item
    is an escaped string block with reStructuredText formatting.

    * list item 1
    * list item 2

    .. code-block:: text

      This example is also rendered
      correctly on multiple lines
      as a pre-formatted block.

Generating a Report¶

Run reno report <path-to-git-repository> to generate a report containing the release notes. The --branch argument can be used to generate a report for a specific branch (the default is the branch that is checked out). To limit the report to a subset of the available versions on the branch, use the --version option (it can be repeated).

Notes are output in the order they are found when scanning the git history of the branch using topological ordering. This is deterministic, but not necessarily predictable or mutable.

Checking Notes¶

Run reno lint <path-to-git-repository> to test the existing release notes files against some rules for catching common mistakes. The command exits with an error code if there are any mistakes, so it can be used in a build pipeline to force some correctness.

Configuring Reno¶

Reno looks for an optional config file, either config.yaml in the release notes directory or reno.yaml in the root directory. If the values in the configuration file do not apply to the command being run, they are ignored. For example, some reno commands take inputs controlling the branch, earliest revision, and other common parameters that control which notes are included in the output. Because they are commonly set options, a configuration file may be the most convenient way to manage the values consistently.

---
branch: master
earliest_version: 12.0.0
collapse_pre_releases: false
stop_at_branch_base: true
sections:
  # The prelude section is implicitly included.
  - [features, New Features]
  - [issues, Known Issues]
  - [upgrade, Upgrade Notes]
  - [api, API Changes]
  - [security, Security Issues]
  - [fixes, Bug Fixes]
# Change prelude_section_name to 'release_summary' from default value
# 'prelude'.
prelude_section_name: release_summary
template: |
          <template-used-to-create-new-notes>
          ...

Many of the settings in the configuration file can be overridden by using command-line switches. For example:

• --branch
• --earliest-version
• --collapse-pre-releases/--no-collapse-pre-releases
• --ignore-cache
• --stop-at-branch-base/--no-stop-at-branch-base

The following options are configurable:

notesdir

The notes subdirectory within the relnotesdir where the notes live.

Defaults to notes.

collapse_pre_releases

Should pre-release versions be merged into the final release of the same number (1.0.0.0a1 notes appear under 1.0.0).

Defaults to True.

stop_at_branch_base

Should the scanner stop at the base of a branch (True) or go ahead and scan the entire history (False)?

Defaults to True.

branch

The git branch to scan. If a stable branch is specified but does not exist, reno attempts to automatically convert that to an “end-of-life” tag. For example, origin/stable/liberty would be converted to liberty-eol.

Defaults to the “current” branch checked out.

earliest_version

The earliest version to be included. This is usually the lowest version number, and is meant to be the oldest version. If unset, all versions will be scanned.

Defaults to None.

template

The template used by reno new to create a note.

release_tag_re

The regex pattern used to match the repo tags representing a valid release version. The pattern is compiled with the verbose and unicode flags enabled.

Defaults to ((?:[\d.ab]|rc)+).

pre_release_tag_re

The regex pattern used to check if a valid release version tag is also a valid pre-release version. The pattern is compiled with the verbose and unicode flags enabled. The pattern must define a group called pre_release that matches the pre-release part of the tag and any separator, e.g for pre-release version 12.0.0.0rc1 the default RE pattern will identify .0rc1 as the value of the group ‘pre_release’.

Defaults to (?P<pre_release>\.\d+(?:[ab]|rc)+\d*)$.

branch_name_re

The pattern for names for branches that are relevant when scanning history to determine where to stop, to find the “base” of a branch. Other branches are ignored.

Defaults to stable/.+.

sections

The identifiers and names of permitted sections in the release notes, in the order in which the final report will be generated. A prelude section will always be automatically inserted before the first element of this list.

prelude_section_name

The name of the prelude section in the note template. Note that the value for this must be a single word, but can have underscores. The value is displayed in titlecase in the report after replacing underscores with spaces.

Defaults to prelude

ignore_null_merges

OpenStack used to use null-merges to bring final release tags from stable branches back into the master branch. This confuses the regular traversal because it makes that stable branch appear to be part of master and/or the later stable branch. This option allows us to ignore those.

When this option is set to True, any merge commits with no changes and in which the second or later parent is tagged are considered “null-merges” that bring the tag information into the current branch but nothing else.

Defaults to True.

ignore_notes

A list of filenames or UIDs for notes that should be ignored by the reno scanner. It is most useful to set this when a note is edited on the wrong branch, making it appear to be part of a release that it is not.

Warning

Setting the option in the main configuration file makes it apply to all branches. To ignore a note in the HTML build, use the ignore-notes parameter to the release-notes sphinx directive.

Debugging¶

The true location of formatting errors in release notes may be masked because of the way release notes are included into sphinx documents. To generate the release notes manually, so that they can be put into a sphinx document directly for debugging, use the report command.

$ reno report .

Within OpenStack¶

The OpenStack project maintains separate instructions for configuring the CI jobs and other project-specific settings used for reno. Refer to the Managing Release Notes section of the Project Team Guide for details.