From 059c735874f4f278b2f3514f0ba010c76a7eefbf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rados=C5=82aw=20Piliszek?= <radoslaw.piliszek@gmail.com>
Date: Thu, 22 Oct 2020 14:29:08 +0200
Subject: [PATCH] [docs] Add templates and examples of renos
With tips and clarifications.
Change-Id: Ic744e13805c4a158d1156a230f8c57d7a980d55f
---
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 739d3a0b5..fb48c06e8 100644
--- a/doc/source/contributor/release-notes.rst
+++ b/doc/source/contributor/release-notes.rst
@@ -4,6 +4,9 @@
Release notes
=============
+Introduction
+~~~~~~~~~~~~
+
Kolla Ansible (just like 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 <summary-line-with-dashes>
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.
+
+.. 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 release notes in HTML format in ``releasenotes/build``, run:
+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-ansible/
+
+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] <https://blueprints.launchpad.net/kolla-ansible/+spec/[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 Ansible.
+ `Partial Blueprint letsencrypt-https <https://blueprints.launchpad.net/kolla-ansible/+spec/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] <https://launchpad.net/bugs/[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 <https://launchpad.net/bugs/1889611>`__
diff --git a/releasenotes/templates/feature.yml b/releasenotes/templates/feature.yml
new file mode 100644
index 000000000..08bf1b4c5
--- /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] <https://blueprints.launchpad.net/kolla-ansible/+spec/[blueprint id]>`__
diff --git a/releasenotes/templates/fix.yml b/releasenotes/templates/fix.yml
new file mode 100644
index 000000000..913aa58ee
--- /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] <https://launchpad.net/bugs/[bug number]>`__
--
GitLab