From c6a399f4535770d0a333bece590857a6ed1cdcd7 Mon Sep 17 00:00:00 2001 From: Lee Yarwood Date: Thu, 30 Mar 2017 16:25:25 +0100 Subject: [PATCH] doc: Separate the releasenotes guide from the code-review section This was previously hidden within the code review guide making it almost impossible to find from the initial index page. Change-Id: I47e771c641d72a837345b1b9a07e86ca4313b518 --- doc/source/code-review.rst | 73 ++++--------------------------------- doc/source/index.rst | 1 + doc/source/releasenotes.rst | 65 +++++++++++++++++++++++++++++++++ 3 files changed, 74 insertions(+), 65 deletions(-) create mode 100644 doc/source/releasenotes.rst diff --git a/doc/source/code-review.rst b/doc/source/code-review.rst index 6fcae38ca51f..59c287758800 100644 --- a/doc/source/code-review.rst +++ b/doc/source/code-review.rst @@ -239,72 +239,15 @@ If a new microversion API is added, the following needs to happen: should reference the Change-Id of the Tempest test for reviewers to identify it. -Release Notes -============= - -What is reno ? --------------- - -Nova uses `reno `_ for -providing release notes in-tree. That means that a patch can include a *reno -file* or a series can have a follow-on change containing that file explaining -what the impact is. - -A *reno file* is a YAML file written in the releasenotes/notes tree which is -generated using the reno tool this way: - -.. code-block:: bash - - $ tox -e venv -- reno new - -where usually ```` can be ``bp-`` for a -blueprint or ``bug-XXXXXX`` for a bugfix. - -Refer to the `reno documentation `_ -for the full list of sections. - - -When a release note is needed ------------------------------ - -A release note is required anytime a reno section is needed. Below are some -examples for each section. Any sections that would be blank should be left out -of the note file entirely. If no section is needed, then you know you don't -need to provide a release note :-) - -* ``upgrade`` - * The patch has an `UpgradeImpact `_ tag - * A DB change needs some deployer modification (like a migration) - * A configuration option change (deprecation, removal or modified default) - * some specific changes that have a `DocImpact `_ tag - but require further action from an deployer perspective - * any patch that requires an action from the deployer in general - -* ``security`` - * If the patch fixes a known vulnerability - -* ``features`` - * If the patch has an `APIImpact `_ tag - * For nova-manage and python-novaclient changes, if it adds or changes a - new command, including adding new options to existing commands - * not all blueprints in general, just the ones impacting a `contractual API `_ - * a new virt driver is provided or an existing driver impacts the `HypervisorSupportMatrix `_ - -* ``critical`` - * Bugfixes categorized as Critical in Launchpad *impacting users* - -* ``fixes`` - * No clear definition of such bugfixes. Hairy long-standing bugs with high - importance that have been fixed are good candidates though. - - -Three sections are left intentionally unexplained (``prelude``, ``issues`` and -``other``). Those are targeted to be filled in close to the release time for -providing details about the soon-ish release. Don't use them unless you know -exactly what you are doing. - - Notifications ============= * Every new notification type shall use the new versioned notification infrastructure documented in :doc:`notifications` + +Release Notes +============= + +A release note is required on changes that have upgrade impact, security +impact, introduce a new feature, fix Critical bugs, or fix long-standing bugs +with high importance. See :doc:`releasenotes` for details on how to create a release +note, each available section and the type of content required. diff --git a/doc/source/index.rst b/doc/source/index.rst index fc11cba7076c..d39c470865d8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -128,6 +128,7 @@ community, while keeping users happy and keeping developers productive. blueprints policies code-review + releasenotes Architecture Concepts ---------------------- diff --git a/doc/source/releasenotes.rst b/doc/source/releasenotes.rst new file mode 100644 index 000000000000..db40ad8b4a93 --- /dev/null +++ b/doc/source/releasenotes.rst @@ -0,0 +1,65 @@ +.. _releasenotes: + +Release Notes +============= + +What is reno ? +-------------- + +Nova uses `reno `_ for +providing release notes in-tree. That means that a patch can include a *reno +file* or a series can have a follow-on change containing that file explaining +what the impact is. + +A *reno file* is a YAML file written in the releasenotes/notes tree which is +generated using the reno tool this way: + +.. code-block:: bash + + $ tox -e venv -- reno new + +where usually ```` can be ``bp-`` for a +blueprint or ``bug-XXXXXX`` for a bugfix. + +Refer to the `reno documentation `_ +for the full list of sections. + + +When a release note is needed +----------------------------- + +A release note is required anytime a reno section is needed. Below are some +examples for each section. Any sections that would be blank should be left out +of the note file entirely. If no section is needed, then you know you don't +need to provide a release note :-) + +* ``upgrade`` + * The patch has an `UpgradeImpact `_ tag + * A DB change needs some deployer modification (like a migration) + * A configuration option change (deprecation, removal or modified default) + * some specific changes that have a `DocImpact `_ tag + but require further action from an deployer perspective + * any patch that requires an action from the deployer in general + +* ``security`` + * If the patch fixes a known vulnerability + +* ``features`` + * If the patch has an `APIImpact `_ tag + * For nova-manage and python-novaclient changes, if it adds or changes a + new command, including adding new options to existing commands + * not all blueprints in general, just the ones impacting a `contractual API `_ + * a new virt driver is provided or an existing driver impacts the `HypervisorSupportMatrix `_ + +* ``critical`` + * Bugfixes categorized as Critical in Launchpad *impacting users* + +* ``fixes`` + * No clear definition of such bugfixes. Hairy long-standing bugs with high + importance that have been fixed are good candidates though. + + +Three sections are left intentionally unexplained (``prelude``, ``issues`` and +``other``). Those are targeted to be filled in close to the release time for +providing details about the soon-ish release. Don't use them unless you know +exactly what you are doing.