Release Notes

In Development

New Features

  • Reno now allows specifying subsections, which will appear under their top-level sections like “Features”. This allows you to group related changes together better.

    To enable, set the sections value in config. Add subsections directly underneath their top-level section, with the number 2 or 3 after to indicate its nesting level. For example, ["features_command_line", "Command Line", 2]. Then, in your release note files, use the ID of the subsection, e.g. features_command_line.

Bug Fixes

  • Remove noisy log statement for deleted release notes. These look like:

    unable to find release notes file associated with unique id ‘34cd623294a30d83’, skipping

4.0.0

New Features

  • The default sort order for branch names has been modified in order to accomodate the way OpenStack stable branches are named. Branches that match the pattern stable/[0-9].* will be sorted as stable/zzz[0-9].*. This ensures that the new numerical branch names like stable/2023.1 will be sorted after the older stable branches like stable/zed. Two new variables have been added to control the behaviour, branch_sort_re and branch_sort_prefix. See their help text for more information.

Upgrade Notes

  • The default sort order for branch names has been modified in order to accomodate the way OpenStack stable branches are named. See the “Features” section for more information.

3.5.0

New Features

  • The reno.scanner.Scanner and reno.loader.Loader classes can now be used as context managers. For example:

    import reno.scannner

with reno.scanner.Scanner(...) as scanner:
    pass

    This will ensure any open files pertaining to the scanned Git repo are correctly closed, avoiding ResourceWarning instances otherwise seen.

    A close() method is also provided for both, allowing use outside of context managers. For example:

    import reno.loader

loader = reno.loader.Loader(...)
try:
    pass
finally:
    loader.close()

Bug Fixes

  • Instances of reno.scanner.Scanner and reno.loader.Loader will now corectly close all open files related to the scanned Git repo when the close() method is called. Alternatively, these classes may be used as a context manager. Previously, Python would attempt to close these files itself, resulting in a ResourceWarning warning being emitted.

3.4.0

New Features

  • Release note file validation is improved. Files missing section information will now be correctly handled and rejected, as will invalid sections.

3.2.0

New Features

  • Add a new configuration option, encoding, to specify the encoding to use when reading release notes file. See Usage for more details.

  • Add the semver-next command to calculate the next release version based on the available release notes. Three new configuration options (semver_major, semver_minor, and semver_patch) define the sections that should cause different types of version increments. See Usage for details.

3.1.0

New Features

  • If no earliest version is provided for a branch, reno will scan commits on the branch in reverse order, attempting to find a common ancestor with the master branch. Once found, the last common commit - the branch point - is checked for a tag. Previously, if no tag was found, reno would stop scanning. This was problematic for instances where a branch was not created at the tagged commit but rather some commits later. Reno will now continue scanning until it finds a tag.

  • Add an option, add_release_date, to print the release dates for every version.

Bug Fixes

  • Previously, it was not possible build documentation that used the release-notes Sphinx extension from tarballs. The Sphinx extension will now search the following directories, relative to the working directory of the sphinx-build tool, to find the release notes directory: ., .., and ../... This only applies when it is not possible to discover this information using git.

3.0.0

New Features

  • The reno cache command and build_reno setuptools command now default to scanning to all enabled branches. This ensures the cache is complete for projects that use multiple branches, such as stable branches.

Upgrade Notes

  • Python 2.7 support has been dropped. The minimum version of Python now supported by reno is Python 3.6.

2.11.2

Bug Fixes

  • Fix an issue with the way command line options and configuration settings interact so that the settings in the configuration file are used properly when command line arguments for those options are not provided.

2.10.0

New Features

  • Allow optional ‘v’ prefix in the default version tag regex.

2.9.2

Bug Fixes

2.9.0

New Features

  • Add a build_reno setuptools command that allows users to generate a release notes document and a reno cache file that can be used to build release notes documents without the full Git history present.

  • Added explicitly calculated anchors to ensure section links are both unique and stable over time.

2.8.0

New Features

  • Added configuration option unreleased_version_title with associated Sphinx directive argument to control whether to show the computed version number for changes that have not been tagged, or to show a static title string specified in the option value.

2.7.0

