Improve Help Text of Configuration Options in Glance and Glance Store
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
Glance |
Fix Released
|
Wishlist
|
Hemanth Makkapati | ||
glance_store |
Fix Released
|
Wishlist
|
Hemanth Makkapati |
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_
# 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:/
Changed in glance-store: | |
importance: | Undecided → Wishlist |
description: | updated |
Changed in glance-store: | |
assignee: | nobody → Sharat Sharma (sharat-sharma) |
Changed in glance-store: | |
assignee: | Sharat Sharma (sharat-sharma) → nobody |
Changed in glance: | |
status: | New → Fix Released |
Changed in glance-store: | |
status: | New → Fix Released |
Changed in glance: | |
status: | Fix Released → In Progress |
Changed in glance-store: | |
status: | Fix Released → In Progress |
description: | updated |
Changed in glance: | |
status: | In Progress → Fix Released |
Changed in glance-store: | |
status: | In Progress → Fix Released |
Reviewed: https:/ /review. openstack. org/307978 /git.openstack. org/cgit/ openstack/ glance/ commit/ ?id=a37cc47817c cfffc06eb74c692 95ac722a6a85a8
Committed: https:/
Submitter: Jenkins
Branch: master
commit a37cc47817ccfff c06eb74c69295ac 722a6a85a8
Author: Hemanth Makkapati <email address hidden>
Date: Tue Apr 19 13:17:38 2016 -0500
Improve help text of image cache opts
Change-Id: Ifa88896d475a2f ed3003ed68f7aad de7b3c28616
Partial-Bug: #1570946