![Doug Hellmann](/assets/img/avatar_default.png)
Add a sub-command for computing the next release version number by applying Semantic Versioning rules to the release notes added to a project since the last published release. Add configuration options to control which notes sections trigger updates to each level of the version number. Change-Id: I96be0c81a3947aaa0bf9080b500cf1bc77abe655 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
324 lines
10 KiB
ReStructuredText
324 lines
10 KiB
ReStructuredText
========
|
|
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.
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
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:
|
|
|
|
.. literalinclude:: ../../../examples/notes/add-complex-example-6b5927c246456896.yaml
|
|
:language: yaml
|
|
|
|
See :doc:`examples` for the rendered version of the note.
|
|
|
|
.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
.. _SemVer: https://semver.org
|
|
|
|
.. _configuration:
|
|
|
|
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.
|
|
|
|
.. code-block:: 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
|
|
|
|
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:
|
|
|
|
.. show-reno-config::
|
|
|
|
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.
|
|
|
|
.. code-block:: console
|
|
|
|
$ reno report .
|
|
|
|
Updating Stable Branch Release Notes
|
|
====================================
|
|
|
|
Occasionally it is necessary to update release notes for past releases
|
|
due to URLs changing or errors not being noticed until after they have
|
|
been released. In cases like these, it is important to note that any
|
|
updates to these release notes should be proposed directly to the stable
|
|
branch where they were introduced.
|
|
|
|
.. note::
|
|
|
|
Due to the way reno scans release notes, if a note is updated on a
|
|
later branch instead of its original branch, it will then show up
|
|
in the release notes for the later release.
|
|
|
|
If a note is accidentally modified in a later branch causing it to show
|
|
up in the wrong release's notes, the ``ignore-notes`` directive may be
|
|
used to manually exclude it from the generated output:
|
|
|
|
::
|
|
|
|
===========================
|
|
Pike Series Release Notes
|
|
===========================
|
|
|
|
.. release-notes::
|
|
:branch: stable/pike
|
|
:ignore-notes:
|
|
mistake-note-1-ee6274467572906b.yaml,
|
|
mistake-note-2-dd6274467572906b.yaml
|
|
|
|
|
|
Even though the note will be parsed in the newer release, it will be
|
|
excluded from the output for that release.
|
|
|
|
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
|
|
<https://docs.openstack.org/project-team-guide/release-management.html#managing-release-notes>`__
|
|
section of the Project Team Guide for details.
|
|
|
|
Within Travis CI
|
|
================
|
|
|
|
The `Travis CI <https://travis-ci.org/>`_ uses shallow git clones,
|
|
and detached head, which prevents reno from accessing the repo data
|
|
it needs.
|
|
You'll see an error message like the one mentioned in
|
|
`Launchpad bug 1703603 <https://bugs.launchpad.net/reno/+bug/1703603>`_.
|
|
|
|
To use reno within a Travis CI job, the cloned repository needs to be
|
|
unshallowed and checked out in the right branch from your ``.travis.yml``,
|
|
like in the following example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
language: python
|
|
|
|
python:
|
|
- 3.5
|
|
|
|
install:
|
|
- |
|
|
# Force unshallow and checkout the current branch
|
|
# https://docs.openstack.org/reno/latest/user/usage.html#within-travis-ci
|
|
git config remote.origin.fetch +refs/heads/*:refs/remotes/origin/*
|
|
git fetch --unshallow --tags
|
|
git symbolic-ref --short HEAD || git checkout -b ${TRAVIS_BRANCH}-test $TRAVIS_BRANCH
|
|
# Ref: https://stackoverflow.com/questions/32580821/how-can-i-customize-override-the-git-clone-step-in-travis-ci
|
|
|
|
script:
|
|
- reno report .
|