From 9599ffe65d9dcd4b3aa780d346eccd1e760890bf Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Tue, 13 Jun 2017 15:55:33 -0400 Subject: reorganize existing documentation according to the new standard layout Move existing content around based on the doc-migration specification. Replace :doc: markup with :ref: to have sphinx keep track of where the files move and generate valid hyperlinks. Add a few toctrees and index pages for the new directories. Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Change-Id: I253ee8f89d3ec40e39310c18bb87ed1d3d5de330 Signed-off-by: Doug Hellmann --- doc/source/contributor/command-beta.rst | 108 ++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 doc/source/contributor/command-beta.rst (limited to 'doc/source/contributor/command-beta.rst') diff --git a/doc/source/contributor/command-beta.rst b/doc/source/contributor/command-beta.rst new file mode 100644 index 00000000..40ede671 --- /dev/null +++ b/doc/source/contributor/command-beta.rst @@ -0,0 +1,108 @@ +.. _command-beta: + +============ +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. +This also applies to command options associated with the beta +command object. + +See the examples below on how to label an entire command or +a specific option as a beta by updating the documentation +and implementation. + +The initial release note must label the new command or option +as a beta. No further release notes are required until the command +or option is no longer a beta. At which time, the beta label or +the command or option itself must be removed and a new release note +must be provided. + +Beta Command Example +-------------------- + +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 ``--os-beta-command`` to + enable this command. + +.. program:: example list +.. code:: bash + + openstack 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 --os-beta-command to enable + this command) + """ + +Implementation +~~~~~~~~~~~~~~ + +The command must raise a ``CommandError`` exception if beta commands +are not enabled via ``--os-beta-command`` global option. + +.. code-block:: python + + def take_action(self, parsed_args): + self.validate_os_beta_command_enabled() + +Beta Option Example +------------------- + +Documentation +~~~~~~~~~~~~~ + +The option documentation must label the option as a beta. + +.. option:: --example + + Example + + .. caution:: This is a beta command option and subject + to change. Use global option ``--os-beta-command`` + to enable this command option. + +Implementation +~~~~~~~~~~~~~~ + +The option must not be added if beta commands are not +enabled via ``--os-beta-command`` global option. + +.. code-block:: python + + def get_parser(self, prog_name): + if self.app.options.os_beta_command: + parser.add_argument( + '--example', + metavar='', + help=_("Example") + ) -- cgit v1.2.1