Merge "Add releasenotes templates and update documentation"

doc/source/contributor/release-notes.rst

@@ -4,6 +4,9 @@
 Release notes
 =============
 
+Introduction
+~~~~~~~~~~~~
+
 Kayobe (just like Kolla) uses the following release notes sections:
 
 - ``features`` --- for new features or functionality; these should ideally
@@ -22,7 +25,7 @@ Other release note types may be applied per common sense.
 Each change should include a release note unless being a ``TrivialFix``
 change or affecting only docs or CI. Such changes should `not` include
 a release note to avoid confusion.
-Remember release notes are mostly for end users which, in case of Kolla,
+Remember release notes are mostly for end users which, in case of Kayobe,
 are OpenStack administrators/operators.
 In case of doubt, the core team will let you know what is required.
 
@@ -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.
 
-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,90 @@ 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.
+
+Templates and examples
+~~~~~~~~~~~~~~~~~~~~~~
+
+All approved release notes end up being published on a dedicated site:
+
+   https://docs.openstack.org/releasenotes/kayobe/
+
+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.]
+
+Example
++++++++
+
+Implementing feature 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 letsencrypt-https
+
+And then fill it out with the following content (for example):
+
+.. 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 Kayobe.
+
+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://bugs.launchpad.net/kayobe/+bug/[bug number]>`__
+
+Example
++++++++
+
+Fixing bug number `9999999`, we use ``reno`` to generate the scaffolded file:
+
+.. code-block:: console
+
+   tox -e venv -- reno new --from-template releasenotes/templates/fix.yml bug-9999999
+
+And then fill it out with the following content (for example):
+
+.. code-block:: yaml
+
+   ---
+   fixes:
+     - |
+       Fixes ``deploy-containers`` action missing for the Masakari role.
+       `LP#9999999 <https://bugs.launchpad.net/kayobe/+bug/9999999>`__

releasenotes/templates/feature.yml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Implements [some feature].
+    [Can be described using multiple sentences if necessary.]

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://bugs.launchpad.net/kayobe/+bug/[bug number]>`__