diff --git a/doc/source/backwards-incompatible.rst b/doc/source/backwards-incompatible.rst index 4b90d6e1bc..00b314a53c 100644 --- a/doc/source/backwards-incompatible.rst +++ b/doc/source/backwards-incompatible.rst @@ -10,6 +10,9 @@ Should positional arguments for a command need to change, the OpenStackClient team attempts to make the transition as painless as possible. Look for deprecation warnings that indicate the new commands (or options) to use. +Commands labeled as a beta according to :doc:`command-beta` are exempt from +this backwards incompatible change handling. + List of Backwards Incompatible Changes ====================================== diff --git a/doc/source/command-beta.rst b/doc/source/command-beta.rst new file mode 100644 index 0000000000..53a442047f --- /dev/null +++ b/doc/source/command-beta.rst @@ -0,0 +1,72 @@ +============ +Command Beta +============ + +OpenStackClient releases do not always coincide with OpenStack +releases. This creates challenges when developing new OpenStackClient +commands for the current OpenStack release under development +since there may not be an official release of the REST API +enhancements necessary for the command. In addition, backwards +compatibility may not be guaranteed until an official OpenStack release. +To address these challenges, an OpenStackClient command may +be labeled as a beta command according to the guidelines +below. Such commands may introduce backwards incompatible +changes and may use REST API enhancements not yet released. + +See the examples below on how to label a command as a beta +by updating the command documentation, help and implementation. + +The initial release note must label the new command as a beta. +No further release notes are required until the command +is no longer a beta. At which time, the command beta label +or the command itself must be removed and a new release note +must be provided. + +Documentation +------------- + +The command documentation must label the command as a beta. + +example list +~~~~~~~~~~~~ + +List examples + +.. caution:: This is a beta command and subject to change. + Use global option ``--enable-beta-commands`` to + enable this command. + +.. program:: example list +.. code:: bash + + os example list + +Help +---- + +The command help must label the command as a beta. + +.. code-block:: python + + class ShowExample(command.ShowOne): + """Display example details + + (Caution: This is a beta command and subject to change. + Use global option --enable-beta-commands to enable + this command) + """ + +Implementation +-------------- + +The command must raise a ``CommandError`` exception if beta commands +are not enabled via ``--enable-beta-commands`` global option. + +.. code-block:: python + + def take_action(self, parsed_args): + if not self.app.options.enable_beta_commands: + msg = _('Caution: This is a beta command and subject to ' + 'change. Use global option --enable-beta-commands ' + 'to enable this command.') + raise exceptions.CommandError(msg) diff --git a/doc/source/index.rst b/doc/source/index.rst index fe12b862ea..0869344142 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -47,6 +47,7 @@ Developer Documentation :maxdepth: 1 developing + command-beta command-options command-wrappers command-errors diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst index a2ecd8db73..8cd10a7933 100644 --- a/doc/source/man/openstack.rst +++ b/doc/source/man/openstack.rst @@ -147,6 +147,9 @@ OPTIONS :option:`--debug` show tracebacks on errors and set verbosity to debug +:option:`--enable-beta-commands` + Enable beta commands which are subject to change + COMMANDS ======== diff --git a/openstackclient/shell.py b/openstackclient/shell.py index b96fb089b9..9968d73fc1 100644 --- a/openstackclient/shell.py +++ b/openstackclient/shell.py @@ -250,6 +250,11 @@ class OpenStackShell(app.App): action='store_true', help="Print API call timing info", ) + parser.add_argument( + '--enable-beta-commands', + action='store_true', + help="Enable beta commands which are subject to change", + ) # osprofiler HMAC key argument if osprofiler_profiler: