9599ffe65d
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 <doug@doughellmann.com>
2.8 KiB
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.
example list
openstack example listHelp
The command help must label the command as a beta.
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.
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.
--example <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.
def get_parser(self, prog_name):
if self.app.options.os_beta_command:
parser.add_argument(
'--example',
metavar='<example>',
help=_("Example")
)