From 0c3441599671e278031d07f87b318881870c8f10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rados=C5=82aw=20Piliszek?= Date: Sun, 31 Jan 2021 18:52:13 +0100 Subject: [PATCH] [docs] Add templates and examples of renos With tips and clarifications. Adapted from Kolla Ansible's patch. [1] [1] https://review.opendev.org/c/openstack/kolla-ansible/+/759254 Change-Id: I07490bc3a7809415fe1734aee255143c205d9573 --- doc/source/contributor/release-notes.rst | 131 ++++++++++++++++++++++- releasenotes/templates/feature.yml | 7 ++ releasenotes/templates/fix.yml | 7 ++ 3 files changed, 143 insertions(+), 2 deletions(-) create mode 100644 releasenotes/templates/feature.yml create mode 100644 releasenotes/templates/fix.yml diff --git a/doc/source/contributor/release-notes.rst b/doc/source/contributor/release-notes.rst index 854fc88fc1..e82da4c576 100644 --- a/doc/source/contributor/release-notes.rst +++ b/doc/source/contributor/release-notes.rst @@ -4,6 +4,9 @@ Release notes ============= +Introduction +~~~~~~~~~~~~ + Kolla uses the following release notes sections: - ``features`` --- for new features or functionality; these should ideally @@ -33,9 +36,15 @@ To add a release note, run the following command: tox -e venv -- reno new All release notes can be inspected by browsing ``releasenotes/notes`` -directory. +directory. Further on this page we show reno templates, examples and how to +make use of them. -To generate release notes in HTML format in ``releasenotes/build``, run: +.. note:: + + The term `release note` is often abbreviated to `reno` as it is the name of + the tool that is used to manage the release notes. + +To generate renos in HTML format in ``releasenotes/build``, run: .. code-block:: console @@ -43,3 +52,121 @@ To generate release notes in HTML format in ``releasenotes/build``, run: Note this requires the release note to be tracked by ``git`` so you have to at least add it to the ``git``'s staging area. + +The release notes are linted in the CI system. To lint locally, run: + +.. code-block:: console + + tox -e doc8 + +The above lints all of documentation at once. + +Templates and examples +~~~~~~~~~~~~~~~~~~~~~~ + +All approved release notes end up being published on a dedicated site: + + https://docs.openstack.org/releasenotes/kolla/ + +When looking for examples, it is advised to consider browsing the page above +for a similar type of change and then comparing with their source +representation in ``releasenotes/notes``. + +The sections below give further guidelines. Please try to follow them but note +they are not set in stone and sometimes a different wording might be more +appropriate. In case of doubt, the core team will be happy to help. + +Features +-------- + +Template +++++++++ + +.. path releasenotes/templates/feature.yml +.. code-block:: yaml + + --- + features: + - | + Implements [some feature]. + [Can be described using multiple sentences if necessary.] + [Limitations worth mentioning can be included as well.] + `Blueprint [blueprint id] `__ + +.. note:: + + The blueprint can be mentioned even if the change implements it only + partially. This can be emphasised by preceding the ``Blueprint`` word by + ``Partial``. See the example below. + +Example ++++++++ + +Implementing blueprint with id `letsencrypt-https`, we use ``reno`` to generate +the scaffolded file: + +.. code-block:: console + + tox -e venv -- reno new --from-template releasenotes/templates/feature.yml blueprint-letsencrypt-https + +.. note:: + + Since we don't require blueprints for simple features, it is allowed to + make up a blueprint-id-friendly string (like in the example here) ad-hoc + for the proposed feature. Please then skip the ``blueprint-`` prefix to + avoid confusion. + +And then fill it out with the following content: + +.. code-block:: yaml + + --- + features: + - | + Implements support for hassle-free integration with Let's Encrypt. + The support is limited to operators in the underworld. + For more details check the TLS docs of Kolla. + `Partial Blueprint letsencrypt-https `__ + +.. note:: + + The example above shows how to introduce a limitation. The limitation may be + lifted in the same release cycle and it is OK to mention it nonetheless. + Release notes can be edited later as long as they have not been shipped in + an existing release or release candidate. + +Fixes +----- + +Template +++++++++ + +.. path releasenotes/templates/fix.yml +.. code-block:: yaml + + --- + fixes: + - | + Fixes [some bug]. + [Can be described using multiple sentences if necessary.] + [Possibly also giving the previous behaviour description.] + `LP#[bug number] `__ + +Example ++++++++ + +Fixing bug number `1889611`, we use ``reno`` to generate the scaffolded file: + +.. code-block:: console + + tox -e venv -- reno new --from-template releasenotes/templates/fix.yml bug-1889611 + +And then fill it out with the following content: + +.. code-block:: yaml + + --- + fixes: + - | + Fixes ``deploy-containers`` action missing for the Masakari role. + `LP#1889611 `__ diff --git a/releasenotes/templates/feature.yml b/releasenotes/templates/feature.yml new file mode 100644 index 0000000000..f6d9944975 --- /dev/null +++ b/releasenotes/templates/feature.yml @@ -0,0 +1,7 @@ +--- +features: + - | + Implements [some feature]. + [Can be described using multiple sentences if necessary.] + [Limitations worth mentioning can be included as well.] + `Blueprint [blueprint id] `__ diff --git a/releasenotes/templates/fix.yml b/releasenotes/templates/fix.yml new file mode 100644 index 0000000000..913aa58ee6 --- /dev/null +++ b/releasenotes/templates/fix.yml @@ -0,0 +1,7 @@ +--- +fixes: + - | + Fixes [some bug]. + [Can be described using multiple sentences if necessary.] + [Possibly also giving the previous behaviour description.] + `LP#[bug number] `__