From 9fe78e8a60f7ff6797a8a03e1da05ebc3e251fb8 Mon Sep 17 00:00:00 2001 From: Takashi NATSUME Date: Mon, 24 Jun 2019 11:35:36 +0900 Subject: Add a guide to add a new microversion support Add a contributor guide for adding a new microversion support. Change-Id: I5e7699b6afbecf1e22cdc059a36832c144fc8e2f --- doc/source/conf.py | 1 + doc/source/contributor/index.rst | 1 + doc/source/contributor/microversions.rst | 71 ++++++++++++++++++++++++++++++++ 3 files changed, 73 insertions(+) create mode 100644 doc/source/contributor/microversions.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index ffd5782d..b535272d 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -80,6 +80,7 @@ bug_project = 'python-novaclient' bug_tag = '' openstack_projects = [ 'keystoneauth', + 'nova', 'os-client-config', 'python-openstackclient', ] diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 91ead0be..58b9bd7e 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -13,4 +13,5 @@ __ https://docs.openstack.org/infra/manual/developers.html#development-workflow .. toctree:: :maxdepth: 2 + microversions testing diff --git a/doc/source/contributor/microversions.rst b/doc/source/contributor/microversions.rst new file mode 100644 index 00000000..7cd41c46 --- /dev/null +++ b/doc/source/contributor/microversions.rst @@ -0,0 +1,71 @@ +===================================== +Adding support for a new microversion +===================================== + +If a new microversion is added on the nova side, +then support must be added on the *python-novaclient* side also. +The following procedure describes how to add support for a new microversion +in *python-novaclient*. + +#. Update ``API_MAX_VERSION`` + + Set ``API_MAX_VERSION`` in ``novaclient/__init__.py`` to the version + you are going to support. + + .. note:: + + Microversion support should be added one by one in order. + For example, microversion 2.74 should be added right after + microversion 2.73. Microversion 2.74 should not be added right + after microversion 2.72 or earlier. + +#. Update CLI and Python API + + Update CLI (``novaclient/v2/shell.py``) and/or Python API + (``novaclient/v2/*.py``) to support the microversion. + +#. Add tests + + Add unit tests for the change. Add unit tests for the previous microversion + to check raising an error or an exception when new arguments or parameters + are specified. Add functional tests if necessary. + + Add the microversion in the ``exclusions`` in the ``test_versions`` + method of the ``novaclient.tests.unit.v2.test_shell.ShellTest`` class + if there are no versioned wrapped shell method changes + for the microversion. + + For example (microversion 2.72 example):: + + exclusions = set([ + (snipped...) + 72, # There are no version-wrapped shell method changes for this. + ]) + +#. Update the CLI reference + + Update the CLI reference (``doc/source/cli/nova.rst``) + if the CLI commands and/or arguments are modified. + +#. Add a release note + + Add a release note for the change. The release note should include a link + to the description for the microversion in the + :nova-doc:`Compute API Microversion History + `. + +#. Commit message + + The description of the blueprint and dependency on the patch in nova side + should be added in the commit message. For example:: + + Implements: blueprint remove-force-flag-from-live-migrate-and-evacuate + Depends-On: https://review.opendev.org/#/c/634600/ + +See the following examples: + +- `Microversion 2.71 - show server group `_ +- `API microversion 2.69: Handles Down Cells `_ +- `Microversion 2.68: Remove 'forced' live migrations, evacuations `_ +- `Add support changes-before for microversion 2.66 `_ +- `Microversion 2.64 - Use new format policy in server group `_ -- cgit v1.2.1