** Changed in: glance
Status: In Progress => Fix Released
** Changed in: glance-store
Status: In Progress => Fix Released
--
You received this bug notification because you are a member of Yahoo!
Engineering Team, which is subscribed to Glance.
https://bugs.launchpad.net/bugs/1570946
Title:
Improve Help Text of Configuration Options in Glance and Glance Store
Status in Glance:
Fix Released
Status in glance_store:
Fix Released
Bug description:
The overall aim is operators should not need to read and understand
the code to know how to configure the system.
This lite-spec is focusing on making sure oslo.config has all the
information required to generate good sample configuration files and
generating good documentation for the configuration options. This spec
is not focusing on how the documentation is generated from the option
definitions.
Most importantly, we need a good description for each of the
configuration options, set in the help text of the option. This means
developers reviewing each configuration option descriptions and adding
any missing details.
Nova has found standardizing around a template has helped build some
consistency in what is described in the help text for each option.
This template, shown below, probably works well for Glance too.
# A short description about what it does. If it is a unit (e.g. timeout)
# describe the unit which is used (seconds, megabyte, mebibyte, ...)
# A long description what the impact and scope is. The operators should
# know the expected change in the behavior of Glance if they tweak this.
Possible values:
# Description of possible values. Especially if this is an option
# with numeric values (int, float), describe the edge cases (like the
# min value, max value, 0, -1). Further, for choices which are not
# obviously named, please describe the affect of each choice.
# Note: this does not replace the need for StrOpt.choices, StrOpt.regex,
# IntOpt.min, etc.
Related options:
# Which other config options have to be considered when I change this
# one? If it stands solely on its own, use "None"
# Note: this does not replace the proposed Opt.related_options, it's used
# when extra details are required.
When reviewing the description of the configuration, it's worth
reviewing the other parameters passed to ``oslo.config``. There have
been features added to make the opt definition more precise, but some
of the options have not been updated since those new features were
added.
We must pay particular attention to:
* Option type: make sure you are using the best type, and in some cases
making better use of custom option types.
* Check if there is any extra options that could be used for that type of
option to help improve the documentation, such as StrOpt.choices, IntOpt.min
* Deprecated: look at deprecating options that are best removed rather than
having the documentation improved. Look at removing options that have been
deprecated for several releases, but not yet removed. Be sure to set the
deprecated_reason setting.
* Look out for bad defaults that force install guides to tell users to set
configuration value because the default would never work. Always optimize the
default for operators rather than the test environment.
(NOTE: This is mostly taken from the cross-project spec [0] and adapted to
Glance)
[0] https://review.openstack.org/#/c/295543/
To manage notifications about this bug go to:
https://bugs.launchpad.net/glance/+bug/1570946/+subscriptions
--
Mailing list: https://launchpad.net/~yahoo-eng-team
Post to : yahoo-eng-team@lists.launchpad.net
Unsubscribe : https://launchpad.net/~yahoo-eng-team
More help : https://help.launchpad.net/ListHelp
