From f9f3bca8f7f867dfcc5716224dc5b13270b17180 Mon Sep 17 00:00:00 2001 From: "wu.chunyang" Date: Mon, 11 Jul 2022 21:56:26 +0800 Subject: Add release note(aka. reno) guide This PR adds reloease note guide for trove project and renames some notes due to uid collision Change-Id: I55f49425dc3df6599ff6714efd8f7c1dc656ddf2 --- doc/requirements.txt | 12 ++ doc/source/contributor/index.rst | 1 + doc/source/contributor/release-notes.rst | 154 +++++++++++++++++++++ releasenotes/notes/support-backup-strategy.yaml | 6 + releasenotes/notes/support-online-resize.yaml | 7 + .../notes/support-subnet-and-ip-address.yaml | 7 + .../notes/victoria-support-backup-strategy.yaml | 6 - .../notes/victoria-support-online-resize.yaml | 7 - .../victoria-support-subnet-and-ip-address.yaml | 7 - releasenotes/templates/feature.yml | 7 + releasenotes/templates/fix.yml | 7 + tox.ini | 14 +- 12 files changed, 214 insertions(+), 21 deletions(-) create mode 100644 doc/requirements.txt create mode 100644 doc/source/contributor/release-notes.rst create mode 100644 releasenotes/notes/support-backup-strategy.yaml create mode 100644 releasenotes/notes/support-online-resize.yaml create mode 100644 releasenotes/notes/support-subnet-and-ip-address.yaml delete mode 100644 releasenotes/notes/victoria-support-backup-strategy.yaml delete mode 100644 releasenotes/notes/victoria-support-online-resize.yaml delete mode 100644 releasenotes/notes/victoria-support-subnet-and-ip-address.yaml create mode 100644 releasenotes/templates/feature.yml create mode 100644 releasenotes/templates/fix.yml 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 + +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] `__ + + +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 `__ + + +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] `__ + +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 `__ diff --git a/releasenotes/notes/support-backup-strategy.yaml b/releasenotes/notes/support-backup-strategy.yaml new file mode 100644 index 00000000..97b9335c --- /dev/null +++ b/releasenotes/notes/support-backup-strategy.yaml @@ -0,0 +1,6 @@ +--- +features: + - The user can create backup strategy to define the configurations for + creating backups, e.g. the swift container to store the backup data. Users + can also specify the container name when creating backups which takes + precedence over the backup strategy configuration. diff --git a/releasenotes/notes/support-online-resize.yaml b/releasenotes/notes/support-online-resize.yaml new file mode 100644 index 00000000..f5218013 --- /dev/null +++ b/releasenotes/notes/support-online-resize.yaml @@ -0,0 +1,7 @@ +--- +features: + - Trove now supports to resize volume without downtime. To use this feature, + the version of Nova and Cinder needs to be at least Pike, the config option + ``cinder_service_type`` needs to be set to ``volumev3``. The cloud admin + can disable this feature by setting ``online_volume_resize=False``, default + is enabled. \ No newline at end of file diff --git a/releasenotes/notes/support-subnet-and-ip-address.yaml b/releasenotes/notes/support-subnet-and-ip-address.yaml new file mode 100644 index 00000000..e7037ec5 --- /dev/null +++ b/releasenotes/notes/support-subnet-and-ip-address.yaml @@ -0,0 +1,7 @@ +--- +features: + - Support ``subnet_id`` and ``ip_address`` for creating instance. When + creating instance, trove will check the network conflicts between user's + network and the management network, additionally, the cloud admin is able + to define other reserved networks by configuring + ``reserved_network_cidrs``. diff --git a/releasenotes/notes/victoria-support-backup-strategy.yaml b/releasenotes/notes/victoria-support-backup-strategy.yaml deleted file mode 100644 index 97b9335c..00000000 --- a/releasenotes/notes/victoria-support-backup-strategy.yaml +++ /dev/null @@ -1,6 +0,0 @@ ---- -features: - - The user can create backup strategy to define the configurations for - creating backups, e.g. the swift container to store the backup data. Users - can also specify the container name when creating backups which takes - precedence over the backup strategy configuration. diff --git a/releasenotes/notes/victoria-support-online-resize.yaml b/releasenotes/notes/victoria-support-online-resize.yaml deleted file mode 100644 index f5218013..00000000 --- a/releasenotes/notes/victoria-support-online-resize.yaml +++ /dev/null @@ -1,7 +0,0 @@ ---- -features: - - Trove now supports to resize volume without downtime. To use this feature, - the version of Nova and Cinder needs to be at least Pike, the config option - ``cinder_service_type`` needs to be set to ``volumev3``. The cloud admin - can disable this feature by setting ``online_volume_resize=False``, default - is enabled. \ No newline at end of file diff --git a/releasenotes/notes/victoria-support-subnet-and-ip-address.yaml b/releasenotes/notes/victoria-support-subnet-and-ip-address.yaml deleted file mode 100644 index e7037ec5..00000000 --- a/releasenotes/notes/victoria-support-subnet-and-ip-address.yaml +++ /dev/null @@ -1,7 +0,0 @@ ---- -features: - - Support ``subnet_id`` and ``ip_address`` for creating instance. When - creating instance, trove will check the network conflicts between user's - network and the management network, additionally, the cloud admin is able - to define other reserved networks by configuring - ``reserved_network_cidrs``. 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] `__ 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] `__ 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 -- cgit v1.2.1