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

The --from-template option allows you to use a pre-defined file and use that as the release note.

$ reno new slug-goes-here --from-template my-file.yaml
... Creates a release note using the provided file my-file.yaml ...
Created new notes file in releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml

Note

You can also combine the flags --edit and --from-template to create a release note from a specified file and immediately start an editor to modify the new file.

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.

Note File Syntax¶

Release notes may include embedded reStructuredText, including simple inline markup like emphasis and pre-formatted text as well as complex body structures such as nested lists and tables. To use these formatting features, the note must be escaped from the YAML parser.

The default template sets up the prelude section to use > so that line breaks in the text are removed. This escaping mechanism is not needed for the bullet items in the other sections of the template.

To escape the text of any section and retain the newlines, prefix the value with |. For example:

---
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.
fixes_command_line:
  - |
    This is a subsection. It requires setting `sections` in
    config with an entry underneath `['fixes', 'Bug Fixes']` like
    `['fixes_command_line', 'Command Line', 2]`. The `2` at the end
    indicates that the entry is a subsection header.
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.

See Examples for the rendered version of the note.

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¶

Warning

The lint command is deprecated and will be removed in a future release. Note validation is now performed automatically by the loader during all operations (such as reno report or Sphinx builds).

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.

Computing Next Release Version¶

Run reno -q semver-next to compute the next SemVer version number based on the types of release notes found since the last release.

Configuring Reno¶

Reno looks for an optional config file, checking in order:

config.yaml in the release notes directory (defaults to releasenotes/config.yaml)
reno.yaml in the root directory of the repository
A [tool.reno] table in pyproject.toml in the root directory of the repository

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.

Using YAML (reno.yaml or releasenotes/config.yaml):

---
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>
          ...
encoding: utf8

Using TOML (pyproject.toml):

[tool.reno]
branch = "master"
earliest_version = "12.0.0"
collapse_pre_releases = false
stop_at_branch_base = true
sections = [
  ["features", "New Features"],
  ["issues", "Known Issues"],
  ["upgrade", "Upgrade Notes"],
  ["api", "API Changes"],
  ["security", "Security Issues"],
  ["fixes", "Bug Fixes"],
]
prelude_section_name = "release_summary"
encoding = "utf8"

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:

add_release_date

Should the report include release date (True) based on the date of objects associated with the release tag.

Defaults to False

allow_subdirectories

Allow creating subdirectories under the notes subdirectory.

Defaults to False

branch

The git branch to scan. Defaults to the “current” branch checked out. 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 None

branch_name_prefix

The prefix to add to tags for closed branches to restore the old branch name to allow sorting to place the tag in the proper place in history. For example, OpenStack turns “mitaka-eol” into “stable/mitaka” by removing the “-eol” suffix via closed_branch_tag_re and setting the prefix to “stable/”.

Defaults to 'stable/'

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/.+'

branch_sort_prefix

The prefix to add to names of branches matched by branch_sort_re. This allows OpenStack branches to be sorted according to the current release naming scheme. Set to “stable/” in order to restore plain alphabetic ordering.

Defaults to 'stable/zzz'

branch_sort_re

By default branches are sorted alphabetically, except for branches matching this pattern, those will be sorted with branch_sort_prefix inserted in order to accomodate the way OpenStack stable branches are named and sorted.

Defaults to 'stable/([0-9].*)'

closed_branch_tag_re

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

Defaults to '(.+)-eo[lm]'

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

default_branch

The default git branch for the repository. This is the base branch that is treated as the root for other branches. By default this is master.

Defaults to 'master'

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

encoding