New Features

  • Adds new configuration options closed_branch_tag_re (to identify tags that replace branches that have been closed) and branch_name_prefix (a value to be added back to the closed branch tag to turn it into the original branch name.

    These options are used in OpenStack to support scanning the history of a branch based on the previous series branch, even after that previous series is closed by setting closed_branch_tag_re to (.+)-eol so that the series name in a value like "mitaka-eol" is extracted using the group. With branch_name_prefix set to "stable/" the tag mitaka-eol becomes the branch name stable/mitaka.

Bug Fixes

  • Fixes bug 1746076 so that scanning stable branches correctly includes the history of earlier closed stable branches.

2.6.0

New Features

  • The --from-template flag was added to the release note creation command. This enables one to create a release note from a pre-defined template, which is useful when automating the creation of commits.

Bug Fixes

  • A fix is included to ignore changes to a note file until the scanner encounters the git operation that adds the file. This ensures that if a file is modified on master when it should be modified on another branch the note is not erroneously incorporated into the notes for the next release from master. fixes bug 1682796

2.5.1

New Features

  • The automatic branch name handling is updated so that if the reference points explicitly to the origin remote, but that remote isn’t present (as it won’t be when zuul configures the repo in CI), then the shortened form of the reference without the prefix is used instead. This allows explicit references to origin/stable/name to be translated to stable/name and find the expected branch.

2.5.0

New Features

  • Release notes entries may now be made up of single strings. This simplifies formatting for smaller notes, and eliminates a class of errors associated with escaping reStructuredText inside YAML lists.

  • Add a new configuration option ignore_notes. Setting the value to a list of filenames or UIDs for notes causes the reno scanner to ignore them. 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.

  • reno will now scan for a reno.yaml file in the root repo directory if a config.yaml file does not exist in the releasenotes directory. This allows users to do away with the unnecessary notes subdirectory in the releasenotes directory.

2.4.1

Bug Fixes

  • Remove an infinite loop in the traversal algorithm caused by some null-merge skip situations.

2.4.0

New Features

  • By default, reno now ignores “null” merge commits that bring in tags from other threads. The new configuration option ignore_null_merges controls this behavior. Setting the flag to False restores the previous behavior in which the null-merge commits were traversed like any other merge commit.

Upgrade Notes

  • The new configuration option ignore_null_merges causes the scanner to ignore merge commits with no changes when one of the parents being merged in has a release tag on it.

Bug Fixes

  • This release fixes a problem with the scanner that may have caused it to stop scanning a branch prematurely when the tag from another branch had been merged into the history.

2.3.2

Bug Fixes

  • Correct a problem with handling deleted release notes that triggered a TypeError with a message like “Can’t mix strings and bytes in path components”

2.3.1

Other Notes

  • The oslosphinx dependency for building documentation is now optional. This breaks a build cycle between oslosphinx and reno.

2.3.0

New Features

  • Add a lint command for checking the contents and names of the release notes files against some basic validation rules.

Bug Fixes

  • Sphinx 1.6.1 now interprets error and warning log messages as reasons to abort the build when strict mode is enabled. This release changes the log level for some calls that weren’t really errors to begin with to avoid having Sphinx abort the build unnecessarily.

2.2.1

Bug Fixes

  • Fix a problem caused by failing to process multiple files with the same UID portion of the filename. Ignore existing cases as long as there is a corrective patch to remove them. Prevent new cases from being introduced. See https://bugs.launchpad.net/reno/+bug/1688042 for details.

2.2.0

New Features

  • Add a --no-show-source option to the report command to skip including the note reference file names and SHA information in comments in the output. This restores the previous format of the output for cases where it is meant to be read by people directly, not just converted to HTML.

  • Add a --title option to the report command.

2.1.2

Bug Fixes

  • Fixes a problem with the sphinx extension that caused it to produce an error if it had a list of versions to include that were not within the set that seemed to be on the branch because of the branch-base detection logic. Now if a list of versions is included, the scan always includes the full history.

2.1.1

Bug Fixes

  • Fix a problem with branch references so that it is now possible to use a local tracking branch name when the branch only exists on the ‘origin’ remote. For example, this allows references to ‘stable/ocata’ when there is no local branch with that name but there is an ‘origin/stable/ocata’ branch.

2.1.0

New Features

  • Add a configuration option branch_name_re to hold a regular expression for choosing “interesting” branches when trying to automatically detect how far back the scanner should look. The default is stable/.+, which works for the OpenStack practice of creating branches named after the stable series of releases.

  • Add a configuration option sections to hold the list of permitted section identifiers and corresponding display names. This also determines the order in which sections are collated.

  • Add the ability to specify regular expressions to a define a customised versioning scheme for release tags and pre-release tags.

    By default this change supports the current versioning scheme used by OpenStack.

    To customise, update the config.yaml file with the appropriate values. For example, for tags with versions like v1.0.0 and pre-release versions like v1.0.0rc1 the following could be added to config.yaml:

    release_tag_re: 'v\d\.\d\.\d(rc\d+)?'
pre_release_tag_re: '(?P<pre_release>rc\d+$)'

  • Include the local working copy when scanning the history of the current branch. Notes files must at least be staged to indicate that they will eventually be part of the history, but subsequent changes to the file do not need to also be staged to be seen.

  • The scanner for the “current” branch (usually master) now stops when it encounters the base of an earlier branch matching the branch_name_re config option. This results in less history appearing on the unreleased pages, while still actually showing the current series and any unreleased notes.

  • The report output now includes debugging details with the filename and sha for the version of the content used to indicate where the content is from to assist with debugging formatting or content issues.

Bug Fixes

  • Fixes the logic for determining how far back in history to look when scanning a given branch. Reno now looks for the base of the “previous” branch, as determined by looking at branches matching branch_name_re in lexical order. This may not work if branches are created using version numbers as their names.

2.0.2

Bug Fixes

  • Fix a problem with the way reno automatically detects the initial version in a branch that prevented it from including all of the notes associated with a release, especially if the branch was created at a pre-release version number. Bug #1652092

2.0.0

Prelude

This release includes a significant rewrite of the internal logic of reno to access git data through the dulwich library instead of the git command line porcelain.

New Features

  • Reno now supports having a config.yaml file in your release notes directory. It will search for file in the directory specified by --rel-notes-dir and parse it. It will apply whatever options are valid for that particular command. If an option is not relevant to a particular sub-command, it will not attempt to apply them.

  • Explicitly allow reno to scan starting from a tag by specifying the tag where a branch name would otherwise be used.

  • Add logic to allow reno to detect a branch that has been marked as end-of-life using the OpenStack community’s process of tagging the HEAD of a stable/foo branch foo-eol before deleting the branch. This means that references to “stable/foo” are translated to “foo-eol” when the branch does not exist, and that Sphinx directives do not need to be manually updated.

  • Set the default value of the reporoot argument for all command line programs to “.” and make it an optional parameter.

  • Automatically stop scanning branches at the point where they diverge from master. This avoids having release notes from older versions, that appear on master before the branch, from showing up in the versions from the branch. This logic is only applied to branches created from master.

  • Add a new configuration option, stop_at_branch_base, to control whether or not the scanner stops looking for changes at the point where a branch diverges from master. The default is True, meaning that the scanner does stop. A false value means that versions that appear on master from a point earlier than when the branch was created will be included when scanning the branch for release notes.

  • Reno now supports to set through template attribute in config.yaml a custom template which will be used by reno new to create notes.

  • Reno now enables with reno new --edit to create a note and edit it with your editor (defined with EDITOR environment variable).

Newton and Earlier

1.9.0

New Features

  • Add logic to allow reno to detect a branch that has been marked as end-of-life using the OpenStack community’s process of tagging the HEAD of a stable/foo branch foo-eol before deleting the branch. This means that references to “stable/foo” are translated to “foo-eol” when the branch does not exist, and that Sphinx directives do not need to be manually updated.

1.5.0

New Features

  • Add the ability to limit queries by stopping at an “earliest version”. This is intended to be used when scanning a branch, for example, to stop at a point when the branch was created and not include all of the history from the parent branch.

1.4.0

New Features

  • Add a flag to collapse pre-release notes into their final release, if the final release tag is present.

Bug Fixes

  • Resolves a bug with properly detecting pre-release versions in the existing history of a repository that resulted in some release notes not appearing in the report output.

1.3.0

Bug Fixes

  • Fixes bug 1522153 so that notes added in commits that are merged after tags are associated with the correct version.

1.2.0

New Features

  • Added a new section for deprecations that occur during a release

1.1.0

New Features

  • Add the --verbose, -v, and -q options to the command line tool for producing different levels of debug output.

Bug Fixes

  • Fix bug 1517175 to ensure that all tagged versions are detected and that notes are associated with the correct version numbers.

1.0.0

New Features

  • Add the sphinx extension for integration with documentation builds.

  • Support note entries that span multiple lines using preformatted syntax in YAML by prefixing the list entry with |.

    For example:

    - |
  This entry has two paragraphs.

  This is the second.

Upgrade Notes

  • Change the order of the slug and UUID value in the note filename so the slug comes before the UUID to make tab completion easier to use.

    Older files are still supported, and can be renamed to use the new style.

0.1.1

Bug Fixes

  • Fixed the section used in the report to include the prelude in the output.

0.1.0

Prelude

This is the first release.

New Features

  • Creating new notes files with unique names.

  • Listing the files with notes related to each release.

  • Producing a unified report of all of the notes for a release.