| 2016-04-15 15:55:37 |
Hemanth Makkapati |
bug |
|
|
added bug |
| 2016-04-15 17:18:35 |
Nikhil Komawar |
bug task added |
|
glance-store |
|
| 2016-04-15 17:18:43 |
Nikhil Komawar |
glance-store: importance |
Undecided |
Wishlist |
|
| 2016-04-20 17:08:24 |
Hemanth Makkapati |
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/ |
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/ |
|
| 2016-05-09 13:05:28 |
Sharat Sharma |
glance-store: assignee |
|
Sharat Sharma (sharat-sharma) |
|
| 2016-05-16 09:14:33 |
Sharat Sharma |
glance-store: assignee |
Sharat Sharma (sharat-sharma) |
|
|
| 2016-05-16 09:14:41 |
Sharat Sharma |
glance: status |
New |
Fix Released |
|
| 2016-05-16 09:14:43 |
Sharat Sharma |
glance-store: status |
New |
Fix Released |
|
| 2016-05-27 17:32:40 |
Hemanth Makkapati |
glance: status |
Fix Released |
In Progress |
|
| 2016-05-27 17:32:43 |
Hemanth Makkapati |
glance-store: status |
Fix Released |
In Progress |
|
| 2016-05-27 17:39:22 |
Hemanth Makkapati |
glance: assignee |
|
Hemanth Makkapati (hemanth-makkapati) |
|
| 2016-05-27 17:39:24 |
Hemanth Makkapati |
glance-store: assignee |
|
Hemanth Makkapati (hemanth-makkapati) |
|
| 2016-07-18 23:54:44 |
Hemanth Makkapati |
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/ |
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/ |
|
| 2016-10-18 19:56:37 |
Hemanth Makkapati |
glance: status |
In Progress |
Fix Released |
|
| 2016-10-18 19:56:41 |
Hemanth Makkapati |
glance-store: status |
In Progress |
Fix Released |
|
