yahoo-eng-team team mailing list archive

[Hemanth Makkapati <hemanth.makkapati@xxxxxxxxxxxxx>]

** Changed in: glance
       Status: Fix Released => In Progress

** Changed in: glance-store
       Status: Fix Released => In Progress

-- 
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:
  In Progress
Status in glance_store:
  In Progress

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.

  Services which consume this:

  # A list of services which consume this option. Operators should not be
  # required to read code to know which one of the services will change its
  # behavior. Nor should they set this in every configuration file to be
  # sure. This can really help deployers understand how the option is used.

  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