The character encoding to use when opening note files. If not specified it will be dependent on the system running reno (whatever ‘locale.getpreferredencoding()’ returns. This takes in a string name that will be passed to the encoding kwarg for open(), so any codec or alias from stdlib’s codec module is valid.

Defaults to None

ignore_notes

Note files to be ignored. It’s useful to be able to ignore a file if it is edited on the wrong branch. Notes should be specified by their filename or UID.

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.

Defaults to []

ignore_null_merges

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.

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.

Defaults to True

notesdir

The notes subdirectory within the relnotesdir where the notes live.

Defaults to 'notes'

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 pattern will identify ‘.0rc1’ as the value of the group ‘pre_release’.

Defaults to

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

prelude_section_name

The name of the prelude section in the note template. This allows users to rename the section to, for example, ‘release_summary’ or ‘project_wide_general_announcements’, which is displayed in titlecase in the report after replacing underscores with spaces.

Defaults to 'prelude'

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

((?:v?[\d.ab]|rc)+)  # digits, a, b, and rc cover regular and
                   # pre-releases

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.

You can optionally include a number from 1 to 3 at the end of the list to mark the entry as a subsection. By default, each section has the number 1, which represents a top-level section. Use 2 and 3 for subsections and subsubsections. For example, ['features', 'New Features', 1], ['features_command_line', 'Command Line', 2], and ['features_command_line_ios', 'iOS', 3]. The order of this option matters; define subsections right after their ancestor sections.

Warning: you should check that semver_major, semver_minor, and semver_patch includes the relevant section names, including subsections.

Defaults to [['features', 'New Features'], ['issues', 'Known Issues'], ['upgrade', 'Upgrade Notes'], ['deprecations', 'Deprecation Notes'], ['critical', 'Critical Issues'], ['security', 'Security Issues'], ['fixes', 'Bug Fixes'], ['other', 'Other Notes']]

semver_major

The sections that indicate release notes triggering major version updates for the next release, from X.Y.Z to X+1.0.0.

Defaults to ['upgrade']

semver_minor

The sections that indicate release notes triggering minor version updates for the next release, from X.Y.Z to X.Y+1.0.

Defaults to ['features']

semver_patch

The sections that indicate release notes triggering patch version updates for the next release, from X.Y.Z to X.Y.Z+1.

Defaults to ['fixes']

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

strict

Treat note validation errors (such as unrecognized sections, invalid note structures, or duplicate unique IDs) as hard errors. By default, this is False and warnings are logged instead.

Defaults to False

template

The template used by reno new to create a note.

Defaults to

---
prelude: >
    Replace this text with content to appear at the top of the section for this
    release. All of the prelude content is merged together and then rendered
    separately from the items listed in other parts of the file, so the text
    needs to be worded so that both the prelude and the other items make sense
    when read independently. This may mean repeating some details. Not every
    release note requires a prelude. Usually only notes describing major
    features or adding release theme details should have a prelude.
features:
  - |
    List new features here, or remove this section.  All of the list items in
    this section are combined when the release notes are rendered, so the text
    needs to be worded so that it does not depend on any information only
    available in another section, such as the prelude. This may mean repeating
    some details.
issues:
  - |
    List known issues here, or remove this section.  All of the list items in
    this section are combined when the release notes are rendered, so the text
    needs to be worded so that it does not depend on any information only
    available in another section, such as the prelude. This may mean repeating
    some details.
upgrade:
  - |
    List upgrade notes here, or remove this section.  All of the list items in
    this section are combined when the release notes are rendered, so the text
    needs to be worded so that it does not depend on any information only
    available in another section, such as the prelude. This may mean repeating
    some details.
deprecations:
  - |
    List deprecations notes here, or remove this section.  All of the list
    items in this section are combined when the release notes are rendered, so
    the text needs to be worded so that it does not depend on any information
    only available in another section, such as the prelude. This may mean
    repeating some details.
critical:
  - |
    Add critical notes here, or remove this section.  All of the list items in
    this section are combined when the release notes are rendered, so the text
    needs to be worded so that it does not depend on any information only
    available in another section, such as the prelude. This may mean repeating
    some details.
security:
  - |
    Add security notes here, or remove this section.  All of the list items in
    this section are combined when the release notes are rendered, so the text
    needs to be worded so that it does not depend on any information only
    available in another section, such as the prelude. This may mean repeating
    some details.
fixes:
  - |
    Add normal bug fixes here, or remove this section.  All of the list items
    in this section are combined when the release notes are rendered, so the
    text needs to be worded so that it does not depend on any information only
    available in another section, such as the prelude. This may mean repeating
    some details.
other:
  - |
    Add other notes here, or remove this section.  All of the list items in
    this section are combined when the release notes are rendered, so the text
    needs to be worded so that it does not depend on any information only
    available in another section, such as the prelude. This may mean repeating
    some details.

uid_overrides

A mapping of note filenames or paths to replacement UIDs. This allows resolving UID collisions when two release note files share the same UID (for example, if a note file was copied).

The keys should be the filename or path of the note file, and the values should be the replacement UID string (typically a 16-character hexadecimal string) or another note filename from which the UID will be derived.

Defaults to {}

unreleased_version_title

The title to use for any notes that do not appear in a released version. If this option is unset, the development version number is used (for example, 3.0.0-3).

Defaults to ''

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 .

Fixing Release Notes¶

Occasionally it is necessary to update release notes due to typos, URLs changing, or errors such as invalid section names not being noticed until after they have been committed or released.

Reno identifies each release note by the unique identifier (a 16-character hexadecimal SHA) embedded in its filename (for example, my-note-95915aaedd3c48d8.yaml). This identifier allows reno to track a release note across Git commits, modifications, and renames.

To fix an existing release note, edit the existing file in place and commit the changes. The process is exactly the same regardless of what you are fixing:

Fixing typos, grammatical mistakes, or broken links in the note text.
Correcting an invalid or unrecognized section header (for example, changing feature: to features:).
Adding or removing content from sections.

Because reno tracks notes by their unique ID, when you modify an existing note in a new commit, reno pulls the updated contents from the newest commit while retaining the note’s association with the release where it was first introduced.

Changed in version 2.6.0: Modifying an existing release note file in Git associates the note with the release where it was originally introduced while using the updated content from the newest commit. In earlier versions, modifying a note could cause it to be attributed to a newer release.

Past Releases and Stable Branches¶

If an update is needed for a release note that was already included in a past release on a stable branch, the fix should be proposed directly to the stable branch where the note was introduced (or cherry-picked to that branch). Because Git branches diverge at the branch point, commits made only on the main development branch are not in the Git history of the stable branch and will therefore not appear in documentation built from that stable branch.

Resolving UID Collisions¶

Because reno extracts the UID from the filename, if a release note file was copied or created manually with an existing UID, two distinct notes may share the same UID. When this happens, reno reports a UID collision error and scanner operations may fail or shadow one of the notes.

If the collision cannot be resolved by renaming the file (for instance, if the note is part of a previous release that should not be re-attributed to a new commit), you can configure uid_overrides in your configuration file (reno.yaml, releasenotes/config.yaml, or pyproject.toml).

uid_overrides maps note filenames to a replacement unique identifier:

uid_overrides:
  cyborg-mdev-support-a1b2c3d4e5f67890.yaml: f83b29d0e1a47c5e

Keys can be paths or basenames, and values can be either a replacement UID string (typically 16 hexadecimal characters) or another release note filename from which the UID will be derived.

Excluding Notes¶

If a release note was added by mistake and should be removed entirely from the rendered output, the ignore-notes option can be used in Sphinx (or ignore_notes in the configuration file) to exclude specific notes by filename or unique ID:

===========================
 Pike Series Release Notes
===========================

.. release-notes::
   :branch: stable/pike
   :ignore-notes:
     mistake-note-1-ee6274467572906b.yaml,
     mistake-note-2-dd6274467572906b.yaml

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.

Within GitHub Actions, ReadTheDocs, …¶

Both GitHub Actions (via the actions/checkout action) and ReadTheDocs use shallow clones by default. If running reno, you will need to configure the appropriate settings to ensure clones include all tags and branches.

Usage

Usage¶

Creating New Release Notes¶

Editing a Release Note¶

Note File Syntax¶

Generating a Report¶

Checking Notes¶

Computing Next Release Version¶

Configuring Reno¶

Debugging¶

Fixing Release Notes¶

Past Releases and Stable Branches¶

Resolving UID Collisions¶

Excluding Notes¶

Within OpenStack¶

Within GitHub Actions, ReadTheDocs, …¶

reno 4.1.1.dev28

Page Contents