openstack/python-openstackclient
Code Issues Proposed changes

Clarification of option name rules

Browse Source 
We never specifcally said anywhere that short names are global only and why.

Change-Id: Ia2824cb7ebe7c2e1d116c0a9bc7760de24904c61
This commit is contained in:
Dean Troyer 2016-07-22 12:58:24 -05:00
parent b59ade75e5
commit 75a1fcf70a
2 changed files with 20 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/command-options.rst
View File

@ -14,6 +14,12 @@ for defining and using options in all situations. The alternative of only
using it when necessary leads to errors when copy-n-paste is used for a using it when necessary leads to errors when copy-n-paste is used for a
new command without understanding why or why not that instance is correct. new command without understanding why or why not that instance is correct.
The :doc:`Human Interface Guide <humaninterfaceguide>`
describes the guildelines for option names and usage. In short:
* All option names shall be GNU-style long names (two leading dashes).
* Some global options may have short nmaes, generally limited to those defined
in support libraries such as ``cliff``.
General Command Options General Command Options
======================= =======================

22
doc/source/humaninterfaceguide.rst
View File

@ -183,14 +183,6 @@ Output formats:
* user-friendly tables with headers, etc * user-friendly tables with headers, etc
* machine-parsable delimited * machine-parsable delimited
Notes:
* All long options names shall begin with two dashes ('--') and use a single dash
('-') internally between words (:code:`--like-this`). Underscores ('_') shall not
be used in option names.
* Authentication options conform to the common CLI authentication guidelines in
:doc:`authentication`.
Global Options Global Options
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
@ -202,6 +194,16 @@ the command-line option takes priority. The environment variable names are deri
from the option name by dropping the leading dashes ('--'), converting each embedded from the option name by dropping the leading dashes ('--'), converting each embedded
dash ('-') to an underscore ('_'), and converting to upper case. dash ('-') to an underscore ('_'), and converting to upper case.
* Global options shall always have a long option name, certain common options may
also have short names. Short names should be reserved for global options to limit
the potential for duplication and multiple meanings between commands given the
limited set of available short names.
* All long options names shall begin with two dashes ('--') and use a single dash
('-') internally between words (:code:`--like-this`). Underscores ('_') shall not
be used in option names.
* Authentication options conform to the common CLI authentication guidelines in
:doc:`authentication`.
For example, :code:`--os-username` can be set from the environment via For example, :code:`--os-username` can be set from the environment via
:code:`OS_USERNAME`. :code:`OS_USERNAME`.
@ -245,6 +247,10 @@ Each command may have its own set of options distinct from the global options.
They follow the same style as the global options and always appear between They follow the same style as the global options and always appear between
the command and any positional arguments the command requires. the command and any positional arguments the command requires.
Command options shall only have long names. The small range of available
short names makes it hard for a single short option name to have a consistent
meaning across multiple commands.
Option Forms Option Forms
++++++++++++ ++++++++++++