Merge "Devref: Command Beta"

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
 ======================================
 

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)

doc/source/index.rst

@@ -47,6 +47,7 @@ Developer Documentation
    :maxdepth: 1
 
    developing
+   command-beta
    command-options
    command-wrappers
    command-errors

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
 ========
 

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: