Merge "Add release note(aka. reno) guide"

9 files changed, 194 insertions, 1 deletions

diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 00000000..da3f3abf
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,12 @@
+# The order of packages is significant, because pip processes them in the order
+# of appearance. Changing the order has an impact on the overall integration
+# process, which may cause wedges in the gate later.
+# Order matters to the pip dependency resolver, so sorting this file
+# changes how packages are installed.  New dependencies should be
+# added in alphabetical order, however, some dependencies may need to
+# be installed in a specific order.
+openstackdocstheme>=2.2.1 # Apache-2.0
+reno>=3.1.0 # Apache-2.0
+sphinx>=2.0.0,!=2.1.0 # BSD
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
+whereto>=0.3.0 # Apache-2.0
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 43b5a13b..3ba2f00e 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -13,3 +13,4 @@ functionality, the following resources are provided.
    design
    functional_test
    testing
+   release-notes
diff --git a/doc/source/contributor/release-notes.rst b/doc/source/contributor/release-notes.rst
new file mode 100644
index 00000000..30923ffa
--- /dev/null
+++ b/doc/source/contributor/release-notes.rst
@@ -0,0 +1,154 @@
+.. _release-notes:
+
+=============
+Release notes
+=============
+
+Introduction
+~~~~~~~~~~~~
+
+Trove uses the following release notes sections:
+
+- ``features`` --- for new features or functionality; these should ideally
+  refer to the blueprint being implemented;
+- ``fixes`` --- for fixes closing bugs; these must refer to the bug being
+  closed;
+- ``upgrade`` --- for notes relevant when upgrading from previous version;
+  these should ideally be added only between major versions; required when
+  the proposed change affects behaviour in a non-backwards compatible way or
+  generally changes something impactful;
+- ``deprecations`` --- to track deprecated features; relevant changes may
+  consist of only the commit message and the release note;
+- ``prelude`` --- filled in by the PTL or Cores before each release or RC.
+
+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 Trove,
+are OpenStack administrators/operators.
+In case of doubt, the core team will let you know what is required.
+
+To add a release note, run the following command:
+
+.. code-block:: console
+
+   tox -e venv -- reno new <summary-line-with-dashes>
+
+All release notes can be inspected by browsing ``releasenotes/notes``
+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 renos in HTML format in ``releasenotes/build``, run:
+
+.. code-block:: console
+
+   tox -e releasenotes
+
+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 pep8
+
+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/trove/
+
+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.]
+       `Stroy [Story id] <https://storyboard.openstack.org/#!/story/[Story id]>`__
+
+
+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
+
+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 Trove.
+       `Stroy xxx <https://storyboard.openstack.org/#!/story/xxx>`__
+
+
+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.]
+       `Stroy [Story id] <https://storyboard.openstack.org/#!/story/[Story id]>`__
+
+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 ``create-datastore`` action doesn't work for the mysql datastore.
+       `LP#xxx <https://storyboard.openstack.org/#!/story/xxx>`__
diff --git a/releasenotes/notes/victoria-support-backup-strategy.yaml b/releasenotes/notes/support-backup-strategy.yaml
index 97b9335c..97b9335c 100644
--- a/releasenotes/notes/victoria-support-backup-strategy.yaml
+++ b/releasenotes/notes/support-backup-strategy.yaml
diff --git a/releasenotes/notes/victoria-support-online-resize.yaml b/releasenotes/notes/support-online-resize.yaml
index f5218013..f5218013 100644
--- a/releasenotes/notes/victoria-support-online-resize.yaml
+++ b/releasenotes/notes/support-online-resize.yaml
diff --git a/releasenotes/notes/victoria-support-subnet-and-ip-address.yaml b/releasenotes/notes/support-subnet-and-ip-address.yaml
index e7037ec5..e7037ec5 100644
--- a/releasenotes/notes/victoria-support-subnet-and-ip-address.yaml
+++ b/releasenotes/notes/support-subnet-and-ip-address.yaml
diff --git a/releasenotes/templates/feature.yml b/releasenotes/templates/feature.yml
new file mode 100644
index 00000000..33d5c537
--- /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.]
+    `Stroy [Story id] <https://storyboard.openstack.org/#!/story/[story id]>`__
diff --git a/releasenotes/templates/fix.yml b/releasenotes/templates/fix.yml
new file mode 100644
index 00000000..13e51f83
--- /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#[Story id] <https://storyboard.openstack.org/#!/story/[Story id]>`__
diff --git a/tox.ini b/tox.ini
index 799454a6..c35a01df 100644
--- a/tox.ini
+++ b/tox.ini
@@ -26,9 +26,15 @@ allowlist_externals = find
                       bash
 
 [testenv:pep8]
+deps =
+  -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
+  -r{toxinidir}/test-requirements.txt
 commands =
     flake8
+    reno lint
     doc8 {posargs}
+    doc8 -e '.yaml' releasenotes/notes/
+    doc8 doc/source
 
 [testenv:debug]
 commands = oslo_debug_helper {posargs}
@@ -79,7 +85,13 @@ commands =
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [testenv:releasenotes]
-commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+deps =
+    -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
+    -r{toxinidir}/doc/requirements.txt
+allowlist_externals = rm
+commands =
+  rm -rf releasenotes/build
+  sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [testenv:bandit]
 commands = bandit -r trove -n5 -x tests