)]}'
{"/COMMIT_MSG":[{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8256d5eeaa20fff800a2ce352ea8c6364d2b9a21","unresolved":false,"context_lines":[{"line_number":9,"context_line":"This spec looks at how to get a better configuration option experience"},{"line_number":10,"context_line":"for operators and (to a lesser extent) developers."},{"line_number":11,"context_line":""},{"line_number":12,"context_line":"Co-Authored-By: Ian Cordasco \u003cgraffatcolmingov@gmail.com\u003e"},{"line_number":13,"context_line":""},{"line_number":14,"context_line":"Change-Id: Ib7de142cec88f82eb8bae4696ca5625c383737c1"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":8,"id":"5a18252c_7e8b8168","line":12,"updated":"2016-04-14 14:34:04.000000000","message":"this should be John as Ian owns the changeid (and John could use the credit)","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"}],"specs/categorized-and-centralized-configuration-options.rst":[{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"188cfae7e2c8c9e71a0cf15023031b7fb754205d","unresolved":false,"context_lines":[{"line_number":15,"context_line":"services and libraries close to the code that needs them. Further, operators"},{"line_number":16,"context_line":"tend to have to deal with hundreds of options across several services without"},{"line_number":17,"context_line":"a complete knowledge of how options relate to each other or which services an"},{"line_number":18,"context_line":"option affects. By centralizing configuration options we make it clear that"},{"line_number":19,"context_line":"they are components unto themselves that need careful maintenance and"},{"line_number":20,"context_line":"documentation."},{"line_number":21,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba0121b8_037554f8","line":18,"range":{"start_line":18,"start_character":16,"end_line":18,"end_character":31},"updated":"2016-03-29 10:36:37.000000000","message":"Nit: Centralising is an idea to help understand and tackle the problem. On its own it doesn\u0027t really fix anything.","commit_id":"c1bbd3f27f8a9da9c28bd692b10ed61b6b30f7a0"},{"author":{"_account_id":17860,"name":"Samuel de Medeiros Queiroz","email":"samueldmq@gmail.com","username":"samueldmq"},"change_message_id":"df35d8256c330630fe537894c3fa2cc3110f05c4","unresolved":false,"context_lines":[{"line_number":15,"context_line":"services and libraries close to the code that needs them. Further, operators"},{"line_number":16,"context_line":"tend to have to deal with hundreds of options across several services without"},{"line_number":17,"context_line":"a complete knowledge of how options relate to each other or which services an"},{"line_number":18,"context_line":"option affects. By centralizing configuration options we make it clear that"},{"line_number":19,"context_line":"they are components unto themselves that need careful maintenance and"},{"line_number":20,"context_line":"documentation."},{"line_number":21,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba0121b8_6a5b2088","line":18,"range":{"start_line":18,"start_character":16,"end_line":18,"end_character":31},"in_reply_to":"ba0121b8_037554f8","updated":"2016-03-29 20:03:40.000000000","message":"What do you mean by centralizing the config? Is it about centralizing all services\u0027 configs in a single spot ? Or all the configs of a single service in a single spot within that service?\n\nFor keystone, all the config options are defined in a single place: https://github.com/openstack/keystone/blob/1ab7cd7/keystone/common/config.py","commit_id":"c1bbd3f27f8a9da9c28bd692b10ed61b6b30f7a0"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"188cfae7e2c8c9e71a0cf15023031b7fb754205d","unresolved":false,"context_lines":[{"line_number":19,"context_line":"they are components unto themselves that need careful maintenance and"},{"line_number":20,"context_line":"documentation."},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"While the config reference documentation is an excellent effort, it has been"},{"line_number":23,"context_line":"shown previously in OpenStack that having the documentation live in-line with"},{"line_number":24,"context_line":"the code will ensure that it is updated when the usage in the code changes."},{"line_number":25,"context_line":"This change would be complimentary to the existing config reference work by"},{"line_number":26,"context_line":"that documentation sub-team."},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"Problem description"},{"line_number":29,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba0121b8_63bc106d","line":26,"range":{"start_line":22,"start_character":0,"end_line":26,"end_character":28},"updated":"2016-03-29 10:36:37.000000000","message":"I don\u0027t think we are really changing anything about that. Its mostly auto generated, apart form the over view things, that should stay the same.\n\nWhat we are doing is making sure the auto generated docs and generated sample files are better and more useful.","commit_id":"c1bbd3f27f8a9da9c28bd692b10ed61b6b30f7a0"},{"author":{"_account_id":8726,"name":"Victor Morales","email":"chipahuac@hotmail.com","username":"electrocucaracha"},"change_message_id":"4773861f4cffc58085474ab5dae480269503898f","unresolved":false,"context_lines":[{"line_number":37,"context_line":""},{"line_number":38,"context_line":"- shows their interdependency with other configuration options"},{"line_number":39,"context_line":""},{"line_number":40,"context_line":"- and explains which of the components of the service they influence"},{"line_number":41,"context_line":""},{"line_number":42,"context_line":"Further, config files that are currently generated can not be limited to"},{"line_number":43,"context_line":"options that are absolutely necessary to set, recommended to set, or"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba0121b8_9a26d7b8","line":40,"updated":"2016-03-29 13:46:42.000000000","message":"Having configuration options centralized could help to easily identify deprecated options.","commit_id":"c1bbd3f27f8a9da9c28bd692b10ed61b6b30f7a0"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"188cfae7e2c8c9e71a0cf15023031b7fb754205d","unresolved":false,"context_lines":[{"line_number":42,"context_line":"Further, config files that are currently generated can not be limited to"},{"line_number":43,"context_line":"options that are absolutely necessary to set, recommended to set, or"},{"line_number":44,"context_line":"relatively advanced settings. Operators performing initial deployments to"},{"line_number":45,"context_line":"evaluate a service should be able to determine which options they need to"},{"line_number":46,"context_line":"get the service running. This also includes choosing reasonable defaults"},{"line_number":47,"context_line":"to start with."},{"line_number":48,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba0121b8_fb772400","line":45,"range":{"start_line":45,"start_character":47,"end_line":45,"end_character":60},"updated":"2016-03-29 10:36:37.000000000","message":"You missed out making it clear how they find what the value should be for each option.","commit_id":"c1bbd3f27f8a9da9c28bd692b10ed61b6b30f7a0"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"188cfae7e2c8c9e71a0cf15023031b7fb754205d","unresolved":false,"context_lines":[{"line_number":45,"context_line":"evaluate a service should be able to determine which options they need to"},{"line_number":46,"context_line":"get the service running. This also includes choosing reasonable defaults"},{"line_number":47,"context_line":"to start with."},{"line_number":48,"context_line":""},{"line_number":49,"context_line":"Centralizing and categorizing configuration options also helps downstream"},{"line_number":50,"context_line":"packagers in determining what values can be left as a default and which need a"},{"line_number":51,"context_line":"user to specify."}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba0121b8_db7ea0ad","line":48,"updated":"2016-03-29 10:36:37.000000000","message":"I think we are missing lots of the important details in the use cases presented in the PWG document.\n\nWe could just paste them, verbatim, into here?","commit_id":"c1bbd3f27f8a9da9c28bd692b10ed61b6b30f7a0"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"188cfae7e2c8c9e71a0cf15023031b7fb754205d","unresolved":false,"context_lines":[{"line_number":52,"context_line":""},{"line_number":53,"context_line":"Proposed change"},{"line_number":54,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":55,"context_line":""},{"line_number":56,"context_line":"This specification, the `related user story`_, and its `predecessor in Nova`_,"},{"line_number":57,"context_line":"proposes that each service adopt a ``conf`` sub-module containing modules with"},{"line_number":58,"context_line":"configuration option definitions. Mimicking the Nova specification, this"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba0121b8_db73404c","line":55,"updated":"2016-03-29 10:36:37.000000000","message":"So I think we should turn this upside down, lets talk about the config updates, and the categorization (the more important stuff)\n\nI think we are missing the discussion of olso.config changes and sample file generator changes that set very important context behind this work.\n\nWe can discuss how the Nova team are approach this long term, by doing the centralize work, but thats a per project implementation detail that may or may not be useful to all projects.","commit_id":"c1bbd3f27f8a9da9c28bd692b10ed61b6b30f7a0"},{"author":{"_account_id":6537,"name":"gordon chung","email":"gord@live.ca","username":"chungg"},"change_message_id":"4f4ef63b6ff7bce0251333fb905b48150f13d6a3","unresolved":false,"context_lines":[{"line_number":127,"context_line":"A generic template for help text was provided as part of the Nova"},{"line_number":128,"context_line":"specification and is replicated here for simplicity:"},{"line_number":129,"context_line":""},{"line_number":130,"context_line":".. code::"},{"line_number":131,"context_line":""},{"line_number":132,"context_line":"    # A short description what it does. If it is a unit (e.g. timeout)"},{"line_number":133,"context_line":"    # describe the unit which is used (seconds, megabyte, mebibyte, ...)"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba0121b8_d672d148","line":130,"updated":"2016-03-29 21:35:15.000000000","message":"tbh, it seems like what is mention below is existing functionality in oslo.config.\n\ndescription \u003d\u003d help\nunit \u003d\u003d (need to be added to oslo.config)\nservice which consume \u003d\u003d oslo group\npossible values \u003d\u003d choices\nrelated options \u003d\u003d oslo group? not sure how it\u0027s different from services which consume.","commit_id":"c1bbd3f27f8a9da9c28bd692b10ed61b6b30f7a0"}],"specs/categorized-configuration-options.rst":[{"author":{"_account_id":8726,"name":"Victor Morales","email":"chipahuac@hotmail.com","username":"electrocucaracha"},"change_message_id":"dfa538402d4347f8c10b9f870bb2272537ad542b","unresolved":false,"context_lines":[{"line_number":39,"context_line":"  specify."},{"line_number":40,"context_line":"* As an Operator scaling out a deployment, there should be minimal"},{"line_number":41,"context_line":"  configuration changes required. For the small number of options that must"},{"line_number":42,"context_line":"  be changed, it should be clear what values require tuning, what symptoms are"},{"line_number":43,"context_line":"  caused by incorrect values and how to determine correct values."},{"line_number":44,"context_line":"* As an Operator, the documentation should be clear on the relationship"},{"line_number":45,"context_line":"  between configuration options. For example, if you select driver A by"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_f4186d77","line":42,"range":{"start_line":42,"start_character":66,"end_line":42,"end_character":74},"updated":"2016-03-30 19:51:15.000000000","message":"This opens a lot of user expectations.  From the a weird behavior to a specific error message in log files.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"99600432651008605c2a2a9014fbe919bd9baba7","unresolved":false,"context_lines":[{"line_number":39,"context_line":"  specify."},{"line_number":40,"context_line":"* As an Operator scaling out a deployment, there should be minimal"},{"line_number":41,"context_line":"  configuration changes required. For the small number of options that must"},{"line_number":42,"context_line":"  be changed, it should be clear what values require tuning, what symptoms are"},{"line_number":43,"context_line":"  caused by incorrect values and how to determine correct values."},{"line_number":44,"context_line":"* As an Operator, the documentation should be clear on the relationship"},{"line_number":45,"context_line":"  between configuration options. For example, if you select driver A by"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_0737524d","line":42,"range":{"start_line":42,"start_character":66,"end_line":42,"end_character":74},"in_reply_to":"ba0121b8_f4186d77","updated":"2016-04-01 14:50:48.000000000","message":"yeah, lets say this one is more of a stretch goal, but I like where its pointing.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":20246,"name":"Aradhana Singh","email":"aradhanamailbox@gmail.com","username":"asingh"},"change_message_id":"68d505f4a8c684e4e502c3bdc3c84c7c006d89ff","unresolved":false,"context_lines":[{"line_number":50,"context_line":"  such and presented in such a way as to make the documentation less daunting."},{"line_number":51,"context_line":"  While remaining discoverable it\u0027s possible such options may require the"},{"line_number":52,"context_line":"  operator to review additional documentation to fully understand their impact."},{"line_number":53,"context_line":"* As on Operator doing an initial configuration, it should be easy to check"},{"line_number":54,"context_line":"  that you have a valid configuration file. Checking for any un-recognized"},{"line_number":55,"context_line":"  configuration options and any invalid values can help find typos."},{"line_number":56,"context_line":"* As an Operator that has just completed an upgrade, it should be easy to"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_a10839db","line":53,"range":{"start_line":53,"start_character":5,"end_line":53,"end_character":7},"updated":"2016-03-31 21:07:47.000000000","message":"s/on/an","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":6816,"name":"Jesse Pretorius","email":"jesse@odyssey4.me","username":"jesse-pretorius"},"change_message_id":"8681638455f98c3a336fc07547cae1f4cd79253b","unresolved":false,"context_lines":[{"line_number":109,"context_line":""},{"line_number":110,"context_line":"There are also some other efforts that are related to this work:"},{"line_number":111,"context_line":""},{"line_number":112,"context_line":"* Tool that can be used as part of a DevOps pipeline to validate"},{"line_number":113,"context_line":"  configuration files. It should warn about any deprecated options, and should"},{"line_number":114,"context_line":"  fail on any unrecognized options or options that don\u0027t have a valid value"},{"line_number":115,"context_line":"  (including failing on required options that are not set)."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"Categorizing configuration options"},{"line_number":118,"context_line":"----------------------------------"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_6dd4b646","line":115,"range":{"start_line":112,"start_character":0,"end_line":115,"end_character":59},"updated":"2016-03-30 12:05:24.000000000","message":"It should ideally also (perhaps optionally) warn the user if they\u0027re using an advanced option. This can help when a setting has transitioned from being commonly used to rarely used (perhaps because there\u0027s not a sane default).","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"80b380a876299a0f71535bfea8610264e69eb716","unresolved":false,"context_lines":[{"line_number":109,"context_line":""},{"line_number":110,"context_line":"There are also some other efforts that are related to this work:"},{"line_number":111,"context_line":""},{"line_number":112,"context_line":"* Tool that can be used as part of a DevOps pipeline to validate"},{"line_number":113,"context_line":"  configuration files. It should warn about any deprecated options, and should"},{"line_number":114,"context_line":"  fail on any unrecognized options or options that don\u0027t have a valid value"},{"line_number":115,"context_line":"  (including failing on required options that are not set)."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"Categorizing configuration options"},{"line_number":118,"context_line":"----------------------------------"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_92e4090e","line":115,"range":{"start_line":112,"start_character":0,"end_line":115,"end_character":59},"in_reply_to":"ba0121b8_07d3d2d5","updated":"2016-04-04 20:42:10.000000000","message":"Sorry, must have hit done by accident.  But I agree this is a great idea, maybe an oslo validation script that you supply the configuration file and it will validate it.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"99600432651008605c2a2a9014fbe919bd9baba7","unresolved":false,"context_lines":[{"line_number":109,"context_line":""},{"line_number":110,"context_line":"There are also some other efforts that are related to this work:"},{"line_number":111,"context_line":""},{"line_number":112,"context_line":"* Tool that can be used as part of a DevOps pipeline to validate"},{"line_number":113,"context_line":"  configuration files. It should warn about any deprecated options, and should"},{"line_number":114,"context_line":"  fail on any unrecognized options or options that don\u0027t have a valid value"},{"line_number":115,"context_line":"  (including failing on required options that are not set)."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"Categorizing configuration options"},{"line_number":118,"context_line":"----------------------------------"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_07d3d2d5","line":115,"range":{"start_line":112,"start_character":0,"end_line":115,"end_character":59},"in_reply_to":"ba0121b8_28973bed","updated":"2016-04-01 14:50:48.000000000","message":"oh, thats a nice idea.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"81570f9da599dcec8dee2d29c9b3cea63d8fecba","unresolved":false,"context_lines":[{"line_number":109,"context_line":""},{"line_number":110,"context_line":"There are also some other efforts that are related to this work:"},{"line_number":111,"context_line":""},{"line_number":112,"context_line":"* Tool that can be used as part of a DevOps pipeline to validate"},{"line_number":113,"context_line":"  configuration files. It should warn about any deprecated options, and should"},{"line_number":114,"context_line":"  fail on any unrecognized options or options that don\u0027t have a valid value"},{"line_number":115,"context_line":"  (including failing on required options that are not set)."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"Categorizing configuration options"},{"line_number":118,"context_line":"----------------------------------"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_28973bed","line":115,"range":{"start_line":112,"start_character":0,"end_line":115,"end_character":59},"in_reply_to":"ba0121b8_6dd4b646","updated":"2016-03-30 19:55:05.000000000","message":"Done","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":8726,"name":"Victor Morales","email":"chipahuac@hotmail.com","username":"electrocucaracha"},"change_message_id":"dfa538402d4347f8c10b9f870bb2272537ad542b","unresolved":false,"context_lines":[{"line_number":120,"context_line":"All projects should go through each of their options, looking at which"},{"line_number":121,"context_line":"configuration options should be marked with one of the following:"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"  * Before marking an option as required, we should check that its not"},{"line_number":126,"context_line":"    possible to have a better default, so the operator doesn\u0027t have to set"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_d4df2967","line":123,"range":{"start_line":123,"start_character":4,"end_line":123,"end_character":12},"updated":"2016-03-30 19:51:15.000000000","message":"Isn\u0027t better to have this as opt_category\u003d(required,advanced)?  in that way we can leave the possibility to add more options in future.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"99600432651008605c2a2a9014fbe919bd9baba7","unresolved":false,"context_lines":[{"line_number":120,"context_line":"All projects should go through each of their options, looking at which"},{"line_number":121,"context_line":"configuration options should be marked with one of the following:"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"  * Before marking an option as required, we should check that its not"},{"line_number":126,"context_line":"    possible to have a better default, so the operator doesn\u0027t have to set"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_87524233","line":123,"range":{"start_line":123,"start_character":4,"end_line":123,"end_character":12},"in_reply_to":"ba0121b8_34c14555","updated":"2016-04-01 14:50:48.000000000","message":"we could deprecate the old flags and move to opt_catagory, but thats really details for the oslo.config spec.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"81570f9da599dcec8dee2d29c9b3cea63d8fecba","unresolved":false,"context_lines":[{"line_number":120,"context_line":"All projects should go through each of their options, looking at which"},{"line_number":121,"context_line":"configuration options should be marked with one of the following:"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"  * Before marking an option as required, we should check that its not"},{"line_number":126,"context_line":"    possible to have a better default, so the operator doesn\u0027t have to set"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_34c14555","line":123,"range":{"start_line":123,"start_character":4,"end_line":123,"end_character":12},"in_reply_to":"ba0121b8_d4df2967","updated":"2016-03-30 19:55:05.000000000","message":"This would break a lot of other existing things if we move required, as it is already existing.  Would be better just to tack on and change the generator behavior.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9beceb4d9005cd680917782f934075bd18d6354d","unresolved":false,"context_lines":[{"line_number":131,"context_line":"    operators to work out what value they need to set when doing the initial"},{"line_number":132,"context_line":"    setup of their cloud."},{"line_number":133,"context_line":""},{"line_number":134,"context_line":"* ``advanced\u003dTrue``: this options is very rarely used"},{"line_number":135,"context_line":""},{"line_number":136,"context_line":"  * When marking an option as advanced, we should consider if it is worth"},{"line_number":137,"context_line":"    deprecating and eventually removing the configuration"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_81e8357e","line":134,"range":{"start_line":134,"start_character":37,"end_line":134,"end_character":53},"updated":"2016-04-04 23:44:37.000000000","message":"In OpenStack this is probably not the case due to the million corner cases deviating from the default behavior. TBH I think majority of the current options (at least in Glance) could be easily marked as advanced as they are something most of the deployers does not need to touch anyways.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"6f73a4569e16a3034a17839bd9dc93aeddd94cc4","unresolved":false,"context_lines":[{"line_number":131,"context_line":"    operators to work out what value they need to set when doing the initial"},{"line_number":132,"context_line":"    setup of their cloud."},{"line_number":133,"context_line":""},{"line_number":134,"context_line":"* ``advanced\u003dTrue``: this options is very rarely used"},{"line_number":135,"context_line":""},{"line_number":136,"context_line":"  * When marking an option as advanced, we should consider if it is worth"},{"line_number":137,"context_line":"    deprecating and eventually removing the configuration"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_5caf0494","line":134,"range":{"start_line":134,"start_character":37,"end_line":134,"end_character":53},"in_reply_to":"9a061dce_81e8357e","updated":"2016-04-05 12:54:59.000000000","message":"I am talking about this being something most deployers don\u0027t have to touch, I can reword that.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"ddf63dc16c4de7c421dd6cdf44fe96cf81c9e055","unresolved":false,"context_lines":[{"line_number":136,"context_line":"  * When marking an option as advanced, we should consider if it is worth"},{"line_number":137,"context_line":"    deprecating and eventually removing the configuration"},{"line_number":138,"context_line":""},{"line_number":139,"context_line":"* Review configuration option groups and their descriptions"},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"  * Many options are already in a configuration group. Having a good set of"},{"line_number":142,"context_line":"    groups makes it easier to understand the full list of configuration"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_d7b74f84","line":139,"range":{"start_line":139,"start_character":22,"end_line":139,"end_character":37},"updated":"2016-03-30 12:45:57.000000000","message":"Optional: The OptGroup class also has a \"help\" attribute like the other config options. This can be used to describe the scope of the OptGroup.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"99600432651008605c2a2a9014fbe919bd9baba7","unresolved":false,"context_lines":[{"line_number":136,"context_line":"  * When marking an option as advanced, we should consider if it is worth"},{"line_number":137,"context_line":"    deprecating and eventually removing the configuration"},{"line_number":138,"context_line":""},{"line_number":139,"context_line":"* Review configuration option groups and their descriptions"},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"  * Many options are already in a configuration group. Having a good set of"},{"line_number":142,"context_line":"    groups makes it easier to understand the full list of configuration"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_a72e66a2","line":139,"range":{"start_line":139,"start_character":22,"end_line":139,"end_character":37},"in_reply_to":"ba0121b8_d7b74f84","updated":"2016-04-01 14:50:48.000000000","message":"good point, its probably worth adding that detail.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9beceb4d9005cd680917782f934075bd18d6354d","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"Now any options that are required to be set during the initial setup of the"},{"line_number":157,"context_line":"cloud are clearly marked as such, we can improve the generated sample file."},{"line_number":158,"context_line":"We can move all required options to the top of each configuration group."},{"line_number":159,"context_line":"In addition we can add them into the sample file uncommented, with the"},{"line_number":160,"context_line":"sample_default value very close by in the comment."},{"line_number":161,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_c1250dc3","line":158,"updated":"2016-04-04 23:44:37.000000000","message":"Please no. We just got rid of reordering our sample configs on every single release (or actually every time we made changes to them). This is nightmare for deployers who uses the sample configs as basis for their config templates and tries to keep them up to date between releases.\n\nPersonally I think reordering the config files should be treated always as backwards incompatible API change and done _only_ if there is extremely heavy reasons for it. Not just because \"This would look pretty for Newton cycle\".","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"6f73a4569e16a3034a17839bd9dc93aeddd94cc4","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"Now any options that are required to be set during the initial setup of the"},{"line_number":157,"context_line":"cloud are clearly marked as such, we can improve the generated sample file."},{"line_number":158,"context_line":"We can move all required options to the top of each configuration group."},{"line_number":159,"context_line":"In addition we can add them into the sample file uncommented, with the"},{"line_number":160,"context_line":"sample_default value very close by in the comment."},{"line_number":161,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_7c0da88f","line":158,"in_reply_to":"9a061dce_48ce26b5","updated":"2016-04-05 12:54:59.000000000","message":"The order of the sample file should be irrelavant for most people. For those it matters two need to change how the update the configuration files, and use the more standard ways to update ini files that ship in all the key dev ops tools.\n\nThe names, groups and possible options are totally an API, and we should not change that, unless we have good reason and an upgrade story.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"8f72d3e4c29b220e6924353357a53052e1cec2f3","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"Now any options that are required to be set during the initial setup of the"},{"line_number":157,"context_line":"cloud are clearly marked as such, we can improve the generated sample file."},{"line_number":158,"context_line":"We can move all required options to the top of each configuration group."},{"line_number":159,"context_line":"In addition we can add them into the sample file uncommented, with the"},{"line_number":160,"context_line":"sample_default value very close by in the comment."},{"line_number":161,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"7a1b2928_b9783bfa","line":158,"in_reply_to":"9a061dce_7c0da88f","updated":"2016-04-12 10:33:53.000000000","message":"Markus \u0026 John,\n\ntry to host your config templates based on the example config files with their comments included for example in git repo. Then mix the order of those options around (like config generator did until it got fixed recently) and rebase your templating. Most probably you will have loads of merge conflicts there. Anyone who would like to base their configs on the upstream example configs and keep some level of version control on them will have issue those moving around all the time.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"441efbe3028bb52dbc113cc7f281b65811ec1fce","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"Now any options that are required to be set during the initial setup of the"},{"line_number":157,"context_line":"cloud are clearly marked as such, we can improve the generated sample file."},{"line_number":158,"context_line":"We can move all required options to the top of each configuration group."},{"line_number":159,"context_line":"In addition we can add them into the sample file uncommented, with the"},{"line_number":160,"context_line":"sample_default value very close by in the comment."},{"line_number":161,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_48ce26b5","line":158,"in_reply_to":"9a061dce_c1250dc3","updated":"2016-04-05 11:42:37.000000000","message":"@Erno: I don\u0027t quite get why a change of the order of the options has a negative impact. Are we talking about something like in this example:\n\n    [group_a]\n    opt_a_1 \u003d 1\n    opt_a_2 \u003d 2\n\n    [group_b]\n    opt_b_3 \u003d 3\n    opt_b_4 \u003d 4\n\ngets reordered in a new release to:\n\n    [group_a]\n    opt_a_2 \u003d 2\n    opt_a_1 \u003d 1\n\n    [group_b]\n    opt_b_4 \u003d 4\n    opt_b_3 \u003d 3\n\nIs that already the issue? If \"yes\", then I don\u0027t get the reason. Could you explain the workflow of an deployer here a bit more please?","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"92ee8feaabb7b6cc613e23913faf30cf70812f17","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"Now any options that are required to be set during the initial setup of the"},{"line_number":157,"context_line":"cloud are clearly marked as such, we can improve the generated sample file."},{"line_number":158,"context_line":"We can move all required options to the top of each configuration group."},{"line_number":159,"context_line":"In addition we can add them into the sample file uncommented, with the"},{"line_number":160,"context_line":"sample_default value very close by in the comment."},{"line_number":161,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_a4aef982","line":158,"in_reply_to":"9a061dce_c1250dc3","updated":"2016-04-05 16:46:06.000000000","message":"The order of each section would remain the same.  Inside the section, the point would be to put required options (ones that absolutely need user input/adjustment, i.e. don\u0027t have a usable default) at the top of those sections and uncommented.  This would make it easier to understand what options are absolutely needed to get a service started.\n\nBelow, the advanced options would be treated the opposite.  They would be pushed to the bottom of the section and out of sight for most users that don\u0027t even need such options.  The options are unnecessary ones, optional, and ones that could cause incredible confusion or harm performance/functionality of an installation.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9beceb4d9005cd680917782f934075bd18d6354d","unresolved":false,"context_lines":[{"line_number":161,"context_line":""},{"line_number":162,"context_line":"It is common to add DEPRECATED at the top of the description for deprecated"},{"line_number":163,"context_line":"options. We should get the generator to clearly mark deprecated and advanced"},{"line_number":164,"context_line":"options in the comments in the sample file."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"Now we know about advanced options, for each group of options, we can move"},{"line_number":167,"context_line":"the advanced options to the bottom of the group."}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_a109f933","line":164,"updated":"2016-04-04 23:44:37.000000000","message":"Isn\u0027 this the case already with DEPRECATED?","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"6f73a4569e16a3034a17839bd9dc93aeddd94cc4","unresolved":false,"context_lines":[{"line_number":161,"context_line":""},{"line_number":162,"context_line":"It is common to add DEPRECATED at the top of the description for deprecated"},{"line_number":163,"context_line":"options. We should get the generator to clearly mark deprecated and advanced"},{"line_number":164,"context_line":"options in the comments in the sample file."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"Now we know about advanced options, for each group of options, we can move"},{"line_number":167,"context_line":"the advanced options to the bottom of the group."}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_dc1cb4c3","line":164,"in_reply_to":"9a061dce_a109f933","updated":"2016-04-05 12:54:59.000000000","message":"no, its currently not the case.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9beceb4d9005cd680917782f934075bd18d6354d","unresolved":false,"context_lines":[{"line_number":164,"context_line":"options in the comments in the sample file."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"Now we know about advanced options, for each group of options, we can move"},{"line_number":167,"context_line":"the advanced options to the bottom of the group."},{"line_number":168,"context_line":"Similarly we can move all the deprecated options for each group just above"},{"line_number":169,"context_line":"the list of advanced options."},{"line_number":170,"context_line":"We might want to allow the generator to optionally exclude advanced options."}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_0511d052","line":167,"updated":"2016-04-04 23:44:37.000000000","message":"Please no. For same reasons I mentioned for the required field.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"6f73a4569e16a3034a17839bd9dc93aeddd94cc4","unresolved":false,"context_lines":[{"line_number":164,"context_line":"options in the comments in the sample file."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"Now we know about advanced options, for each group of options, we can move"},{"line_number":167,"context_line":"the advanced options to the bottom of the group."},{"line_number":168,"context_line":"Similarly we can move all the deprecated options for each group just above"},{"line_number":169,"context_line":"the list of advanced options."},{"line_number":170,"context_line":"We might want to allow the generator to optionally exclude advanced options."}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_fc7898f4","line":167,"in_reply_to":"9a061dce_0511d052","updated":"2016-04-05 12:54:59.000000000","message":"I don\u0027t understand your concern on the ordering of the options.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"92ee8feaabb7b6cc613e23913faf30cf70812f17","unresolved":false,"context_lines":[{"line_number":164,"context_line":"options in the comments in the sample file."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"Now we know about advanced options, for each group of options, we can move"},{"line_number":167,"context_line":"the advanced options to the bottom of the group."},{"line_number":168,"context_line":"Similarly we can move all the deprecated options for each group just above"},{"line_number":169,"context_line":"the list of advanced options."},{"line_number":170,"context_line":"We might want to allow the generator to optionally exclude advanced options."}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_e4b631db","line":167,"in_reply_to":"9a061dce_0511d052","updated":"2016-04-05 16:46:06.000000000","message":"Replied to in required options.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9beceb4d9005cd680917782f934075bd18d6354d","unresolved":false,"context_lines":[{"line_number":165,"context_line":""},{"line_number":166,"context_line":"Now we know about advanced options, for each group of options, we can move"},{"line_number":167,"context_line":"the advanced options to the bottom of the group."},{"line_number":168,"context_line":"Similarly we can move all the deprecated options for each group just above"},{"line_number":169,"context_line":"the list of advanced options."},{"line_number":170,"context_line":"We might want to allow the generator to optionally exclude advanced options."},{"line_number":171,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_c546b822","line":168,"updated":"2016-04-04 23:44:37.000000000","message":"DITTO","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"ddf63dc16c4de7c421dd6cdf44fe96cf81c9e055","unresolved":false,"context_lines":[{"line_number":166,"context_line":"Now we know about advanced options, for each group of options, we can move"},{"line_number":167,"context_line":"the advanced options to the bottom of the group."},{"line_number":168,"context_line":"Similarly we can move all the deprecated options for each group just above"},{"line_number":169,"context_line":"the list of advanced options."},{"line_number":170,"context_line":"We might want to allow the generator to optionally exclude advanced options."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"Improving Documentation and Sample file"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_52c6ad48","line":169,"range":{"start_line":169,"start_character":12,"end_line":169,"end_character":28},"updated":"2016-03-30 12:45:57.000000000","message":"So the order within one group will be:\n* required options with default hints\n* \"normal\" options with defaults\n* deprecated options\n* advanced options\n\nIt\u0027s a reasonable order IMO. Maybe we can move the deprecated options before the normal ones. This would make an order of decreasing attention:\n* required options with default hints\n* deprecated options\n* \"normal\" options with defaults\n* advanced options","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"81570f9da599dcec8dee2d29c9b3cea63d8fecba","unresolved":false,"context_lines":[{"line_number":166,"context_line":"Now we know about advanced options, for each group of options, we can move"},{"line_number":167,"context_line":"the advanced options to the bottom of the group."},{"line_number":168,"context_line":"Similarly we can move all the deprecated options for each group just above"},{"line_number":169,"context_line":"the list of advanced options."},{"line_number":170,"context_line":"We might want to allow the generator to optionally exclude advanced options."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"Improving Documentation and Sample file"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_c81b1fc9","line":169,"range":{"start_line":169,"start_character":12,"end_line":169,"end_character":28},"in_reply_to":"ba0121b8_52c6ad48","updated":"2016-03-30 19:55:05.000000000","message":"Done","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9beceb4d9005cd680917782f934075bd18d6354d","unresolved":false,"context_lines":[{"line_number":173,"context_line":"---------------------------------------"},{"line_number":174,"context_line":""},{"line_number":175,"context_line":"The overall aim is operators should not need to read and understand the code"},{"line_number":176,"context_line":"to know how to configure the system. To make this possible we need better"},{"line_number":177,"context_line":"documentation for each configuration option. This spec is focusing on making"},{"line_number":178,"context_line":"sure olso.config has all the information required to generated some good"},{"line_number":179,"context_line":"documentation, and we are not focusing on creating that documentation."},{"line_number":180,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_c55cf827","line":177,"range":{"start_line":176,"start_character":37,"end_line":177,"end_character":44},"updated":"2016-04-04 23:44:37.000000000","message":"I\u0027m surprised if anyone has been blocking documentation improvements of our config options due to lack of spec. Please feel free proposing thise changes, I\u0027m at least happy to review!","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"6f73a4569e16a3034a17839bd9dc93aeddd94cc4","unresolved":false,"context_lines":[{"line_number":173,"context_line":"---------------------------------------"},{"line_number":174,"context_line":""},{"line_number":175,"context_line":"The overall aim is operators should not need to read and understand the code"},{"line_number":176,"context_line":"to know how to configure the system. To make this possible we need better"},{"line_number":177,"context_line":"documentation for each configuration option. This spec is focusing on making"},{"line_number":178,"context_line":"sure olso.config has all the information required to generated some good"},{"line_number":179,"context_line":"documentation, and we are not focusing on creating that documentation."},{"line_number":180,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_bc8aa0bd","line":177,"range":{"start_line":176,"start_character":37,"end_line":177,"end_character":44},"in_reply_to":"9a061dce_c55cf827","updated":"2016-04-05 12:54:59.000000000","message":"This is about a concerted effort to review them, and improve them where needed.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":20246,"name":"Aradhana Singh","email":"aradhanamailbox@gmail.com","username":"asingh"},"change_message_id":"68d505f4a8c684e4e502c3bdc3c84c7c006d89ff","unresolved":false,"context_lines":[{"line_number":175,"context_line":"The overall aim is operators should not need to read and understand the code"},{"line_number":176,"context_line":"to know how to configure the system. To make this possible we need better"},{"line_number":177,"context_line":"documentation for each configuration option. This spec is focusing on making"},{"line_number":178,"context_line":"sure olso.config has all the information required to generated some good"},{"line_number":179,"context_line":"documentation, and we are not focusing on creating that documentation."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"Most importantly, we need a good description for each of the configuration"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_a12f993d","line":178,"range":{"start_line":178,"start_character":53,"end_line":178,"end_character":62},"updated":"2016-03-31 21:07:47.000000000","message":"s/generated/generate","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":20246,"name":"Aradhana Singh","email":"aradhanamailbox@gmail.com","username":"asingh"},"change_message_id":"4b4ce5071a503c887efbeb5b15f36ad3cf7041f3","unresolved":false,"context_lines":[{"line_number":176,"context_line":"to know how to configure the system. To make this possible we need better"},{"line_number":177,"context_line":"documentation for each configuration option. This spec is focusing on making"},{"line_number":178,"context_line":"sure olso.config has all the information required to generated some good"},{"line_number":179,"context_line":"documentation, and we are not focusing on creating that documentation."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"Most importantly, we need a good description for each of the configuration"},{"line_number":182,"context_line":"options. This means developers reviewing the configuration option descriptions"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_670e433c","line":179,"range":{"start_line":179,"start_character":19,"end_line":179,"end_character":21},"updated":"2016-03-31 16:04:29.000000000","message":"\"we\"? is it for \"operators\" or \"developers\"","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"99600432651008605c2a2a9014fbe919bd9baba7","unresolved":false,"context_lines":[{"line_number":176,"context_line":"to know how to configure the system. To make this possible we need better"},{"line_number":177,"context_line":"documentation for each configuration option. This spec is focusing on making"},{"line_number":178,"context_line":"sure olso.config has all the information required to generated some good"},{"line_number":179,"context_line":"documentation, and we are not focusing on creating that documentation."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"Most importantly, we need a good description for each of the configuration"},{"line_number":182,"context_line":"options. This means developers reviewing the configuration option descriptions"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_f2a65a0d","line":179,"range":{"start_line":179,"start_character":19,"end_line":179,"end_character":21},"in_reply_to":"ba0121b8_670e433c","updated":"2016-04-01 14:50:48.000000000","message":"I was meaning those folks working on the spec, but I should clarify.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9beceb4d9005cd680917782f934075bd18d6354d","unresolved":false,"context_lines":[{"line_number":197,"context_line":"    # A list of services which consume this option. Operators should not be"},{"line_number":198,"context_line":"    # required to read code to know which one of the services will change its"},{"line_number":199,"context_line":"    # behavior. Nor should they set this in every ``nova.conf`` file to be"},{"line_number":200,"context_line":"    # sure."},{"line_number":201,"context_line":""},{"line_number":202,"context_line":"    Possible values:"},{"line_number":203,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_25733482","line":200,"updated":"2016-04-04 23:44:37.000000000","message":"This seems to be only problem for the services utilizing common config file. Again good reason why not to go for such.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"6f73a4569e16a3034a17839bd9dc93aeddd94cc4","unresolved":false,"context_lines":[{"line_number":197,"context_line":"    # A list of services which consume this option. Operators should not be"},{"line_number":198,"context_line":"    # required to read code to know which one of the services will change its"},{"line_number":199,"context_line":"    # behavior. Nor should they set this in every ``nova.conf`` file to be"},{"line_number":200,"context_line":"    # sure."},{"line_number":201,"context_line":""},{"line_number":202,"context_line":"    Possible values:"},{"line_number":203,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_1c674c26","line":200,"in_reply_to":"9a061dce_25733482","updated":"2016-04-05 12:54:59.000000000","message":"Separating them into specific config files is fine, thats an alternative implementation for achieving the same goal.\n\nThe key point here is being clear what consues them.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"ddf63dc16c4de7c421dd6cdf44fe96cf81c9e055","unresolved":false,"context_lines":[{"line_number":213,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":214,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":215,"context_line":"    # Note: this does not replace the new Opt.related_options, it used"},{"line_number":216,"context_line":"    # when extra details are required."},{"line_number":217,"context_line":""},{"line_number":218,"context_line":"When reviewing the description of the configuration, its worth reviewing the"},{"line_number":219,"context_line":"other parameters passed to ``oslo.config``. There have been features added to"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_d7fe2837","line":216,"range":{"start_line":216,"start_character":11,"end_line":216,"end_character":37},"updated":"2016-03-30 12:45:57.000000000","message":"Especially when the relationship is between config options from different groups. For example in Nova, the \"ssl\" and \"cert\" options from the \"default\" group influence the behavior of the proxy services \"base_url\" (http \u003c-\u003e https).","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":20246,"name":"Aradhana Singh","email":"aradhanamailbox@gmail.com","username":"asingh"},"change_message_id":"68d505f4a8c684e4e502c3bdc3c84c7c006d89ff","unresolved":false,"context_lines":[{"line_number":217,"context_line":""},{"line_number":218,"context_line":"When reviewing the description of the configuration, its worth reviewing the"},{"line_number":219,"context_line":"other parameters passed to ``oslo.config``. There have been features added to"},{"line_number":220,"context_line":"make the opt definition more precise, many may have been added since the opt"},{"line_number":221,"context_line":"was added. You should pay particular attention to:"},{"line_number":222,"context_line":""},{"line_number":223,"context_line":"* Option type: make sure you are using the best type"},{"line_number":224,"context_line":"* Check if there is any extra options that could be used for that type of"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_1c2a2adb","line":221,"range":{"start_line":220,"start_character":38,"end_line":221,"end_character":9},"updated":"2016-03-31 21:07:47.000000000","message":"its unclear whether the features have been added because of the usage of \"may have\". My suggestion would be make this sentence close ended.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"ddf63dc16c4de7c421dd6cdf44fe96cf81c9e055","unresolved":false,"context_lines":[{"line_number":220,"context_line":"make the opt definition more precise, many may have been added since the opt"},{"line_number":221,"context_line":"was added. You should pay particular attention to:"},{"line_number":222,"context_line":""},{"line_number":223,"context_line":"* Option type: make sure you are using the best type"},{"line_number":224,"context_line":"* Check if there is any extra options that could be used for that type of"},{"line_number":225,"context_line":"  option to help improve the documentation, such as StrOpt.choices, IntOpt.min"},{"line_number":226,"context_line":"* Deprecated: look at deprecating options that are best removed rather than"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_2278042a","line":223,"range":{"start_line":223,"start_character":43,"end_line":223,"end_character":52},"updated":"2016-03-30 12:45:57.000000000","message":"Using custom types should be considered as well. I still have to evaluate how the custom types behave. Right now (in Nova) we often use \"MultiStrOpt\" when a custom type would fit better. For example the \"pci_passthrough_whitelist\" option which is pretty complex.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9beceb4d9005cd680917782f934075bd18d6354d","unresolved":false,"context_lines":[{"line_number":231,"context_line":"  configuration value because the default would never work. Always optimize"},{"line_number":232,"context_line":"  the default for operators rather than the test environment."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Centralize Configuration options"},{"line_number":235,"context_line":"--------------------------------"},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"This specification\u0027s `predecessor in Nova`_ proposes that each service adopt a"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_6591ac99","line":234,"updated":"2016-04-04 23:44:37.000000000","message":"Personally I think this is directly opposite what the goal was set at the start of this spec.\n\nI think centralizing the config options does not only make it more difficult for developers (which weirdly seems to be the goal here) but also makes it more tempting to not document the configs properly and just direct the operator/\"general public\" to the config module for more information.\n\nSome way this looks to be driven by the bad decision made to remove example configs from lots of project repos and now there has been realized need for that again so there is online resource where one can go and look for the configs. Well bring back the example configs and we do not need to point people looking the code defining the options.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"6f73a4569e16a3034a17839bd9dc93aeddd94cc4","unresolved":false,"context_lines":[{"line_number":231,"context_line":"  configuration value because the default would never work. Always optimize"},{"line_number":232,"context_line":"  the default for operators rather than the test environment."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Centralize Configuration options"},{"line_number":235,"context_line":"--------------------------------"},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"This specification\u0027s `predecessor in Nova`_ proposes that each service adopt a"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_7c3c88e2","line":234,"in_reply_to":"9a061dce_14c8ca21","updated":"2016-04-05 12:54:59.000000000","message":"+1 to markus_z\u0027s points here.\n\nThis is not trying to kill the docs, this is trying to help the docs. This has apparently worked out quite well for keystone.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"441efbe3028bb52dbc113cc7f281b65811ec1fce","unresolved":false,"context_lines":[{"line_number":231,"context_line":"  configuration value because the default would never work. Always optimize"},{"line_number":232,"context_line":"  the default for operators rather than the test environment."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Centralize Configuration options"},{"line_number":235,"context_line":"--------------------------------"},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"This specification\u0027s `predecessor in Nova`_ proposes that each service adopt a"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_14c8ca21","line":234,"in_reply_to":"9a061dce_456e1602","updated":"2016-04-05 11:42:37.000000000","message":"@Erno: The place we (Nova folks) point people to is the  \"nova.conf.sample\" at [1] or the \"configuration reference\" guide [2], both generated from the code. The sample file is automatically up-to-date with each merged commit, the guide gets manually updated with each release. There is absolutely no need to look into the code if we write a proper config option help text. The in-tree organization of the config options at a central place was/is a means to:\n\n* encourage a common style with exhaustive information\n  of the help text\n* make the developer see the options from the point of view\n  of the ops (no context given by the functional code\n  which uses an option).\n* make removal of once deprecated options easier\n* make developers think twice if it is really necessary \n  to add even more config options.\n* make developers check if there is possibly already\n  another config option which does the same\n\nAgain, I can only talk for Nova, we take the standard-deprecation-policy [3] seriously. I left a question at line 158 about the order of options.\n\nReferences:\n[1] http://docs.openstack.org/developer/nova/sample_config.html\n[2] http://docs.openstack.org/mitaka/config-reference/compute/config-options.html\n[3] http://governance.openstack.org/reference/tags/assert_follows-standard-deprecation.html","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"517dbc1c927b562fb10ade6f58c5716e41ed93b1","unresolved":false,"context_lines":[{"line_number":231,"context_line":"  configuration value because the default would never work. Always optimize"},{"line_number":232,"context_line":"  the default for operators rather than the test environment."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Centralize Configuration options"},{"line_number":235,"context_line":"--------------------------------"},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"This specification\u0027s `predecessor in Nova`_ proposes that each service adopt a"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_b36e5dc7","line":234,"in_reply_to":"9a061dce_6591ac99","updated":"2016-04-05 09:02:36.000000000","message":"@Erno: The goal is to provide better documentation of the config options for ops/deployers. Having the options near the code which uses them makes it tempting for developers to omit documentation, because the code is \"just a few lines away\". Having a \"distance\" between the config options and the code which uses them enables the developers to see that option from an ops perspective. Then we can treat them like the interface they are, with the same demand of quality like the REST API. \nTo be honest, I don\u0027t know how it was done with the \"example config\" files. That\u0027s before I started with Nova.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"dd88b92a79989d36ad346195fd6e6b11ac0d4236","unresolved":false,"context_lines":[{"line_number":231,"context_line":"  configuration value because the default would never work. Always optimize"},{"line_number":232,"context_line":"  the default for operators rather than the test environment."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Centralize Configuration options"},{"line_number":235,"context_line":"--------------------------------"},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"This specification\u0027s `predecessor in Nova`_ proposes that each service adopt a"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a061dce_456e1602","line":234,"in_reply_to":"9a061dce_b36e5dc7","updated":"2016-04-05 10:15:53.000000000","message":"Markus, So for example Glance still carries example configs for this exact reason, to have the config options documented in tree: https://github.com/openstack/glance/blob/master/etc/glance-api.conf\n\n\nLines 28-30 of this spec clearly indicates that ops/deployers should not need to dig into the code for this purpose. I think the end result of this proposal will kill that. Because the config options are on central location of the code \"there is no need for documentation because we can just direct to that module/package\".\n\n\nOur RESTful APIs are not treated with the \"immutability\" and respect they have because they are defined in specific files, they are treated such because they are what they are. We need to grow into the mindset where config options (and specially the files rendered from them) stays stable and well documented and I don\u0027t think this is the right approach towards that.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"ddf63dc16c4de7c421dd6cdf44fe96cf81c9e055","unresolved":false,"context_lines":[{"line_number":234,"context_line":"Centralize Configuration options"},{"line_number":235,"context_line":"--------------------------------"},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"This specification\u0027s `predecessor in Nova`_ proposes that each service adopt a"},{"line_number":238,"context_line":"``conf`` sub-module containing modules with configuration option definitions."},{"line_number":239,"context_line":"While not directly impacting the deployers experience, this has proved a"},{"line_number":240,"context_line":"useful way to help developers consider the configuration options as a whole,"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_22e764b1","line":237,"range":{"start_line":237,"start_character":63,"end_line":237,"end_character":70},"updated":"2016-03-30 12:45:57.000000000","message":"\"project\"?","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"99600432651008605c2a2a9014fbe919bd9baba7","unresolved":false,"context_lines":[{"line_number":234,"context_line":"Centralize Configuration options"},{"line_number":235,"context_line":"--------------------------------"},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"This specification\u0027s `predecessor in Nova`_ proposes that each service adopt a"},{"line_number":238,"context_line":"``conf`` sub-module containing modules with configuration option definitions."},{"line_number":239,"context_line":"While not directly impacting the deployers experience, this has proved a"},{"line_number":240,"context_line":"useful way to help developers consider the configuration options as a whole,"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_12f2ee05","line":237,"range":{"start_line":237,"start_character":63,"end_line":237,"end_character":70},"in_reply_to":"ba0121b8_22e764b1","updated":"2016-04-01 14:50:48.000000000","message":"oh, yeah, thats better.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"ddf63dc16c4de7c421dd6cdf44fe96cf81c9e055","unresolved":false,"context_lines":[{"line_number":239,"context_line":"While not directly impacting the deployers experience, this has proved a"},{"line_number":240,"context_line":"useful way to help developers consider the configuration options as a whole,"},{"line_number":241,"context_line":"rather than in a more piecemeal way."},{"line_number":242,"context_line":"In particular, Nova has structured their configuration centralization like so:"},{"line_number":243,"context_line":""},{"line_number":244,"context_line":".. code::"},{"line_number":245,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_3d2ae57e","line":242,"range":{"start_line":242,"start_character":55,"end_line":242,"end_character":69},"updated":"2016-03-30 12:45:57.000000000","message":"The \"distance\" to the code where it gets used also forces the developers who introduce new config options to write the help text from the perspective of an operator/packager.","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"ddf63dc16c4de7c421dd6cdf44fe96cf81c9e055","unresolved":false,"context_lines":[{"line_number":270,"context_line":"This provides a simple and uniform interface to configuration options while"},{"line_number":271,"context_line":"avoiding potential problems references in the `original mailing list thread`_"},{"line_number":272,"context_line":"with circular dependencies caused by ``import_opt``."},{"line_number":273,"context_line":""},{"line_number":274,"context_line":"Alternatives"},{"line_number":275,"context_line":"------------"},{"line_number":276,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba0121b8_1dc60148","line":273,"updated":"2016-03-30 12:45:57.000000000","message":"We also use a \"single point of entry\" for the generation of the sample config file which enforces a specific interface [1]. This ensures that new modules will keep the contract, otherwise the doc testing job fails. \n\nThe same technique could be used for the \"__init__.py\" module which registers all config options. This would also lead to less merge conflicts when a project starts with the transition.\n\n[1] https://github.com/openstack/nova/blob/master/nova/conf/opts.py","commit_id":"a6c30808772e55c3c9fcaa82293492cb79d4065c"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":34,"context_line":"* As an Operator doing an initial deployment, I should be able to quickly"},{"line_number":35,"context_line":"  identify what configurations I must consider, and how I should determine"},{"line_number":36,"context_line":"  their value for my deployment to be successful."},{"line_number":37,"context_line":"* As a Packager, I should be able to quickly identify what configurations"},{"line_number":38,"context_line":"  options the packaging must set, and what options the operator needs to"},{"line_number":39,"context_line":"  specify."},{"line_number":40,"context_line":"* As an Operator scaling out a deployment, there should be minimal"}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_8da3514f","line":37,"updated":"2016-04-08 23:11:35.000000000","message":"nit: configuration","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":47,"context_line":"* There may be some options that are very unlikely to be used, except by the"},{"line_number":48,"context_line":"  most advanced users. By default, these advanced options should be marked as"},{"line_number":49,"context_line":"  such and presented in such a way as to make the documentation less daunting."},{"line_number":50,"context_line":"  While remaining discoverable it\u0027s possible such options may require the"},{"line_number":51,"context_line":"  operator to review additional documentation to fully understand their impact."},{"line_number":52,"context_line":"* As an Operator doing an initial configuration, it should be easy to check"},{"line_number":53,"context_line":"  that you have a valid configuration file. Checking for any un-recognized"}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_adb5757f","line":50,"updated":"2016-04-08 23:11:35.000000000","message":"nit: i *think* this should have a comma?\n\n  discoverable,","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":67,"context_line":"* Creating new configuration options, when it would be better to use an"},{"line_number":68,"context_line":"  existing configuration"},{"line_number":69,"context_line":"* Not including information about the dependencies between other options that"},{"line_number":70,"context_line":"  are defined elsewhere in the code base."},{"line_number":71,"context_line":""},{"line_number":72,"context_line":"In short, we really need to consider our configuration options together as a"},{"line_number":73,"context_line":"formal contract or API that we expose to operators. We have already"}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_ed248dc7","line":70,"updated":"2016-04-08 23:11:35.000000000","message":"nit: I think should clarify *where* this information *should* be included (I\u0027m assuming in the description, as opposed to some new attribute in oslo.config).","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":67,"context_line":"* Creating new configuration options, when it would be better to use an"},{"line_number":68,"context_line":"  existing configuration"},{"line_number":69,"context_line":"* Not including information about the dependencies between other options that"},{"line_number":70,"context_line":"  are defined elsewhere in the code base."},{"line_number":71,"context_line":""},{"line_number":72,"context_line":"In short, we really need to consider our configuration options together as a"},{"line_number":73,"context_line":"formal contract or API that we expose to operators. We have already"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_8422efff","line":70,"in_reply_to":"5a18252c_c10d9fe9","updated":"2016-04-19 11:46:24.000000000","message":"+1 alexis\u0027 comments.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":67,"context_line":"* Creating new configuration options, when it would be better to use an"},{"line_number":68,"context_line":"  existing configuration"},{"line_number":69,"context_line":"* Not including information about the dependencies between other options that"},{"line_number":70,"context_line":"  are defined elsewhere in the code base."},{"line_number":71,"context_line":""},{"line_number":72,"context_line":"In short, we really need to consider our configuration options together as a"},{"line_number":73,"context_line":"formal contract or API that we expose to operators. We have already"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_c10d9fe9","line":70,"in_reply_to":"9a061dce_ed248dc7","updated":"2016-04-14 14:32:54.000000000","message":"I respectfully disagree - this is the Problem Description. Proposed Changes go into the next section.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":69,"context_line":"* Not including information about the dependencies between other options that"},{"line_number":70,"context_line":"  are defined elsewhere in the code base."},{"line_number":71,"context_line":""},{"line_number":72,"context_line":"In short, we really need to consider our configuration options together as a"},{"line_number":73,"context_line":"formal contract or API that we expose to operators. We have already"},{"line_number":74,"context_line":"established norms across upgrades for renames and removals of configuration"},{"line_number":75,"context_line":"options. We now need to look at establishing patterns of configuration option"},{"line_number":76,"context_line":"usage that will help manage the complexity of our configuration options."}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_c37abe87","line":73,"range":{"start_line":72,"start_character":10,"end_line":73,"end_character":22},"updated":"2016-04-14 14:32:54.000000000","message":"This would be good to add to the overview, it\u0027s important.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":69,"context_line":"* Not including information about the dependencies between other options that"},{"line_number":70,"context_line":"  are defined elsewhere in the code base."},{"line_number":71,"context_line":""},{"line_number":72,"context_line":"In short, we really need to consider our configuration options together as a"},{"line_number":73,"context_line":"formal contract or API that we expose to operators. We have already"},{"line_number":74,"context_line":"established norms across upgrades for renames and removals of configuration"},{"line_number":75,"context_line":"options. We now need to look at establishing patterns of configuration option"},{"line_number":76,"context_line":"usage that will help manage the complexity of our configuration options."}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_0416dfa6","line":73,"range":{"start_line":72,"start_character":10,"end_line":73,"end_character":22},"in_reply_to":"5a18252c_c37abe87","updated":"2016-04-19 11:46:24.000000000","message":"I like that idea.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":73,"context_line":"formal contract or API that we expose to operators. We have already"},{"line_number":74,"context_line":"established norms across upgrades for renames and removals of configuration"},{"line_number":75,"context_line":"options. We now need to look at establishing patterns of configuration option"},{"line_number":76,"context_line":"usage that will help manage the complexity of our configuration options."},{"line_number":77,"context_line":""},{"line_number":78,"context_line":"Proposed change"},{"line_number":79,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_21a9f37b","line":76,"updated":"2016-04-14 14:32:54.000000000","message":"nit: this para is about what we should do, not the problem, ergo it\u0027s part of the Proposed Change","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":73,"context_line":"formal contract or API that we expose to operators. We have already"},{"line_number":74,"context_line":"established norms across upgrades for renames and removals of configuration"},{"line_number":75,"context_line":"options. We now need to look at establishing patterns of configuration option"},{"line_number":76,"context_line":"usage that will help manage the complexity of our configuration options."},{"line_number":77,"context_line":""},{"line_number":78,"context_line":"Proposed change"},{"line_number":79,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_e44ac3c4","line":76,"in_reply_to":"5a18252c_21a9f37b","updated":"2016-04-19 11:46:24.000000000","message":"true, lets drop this.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":93,"context_line":"that is currently under discussion within ``oslo.config``, in particular:"},{"line_number":94,"context_line":""},{"line_number":95,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/advanced-option"},{"line_number":96,"context_line":"  Mark options as \"advanced\" so its clear which options are rarely used"},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_083e05b8","line":96,"updated":"2016-04-08 23:11:35.000000000","message":"nit: it\u0027s (same goes for L127, L132, L216 as well)","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":93,"context_line":"that is currently under discussion within ``oslo.config``, in particular:"},{"line_number":94,"context_line":""},{"line_number":95,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/advanced-option"},{"line_number":96,"context_line":"  Mark options as \"advanced\" so its clear which options are rarely used"},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_e92241a2","line":96,"in_reply_to":"5a18252c_2c30ec9d","updated":"2016-04-14 14:32:54.000000000","message":"I\u0027d prefer this but it seems tricky to manage migration? Supposing I set option \u0027vmware.foo\u0027 which becomes \u0027advanced_vmware.foo\u0027 in the next release. I must modify my config so the setting is still retained. Unless we can do cross-group deprecated names?\n\nIf we do go with the \u0027advanced\u0027 property, we can generate a \"service.conf\" and a \"service_advanced.conf\" each with a vmware section and the options partitioned appropriately. This seems clear enough to me? Old conf files in the merged style will continue to work and operators can transition or not as they choose.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"831008aebca719849c43d4ecc4962c90b248959f","unresolved":false,"context_lines":[{"line_number":93,"context_line":"that is currently under discussion within ``oslo.config``, in particular:"},{"line_number":94,"context_line":""},{"line_number":95,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/advanced-option"},{"line_number":96,"context_line":"  Mark options as \"advanced\" so its clear which options are rarely used"},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_2e7bbbf6","line":96,"in_reply_to":"5a18252c_2c30ec9d","updated":"2016-04-14 03:33:41.000000000","message":"This also has to do with placement, pushing the more uncommon advanced options down the bottom of the namespace.  This will keep what is absolutely relevant to the majority of users up top and clearly accessible, with an understanding that these are the options that you should mostly be concerned with.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":93,"context_line":"that is currently under discussion within ``oslo.config``, in particular:"},{"line_number":94,"context_line":""},{"line_number":95,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/advanced-option"},{"line_number":96,"context_line":"  Mark options as \"advanced\" so its clear which options are rarely used"},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_264f686c","line":96,"in_reply_to":"5a18252c_5c2a0891","updated":"2016-04-19 11:46:24.000000000","message":"@Doug, thats an interesting idea, but I am not sure it lets us do things like have a toggle to hide things in the docs. I mean we could use convention to find them, but it feels hacky.\n\nRegardless, it might be a good way to try identifying the advance options, and if that proves its useful, and we need something more formal, we could reconsider adding \"advanced\u003dtrue\".\n\nI will add something into the alternatives section to capture the idea.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"733f3ec49e90786acee6b4986c258d09f99f41b2","unresolved":false,"context_lines":[{"line_number":93,"context_line":"that is currently under discussion within ``oslo.config``, in particular:"},{"line_number":94,"context_line":""},{"line_number":95,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/advanced-option"},{"line_number":96,"context_line":"  Mark options as \"advanced\" so its clear which options are rarely used"},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_5c2a0891","line":96,"in_reply_to":"5a18252c_e92241a2","updated":"2016-04-14 16:45:04.000000000","message":"@Alexis, options can be renamed across groups. It\u0027s also possible to generate the separate config files you suggest using features we have now, without changing the config generator to support the advanced flag.\n\n@Brian, careful group name selection will have the ordering effect you want, since the config generator sorts the groups it finds so the output is deterministic.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":93,"context_line":"that is currently under discussion within ``oslo.config``, in particular:"},{"line_number":94,"context_line":""},{"line_number":95,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/advanced-option"},{"line_number":96,"context_line":"  Mark options as \"advanced\" so its clear which options are rarely used"},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_2c30ec9d","line":96,"in_reply_to":"9a061dce_083e05b8","updated":"2016-04-13 22:27:29.000000000","message":"As an alternative to adding a new parameter to each option, advanced options could be placed in their own group within the configuration file. That group could then have it\u0027s own special help text elaborating on when it is useful to use the group of options.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":95,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/advanced-option"},{"line_number":96,"context_line":"  Mark options as \"advanced\" so its clear which options are rarely used"},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"},{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_e9ea4173","line":98,"range":{"start_line":98,"start_character":2,"end_line":98,"end_character":68},"updated":"2016-04-14 14:32:54.000000000","message":"nit: can you url-encode the + so these links work please?","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"},{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_0c1c1011","line":101,"updated":"2016-04-13 22:27:29.000000000","message":"Again, we already have a grouping mechanism. Let\u0027s use that to combine related options.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"733f3ec49e90786acee6b4986c258d09f99f41b2","unresolved":false,"context_lines":[{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"},{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_5746634f","line":101,"in_reply_to":"5a18252c_090a1d79","updated":"2016-04-14 16:45:04.000000000","message":"We also want an example of a reference to all of the options in a group (\"if you set the driver to X, you should fill in the driver_X options\"). The number of variations on that are why I think it\u0027s better to use comments for the relationships.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":1297,"name":"Joshua Harlow","email":"jxharlow@godaddy.com","username":"harlowja"},"change_message_id":"4bbe2c661247b4fe1e9c963368d2bc76dff01f43","unresolved":false,"context_lines":[{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"},{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_6558368b","line":101,"in_reply_to":"5a18252c_0c1c1011","updated":"2016-04-14 01:42:51.000000000","message":"Agreed, is the group mechanism not good enough here, or is the relationship trying to establish a non-groupable concept? The blueprint seems to mention that it\u0027s almost like an \u0027also affects\u0027 relationship but not so strongly that they should be in the same group. Is that correct?","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"d9475697074052e3602554bc0d5a1b0247ff765f","unresolved":false,"context_lines":[{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"},{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_b7537638","line":101,"in_reply_to":"5a18252c_5746634f","updated":"2016-04-14 16:59:31.000000000","message":"Ok if the community thinks this is the best path, then let\u0027s drop this blueprint and modify this spec, place everything in help text regarding this.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"831008aebca719849c43d4ecc4962c90b248959f","unresolved":false,"context_lines":[{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"},{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_6e33f362","line":101,"in_reply_to":"5a18252c_6558368b","updated":"2016-04-14 03:33:41.000000000","message":"Correct, this is an \"also affects\" type of relationship rather than a grouping.  It\u0027s a, if you set A, you might need to look at B, C, and D, even if they are not logically in the same group.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"},{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_090a1d79","line":101,"in_reply_to":"5a18252c_6e33f362","updated":"2016-04-14 14:32:54.000000000","message":"For example, many options (EG scheduler_host_subset_size) within Nova\u0027s [scheduler] group are-affected-by \"scheduler_driver\" since they only apply if \"scheduler_driver\u003dFilterScheduler\".\n\nThe blueprint only relates by name, please can you give an example of a trans-group relation?","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":98,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/related-options"},{"line_number":99,"context_line":"  Allow opts to define what options they are related to. The description"},{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_239d9abc","line":101,"in_reply_to":"5a18252c_b7537638","updated":"2016-04-19 11:46:24.000000000","message":"The problem with the comments and grouping, is we can\u0027t have links between the options in the documentation. Its not terribly important, but it does seem useful.\n\nThis is not a key dependency of this spec, we could drop this, if the consensus is that is not worth the effort.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_4c3c23c8","line":103,"range":{"start_line":103,"start_character":2,"end_line":103,"end_character":82},"updated":"2016-04-14 14:32:54.000000000","message":"the problem this addresses isn\u0027t clear to me. I\u0027d prefer each of these blueprints had a mini-spec with Problem Description and Proposed Change. This would allow us to make comments and revisions. Also specs get published.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"d9475697074052e3602554bc0d5a1b0247ff765f","unresolved":false,"context_lines":[{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_579dc208","line":103,"range":{"start_line":103,"start_character":2,"end_line":103,"end_character":82},"in_reply_to":"5a18252c_4c3c23c8","updated":"2016-04-14 16:59:31.000000000","message":"So, this spec is supposed to address this, if it\u0027s not, we should expand on this spec rather than creating something else.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":100,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_06a22cfd","line":103,"range":{"start_line":103,"start_character":2,"end_line":103,"end_character":82},"in_reply_to":"5a18252c_579dc208","updated":"2016-04-19 11:46:24.000000000","message":"We are missing context here, I will add some.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":107,"context_line":"  Uncomment required configurations in the generated sample file"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_4c89e825","line":104,"updated":"2016-04-13 22:27:29.000000000","message":"The intent of the sample_default parameter is to provide a value when no valid default can be pre-defined, so the operator *must* provide a value and we know the form of that value but not an actual value or where the actual value is computed at runtime.\n\nIf we have an example of an option that is using a valid, static, default and sample_default together, I think that\u0027s a bug in the configuration option definition.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":107,"context_line":"  Uncomment required configurations in the generated sample file"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_2360faa4","line":104,"in_reply_to":"5a18252c_17c98a26","updated":"2016-04-19 11:46:24.000000000","message":"So I am going to drop this one, and role it into the blueprint below, coverving the more general intent around a generator option that helps deployers create their initial configuration file.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"831008aebca719849c43d4ecc4962c90b248959f","unresolved":false,"context_lines":[{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":107,"context_line":"  Uncomment required configurations in the generated sample file"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_aedd0be2","line":104,"in_reply_to":"5a18252c_4c89e825","updated":"2016-04-14 03:33:41.000000000","message":"Agreed, the intent of sample_default is to accomplish this but it\u0027s not clear that this is what is accomplished.  In the sample files, the sampe_default presents itself as the default.\n\nThis would more clearly define that this is a sample/example of what might be expected, with a clear way to understand that there is in fact not a default.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"d9475697074052e3602554bc0d5a1b0247ff765f","unresolved":false,"context_lines":[{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":107,"context_line":"  Uncomment required configurations in the generated sample file"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_17c98a26","line":104,"in_reply_to":"5a18252c_77e55f36","updated":"2016-04-14 16:59:31.000000000","message":"Correct we are trying to move toward a more \"minimally useful\" configuration.  My only thought is we present samples that can be used, which lends itself more toward a reference rather than something that can be at least functional.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"733f3ec49e90786acee6b4986c258d09f99f41b2","unresolved":false,"context_lines":[{"line_number":101,"context_line":"  information in the docs and sample file."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-sample-default"},{"line_number":104,"context_line":"  Make better use of the sample default in the sample file generator"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":107,"context_line":"  Uncomment required configurations in the generated sample file"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_77e55f36","line":104,"in_reply_to":"5a18252c_aedd0be2","updated":"2016-04-14 16:45:04.000000000","message":"Yes, well, it is the \"sample\" default not the \"minimally useful\" default. :-)\n\nIt sounds like we could clear that up with an extra comment in those cases, and that should be a straightforward change.\n\nI can see it being useful to have a flag to the config generator to avoid including the sample defaults for options that must be set and have no valid default. That would no longer be a \"sample\" config but a \"minimal\" config and we might make other changes to the contents of the file in that case.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":114,"context_line":"  configuration files. It should warn about any deprecated options, and should"},{"line_number":115,"context_line":"  fail on any unrecognized options or options that don\u0027t have a valid value"},{"line_number":116,"context_line":"  (including failing on required options that are not set). Similarly, it"},{"line_number":117,"context_line":"  could optionally warn folks they are using an advanced option."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"Categorizing configuration options"},{"line_number":120,"context_line":"----------------------------------"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_6cfe3faf","line":117,"updated":"2016-04-14 14:32:54.000000000","message":"As it stands you\u0027ll need a separate tool per service. Services may define new options at any time and there\u0027s no standard for where they\u0027re kept, so it\u0027ll need per-service code to import them.\n\nYou could do centralize-config-options work on every service, declare an API and write a tool that can leverage that to import options from each conformant service. Alternatively, work with each service to add a \"--validate-config\" option.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":114,"context_line":"  configuration files. It should warn about any deprecated options, and should"},{"line_number":115,"context_line":"  fail on any unrecognized options or options that don\u0027t have a valid value"},{"line_number":116,"context_line":"  (including failing on required options that are not set). Similarly, it"},{"line_number":117,"context_line":"  could optionally warn folks they are using an advanced option."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"Categorizing configuration options"},{"line_number":120,"context_line":"----------------------------------"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_e68e1078","line":117,"in_reply_to":"5a18252c_37fac775","updated":"2016-04-19 11:46:24.000000000","message":"Right, the idea is to just do whats possible, in the same way as the configuration generator works.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"733f3ec49e90786acee6b4986c258d09f99f41b2","unresolved":false,"context_lines":[{"line_number":114,"context_line":"  configuration files. It should warn about any deprecated options, and should"},{"line_number":115,"context_line":"  fail on any unrecognized options or options that don\u0027t have a valid value"},{"line_number":116,"context_line":"  (including failing on required options that are not set). Similarly, it"},{"line_number":117,"context_line":"  could optionally warn folks they are using an advanced option."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"Categorizing configuration options"},{"line_number":120,"context_line":"----------------------------------"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_37fac775","line":117,"in_reply_to":"5a18252c_6cfe3faf","updated":"2016-04-14 16:45:04.000000000","message":"If we use the same input file that the config generator uses, we could have some minimal validation done against the options with a central tool. That said, there are still some cases where a valid looking value may in fact be invalid because of combinations of values that don\u0027t work (a username and password must be validated together, for example). App-specific entry points for validator functions might solve that.\n\nThere was an ancient spec for building a validator for Juno (see https://review.openstack.org/#/c/93149/) that might have some use.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":115,"context_line":"  fail on any unrecognized options or options that don\u0027t have a valid value"},{"line_number":116,"context_line":"  (including failing on required options that are not set). Similarly, it"},{"line_number":117,"context_line":"  could optionally warn folks they are using an advanced option."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"Categorizing configuration options"},{"line_number":120,"context_line":"----------------------------------"},{"line_number":121,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_ec727448","line":118,"updated":"2016-04-13 22:27:29.000000000","message":"Please also document the updates needed for the sphinx integration for documenting options. We use that now in developer documents, and will be expanding its use during Newton in the central configuration guide.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":119,"context_line":"Categorizing configuration options"},{"line_number":120,"context_line":"----------------------------------"},{"line_number":121,"context_line":""},{"line_number":122,"context_line":"All projects should go through each of their options, looking at which"},{"line_number":123,"context_line":"configuration options should be marked with one of the following:"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_1856e5cd","line":122,"updated":"2016-04-14 14:32:54.000000000","message":"It\u0027s tricky to say \"all projects should\", at least with an expectation of action, especially now there\u0027s no TC approval. Do you aim for this to be part of DefCore or something? Alternatively, is there some carrot you can dangle (like a validate-config tool)?","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":119,"context_line":"Categorizing configuration options"},{"line_number":120,"context_line":"----------------------------------"},{"line_number":121,"context_line":""},{"line_number":122,"context_line":"All projects should go through each of their options, looking at which"},{"line_number":123,"context_line":"configuration options should be marked with one of the following:"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_83cd8e87","line":122,"in_reply_to":"5a18252c_1856e5cd","updated":"2016-04-19 11:46:24.000000000","message":"Agreed, I am unsure on what wording to use. I used should rather than must, but clearly thats not working.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":124,"context_line":""},{"line_number":125,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"},{"line_number":126,"context_line":""},{"line_number":127,"context_line":"  * Before marking an option as required, we should check that its not"},{"line_number":128,"context_line":"    possible to have a better default, so the operator doesn\u0027t have to set"},{"line_number":129,"context_line":"    this option."},{"line_number":130,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_c8724dad","line":127,"updated":"2016-04-08 23:11:35.000000000","message":"nit: see comment on L96.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":129,"context_line":"    this option."},{"line_number":130,"context_line":""},{"line_number":131,"context_line":"  * Required options generally have empty defaults, but we should make use"},{"line_number":132,"context_line":"    of the ``sample_default`` option and the description, so its easy for"},{"line_number":133,"context_line":"    operators to work out what value they need to set when doing the initial"},{"line_number":134,"context_line":"    setup of their cloud."},{"line_number":135,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_086565e0","line":132,"updated":"2016-04-08 23:11:35.000000000","message":"nit: see comment on L96.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":136,"context_line":"* ``advanced\u003dTrue``: these options rarely need to be set by deployers"},{"line_number":137,"context_line":""},{"line_number":138,"context_line":"  * When marking an option as advanced, we should consider if it is worth"},{"line_number":139,"context_line":"    deprecating and eventually removing the configuration"},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"* Review configuration option groups and their descriptions"},{"line_number":142,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_ecc0b42c","line":139,"updated":"2016-04-13 22:27:29.000000000","message":"Alternately, move the options to a separate group.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":166,"context_line":"Improving Documentation and Sample file"},{"line_number":167,"context_line":"---------------------------------------"},{"line_number":168,"context_line":""},{"line_number":169,"context_line":"The overall aim is operators should not need to read and understand the code"},{"line_number":170,"context_line":"to know how to configure the system."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"This spec is focusing on making sure olso.config has all the information"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_387be129","line":169,"range":{"start_line":169,"start_character":16,"end_line":169,"end_character":18},"updated":"2016-04-14 14:32:54.000000000","message":"nit: is that","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":166,"context_line":"Improving Documentation and Sample file"},{"line_number":167,"context_line":"---------------------------------------"},{"line_number":168,"context_line":""},{"line_number":169,"context_line":"The overall aim is operators should not need to read and understand the code"},{"line_number":170,"context_line":"to know how to configure the system."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"This spec is focusing on making sure olso.config has all the information"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_06334cac","line":169,"range":{"start_line":169,"start_character":16,"end_line":169,"end_character":18},"in_reply_to":"5a18252c_387be129","updated":"2016-04-19 11:46:24.000000000","message":"Done","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"5e1e2e007d53a0caafc3b0ca24ac37aa893f91a7","unresolved":false,"context_lines":[{"line_number":169,"context_line":"The overall aim is operators should not need to read and understand the code"},{"line_number":170,"context_line":"to know how to configure the system."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"This spec is focusing on making sure olso.config has all the information"},{"line_number":173,"context_line":"required to generate good sample configuration files and generating good"},{"line_number":174,"context_line":"documentation for the configuration options. This spec is not focusing on how"},{"line_number":175,"context_line":"the documentation is generated from the option definitions."}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_fc660628","line":172,"range":{"start_line":172,"start_character":37,"end_line":172,"end_character":41},"updated":"2016-04-08 17:31:09.000000000","message":"oslo","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":169,"context_line":"The overall aim is operators should not need to read and understand the code"},{"line_number":170,"context_line":"to know how to configure the system."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"This spec is focusing on making sure olso.config has all the information"},{"line_number":173,"context_line":"required to generate good sample configuration files and generating good"},{"line_number":174,"context_line":"documentation for the configuration options. This spec is not focusing on how"},{"line_number":175,"context_line":"the documentation is generated from the option definitions."}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_c6fe74ad","line":172,"range":{"start_line":172,"start_character":37,"end_line":172,"end_character":41},"in_reply_to":"9a061dce_fc660628","updated":"2016-04-19 11:46:24.000000000","message":"Done","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":180,"context_line":""},{"line_number":181,"context_line":"Nova has found standardizing around a template has helped build some"},{"line_number":182,"context_line":"consistency in what is described in the help text for each option."},{"line_number":183,"context_line":"It is replicated here as an example other project could adopt:"},{"line_number":184,"context_line":""},{"line_number":185,"context_line":".. code::"},{"line_number":186,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_38c9215a","line":183,"range":{"start_line":183,"start_character":42,"end_line":183,"end_character":49},"updated":"2016-04-14 14:32:54.000000000","message":"nit: projects","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":180,"context_line":""},{"line_number":181,"context_line":"Nova has found standardizing around a template has helped build some"},{"line_number":182,"context_line":"consistency in what is described in the help text for each option."},{"line_number":183,"context_line":"It is replicated here as an example other project could adopt:"},{"line_number":184,"context_line":""},{"line_number":185,"context_line":".. code::"},{"line_number":186,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_e601f0b0","line":183,"range":{"start_line":183,"start_character":42,"end_line":183,"end_character":49},"in_reply_to":"5a18252c_38c9215a","updated":"2016-04-19 11:46:24.000000000","message":"Done","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":195,"context_line":"    # A list of services which consume this option. Operators should not be"},{"line_number":196,"context_line":"    # required to read code to know which one of the services will change its"},{"line_number":197,"context_line":"    # behavior. Nor should they set this in every ``nova.conf`` file to be"},{"line_number":198,"context_line":"    # sure. This can really help deployers understand how the option is used."},{"line_number":199,"context_line":""},{"line_number":200,"context_line":"    Possible values:"},{"line_number":201,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_4c13a8b8","line":198,"updated":"2016-04-13 22:27:29.000000000","message":"By setting up the entry points for the config generator correctly, a separate sample configuration file can be generated for each service, including only the options used by that service.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":195,"context_line":"    # A list of services which consume this option. Operators should not be"},{"line_number":196,"context_line":"    # required to read code to know which one of the services will change its"},{"line_number":197,"context_line":"    # behavior. Nor should they set this in every ``nova.conf`` file to be"},{"line_number":198,"context_line":"    # sure. This can really help deployers understand how the option is used."},{"line_number":199,"context_line":""},{"line_number":200,"context_line":"    Possible values:"},{"line_number":201,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_e6c61067","line":198,"in_reply_to":"5a18252c_4c13a8b8","updated":"2016-04-19 11:46:24.000000000","message":"So this is probably a nova specific oddness. We flip flop between telling someone to but the same configuration file for every service, vs thinking about separating them.\n\nWhen it comes to documenting all the options for each project, I think this is still useful. Although we should totally not duplicate the data.\n\nI need to think on that more, I will add a note in the alternatives.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":199,"context_line":""},{"line_number":200,"context_line":"    Possible values:"},{"line_number":201,"context_line":""},{"line_number":202,"context_line":"    # description of possible values. Especially if this is an option"},{"line_number":203,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"},{"line_number":204,"context_line":"    # min value, max value, 0, -1). Further, for choices which are not"},{"line_number":205,"context_line":"    # obviously named, please describe the affect of each choice."}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_283ae9cd","line":202,"updated":"2016-04-08 23:11:35.000000000","message":"nit: capitalize this, or make it a complete sentence?","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":199,"context_line":""},{"line_number":200,"context_line":"    Possible values:"},{"line_number":201,"context_line":""},{"line_number":202,"context_line":"    # description of possible values. Especially if this is an option"},{"line_number":203,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"},{"line_number":204,"context_line":"    # min value, max value, 0, -1). Further, for choices which are not"},{"line_number":205,"context_line":"    # obviously named, please describe the affect of each choice."}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_66ae8082","line":202,"in_reply_to":"9a061dce_283ae9cd","updated":"2016-04-19 11:46:24.000000000","message":"so this is mostly a cut and paste from the spec, in theory, but I can fix that.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":204,"context_line":"    # min value, max value, 0, -1). Further, for choices which are not"},{"line_number":205,"context_line":"    # obviously named, please describe the affect of each choice."},{"line_number":206,"context_line":"    # Note: this does not replace the need for StrOpt.choices, StrOpt.regex,"},{"line_number":207,"context_line":"    # IntOpt.min, etc."},{"line_number":208,"context_line":""},{"line_number":209,"context_line":"    Related options:"},{"line_number":210,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_0c225000","line":207,"updated":"2016-04-13 22:27:29.000000000","message":"The config generator could (does?) include all of the min, max, etc. value information in its output. The sphinx integration does.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":204,"context_line":"    # min value, max value, 0, -1). Further, for choices which are not"},{"line_number":205,"context_line":"    # obviously named, please describe the affect of each choice."},{"line_number":206,"context_line":"    # Note: this does not replace the need for StrOpt.choices, StrOpt.regex,"},{"line_number":207,"context_line":"    # IntOpt.min, etc."},{"line_number":208,"context_line":""},{"line_number":209,"context_line":"    Related options:"},{"line_number":210,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_2614889e","line":207,"in_reply_to":"5a18252c_0c225000","updated":"2016-04-19 11:46:24.000000000","message":"This is not about -1 being a valid value, is about describing what that -1 actually means in this context.\n\nI will try fix that in the description here.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":209,"context_line":"    Related options:"},{"line_number":210,"context_line":""},{"line_number":211,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":212,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":213,"context_line":"    # Note: this does not replace the new Opt.related_options, it used"},{"line_number":214,"context_line":"    # when extra details are required."},{"line_number":215,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_a84c3977","line":212,"updated":"2016-04-08 23:11:35.000000000","message":"nit: stands\n\nnit: missing a period","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":209,"context_line":"    Related options:"},{"line_number":210,"context_line":""},{"line_number":211,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":212,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":213,"context_line":"    # Note: this does not replace the new Opt.related_options, it used"},{"line_number":214,"context_line":"    # when extra details are required."},{"line_number":215,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_8653dc6a","line":212,"in_reply_to":"9a061dce_a84c3977","updated":"2016-04-19 11:46:24.000000000","message":"Done","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":213,"context_line":"    # Note: this does not replace the new Opt.related_options, it used"},{"line_number":214,"context_line":"    # when extra details are required."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":"When reviewing the description of the configuration, its worth reviewing the"},{"line_number":217,"context_line":"other parameters passed to ``oslo.config``. There have been features added to"},{"line_number":218,"context_line":"make the opt definition more precise, but some of the options have not been"},{"line_number":219,"context_line":"updated since those new features were added."}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_e8563105","line":216,"updated":"2016-04-08 23:11:35.000000000","message":"nit: see comment on L96.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":213,"context_line":"    # Note: this does not replace the new Opt.related_options, it used"},{"line_number":214,"context_line":"    # when extra details are required."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":"When reviewing the description of the configuration, its worth reviewing the"},{"line_number":217,"context_line":"other parameters passed to ``oslo.config``. There have been features added to"},{"line_number":218,"context_line":"make the opt definition more precise, but some of the options have not been"},{"line_number":219,"context_line":"updated since those new features were added."}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_26c92827","line":216,"in_reply_to":"9a061dce_e8563105","updated":"2016-04-19 11:46:24.000000000","message":"Done","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":1297,"name":"Joshua Harlow","email":"jxharlow@godaddy.com","username":"harlowja"},"change_message_id":"4bbe2c661247b4fe1e9c963368d2bc76dff01f43","unresolved":false,"context_lines":[{"line_number":229,"context_line":"  deprecated_reason setting."},{"line_number":230,"context_line":"* Look out for bad defaults that force install guides to tell users to set a"},{"line_number":231,"context_line":"  configuration value because the default would never work. Always optimize"},{"line_number":232,"context_line":"  the default for operators rather than the test environment."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Improving the Sample file"},{"line_number":235,"context_line":"--------------------------"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_68076b18","line":232,"updated":"2016-04-14 01:42:51.000000000","message":"+10","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":229,"context_line":"  deprecated_reason setting."},{"line_number":230,"context_line":"* Look out for bad defaults that force install guides to tell users to set a"},{"line_number":231,"context_line":"  configuration value because the default would never work. Always optimize"},{"line_number":232,"context_line":"  the default for operators rather than the test environment."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Improving the Sample file"},{"line_number":235,"context_line":"--------------------------"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_984cb5c9","line":232,"in_reply_to":"5a18252c_68076b18","updated":"2016-04-14 14:32:54.000000000","message":"obvious extension - look for install guides for your service and fix issues raised. This can be a great first contribution.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":229,"context_line":"  deprecated_reason setting."},{"line_number":230,"context_line":"* Look out for bad defaults that force install guides to tell users to set a"},{"line_number":231,"context_line":"  configuration value because the default would never work. Always optimize"},{"line_number":232,"context_line":"  the default for operators rather than the test environment."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Improving the Sample file"},{"line_number":235,"context_line":"--------------------------"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_e6e3b0a2","line":232,"in_reply_to":"5a18252c_984cb5c9","updated":"2016-04-19 11:46:24.000000000","message":"right, but I am trying to focus on what you when editing each option.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":247,"context_line":"* deprecated options, only important for those who have previously set these"},{"line_number":248,"context_line":"  options and are performing an upgrade."},{"line_number":249,"context_line":"* advanced options, by default we can put these last, but we may want to"},{"line_number":250,"context_line":"  optional exclude these from the generate sample default file."},{"line_number":251,"context_line":""},{"line_number":252,"context_line":"Note the above is assuming deployers that base their deployments on updates"},{"line_number":253,"context_line":"to a freshly generated sample file are using tooling that is not affected"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_6c5e6477","line":250,"updated":"2016-04-13 22:27:29.000000000","message":"The configuration generator currently sorts the options alphabetically within each group to ensure that the output of the config file is the same regardless of the order of values returned by the entry point scanner. If we\u0027re going to change that, we need some way to continue to ensure that the output is deterministic.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":247,"context_line":"* deprecated options, only important for those who have previously set these"},{"line_number":248,"context_line":"  options and are performing an upgrade."},{"line_number":249,"context_line":"* advanced options, by default we can put these last, but we may want to"},{"line_number":250,"context_line":"  optional exclude these from the generate sample default file."},{"line_number":251,"context_line":""},{"line_number":252,"context_line":"Note the above is assuming deployers that base their deployments on updates"},{"line_number":253,"context_line":"to a freshly generated sample file are using tooling that is not affected"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_f86fa9f9","line":250,"in_reply_to":"5a18252c_6c5e6477","updated":"2016-04-14 14:32:54.000000000","message":"If we sort alphabetically within each of these four categories, does that fulfil the requirement?","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"733f3ec49e90786acee6b4986c258d09f99f41b2","unresolved":false,"context_lines":[{"line_number":247,"context_line":"* deprecated options, only important for those who have previously set these"},{"line_number":248,"context_line":"  options and are performing an upgrade."},{"line_number":249,"context_line":"* advanced options, by default we can put these last, but we may want to"},{"line_number":250,"context_line":"  optional exclude these from the generate sample default file."},{"line_number":251,"context_line":""},{"line_number":252,"context_line":"Note the above is assuming deployers that base their deployments on updates"},{"line_number":253,"context_line":"to a freshly generated sample file are using tooling that is not affected"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_578e63d0","line":250,"in_reply_to":"5a18252c_f86fa9f9","updated":"2016-04-14 16:45:04.000000000","message":"On closer review, I think we\u0027re only sorting the groups by name, and not the contents of the group. I vaguely remember a team wanting the options to show up in the order they specified (keystone?) to achieve an effect similar to what is proposed here with the advanced flag sorting.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":255,"context_line":"validity of any configuration files that might use an older ordering. It"},{"line_number":256,"context_line":"should be common for a configuration file that is deployed to only contain"},{"line_number":257,"context_line":"the small number of required configuration values, with any required overrides"},{"line_number":258,"context_line":"of other options."},{"line_number":259,"context_line":""},{"line_number":260,"context_line":"Centralize Configuration options (optional)"},{"line_number":261,"context_line":"-------------------------------------------"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_8ce94083","line":258,"updated":"2016-04-13 22:27:29.000000000","message":"As far as the config library is concerned, the order of values in the file doesn\u0027t make any difference.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":255,"context_line":"validity of any configuration files that might use an older ordering. It"},{"line_number":256,"context_line":"should be common for a configuration file that is deployed to only contain"},{"line_number":257,"context_line":"the small number of required configuration values, with any required overrides"},{"line_number":258,"context_line":"of other options."},{"line_number":259,"context_line":""},{"line_number":260,"context_line":"Centralize Configuration options (optional)"},{"line_number":261,"context_line":"-------------------------------------------"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_c6f79457","line":258,"in_reply_to":"5a18252c_8ce94083","updated":"2016-04-19 11:46:24.000000000","message":"Agreed. This was heavily questioned in a previous revision, so I tried to clarify that. Let me borrow your wording, I like it.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":260,"context_line":"Centralize Configuration options (optional)"},{"line_number":261,"context_line":"-------------------------------------------"},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"There have been efforts to declare option near where they are used, and also"},{"line_number":264,"context_line":"efforts to centralize configuration options. This spec encourages project to"},{"line_number":265,"context_line":"look at centralizing configuration as a way to help with the above efforts to"},{"line_number":266,"context_line":"improve the configuration option experience for deployers. Given the diversity"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_782a7991","line":263,"range":{"start_line":263,"start_character":35,"end_line":263,"end_character":41},"updated":"2016-04-14 14:32:54.000000000","message":"nit options","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":261,"context_line":"-------------------------------------------"},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"There have been efforts to declare option near where they are used, and also"},{"line_number":264,"context_line":"efforts to centralize configuration options. This spec encourages project to"},{"line_number":265,"context_line":"look at centralizing configuration as a way to help with the above efforts to"},{"line_number":266,"context_line":"improve the configuration option experience for deployers. Given the diversity"},{"line_number":267,"context_line":"in the project with OpenStack, each project will need to decide what is best"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_580e9d3b","line":264,"range":{"start_line":264,"start_character":66,"end_line":264,"end_character":73},"updated":"2016-04-14 14:32:54.000000000","message":"nit projects","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":267,"context_line":"in the project with OpenStack, each project will need to decide what is best"},{"line_number":268,"context_line":"for them."},{"line_number":269,"context_line":""},{"line_number":270,"context_line":"Project that have defined options near where they are used have come across"},{"line_number":271,"context_line":"several issues, including:"},{"line_number":272,"context_line":""},{"line_number":273,"context_line":"* inconsistent quality in the option declarations, particular around the"}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_88869563","line":270,"updated":"2016-04-08 23:11:35.000000000","message":"nit: Projects","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":275,"context_line":"* not enough effort on the overall experience of using configuration options,"},{"line_number":276,"context_line":"  such as defining new options rather than re-using existing options"},{"line_number":277,"context_line":""},{"line_number":278,"context_line":"Keystone have found a centralized approach to defining options has proved a"},{"line_number":279,"context_line":"useful way to help developers consider the configuration options as a whole,"},{"line_number":280,"context_line":"rather than in a more piecemeal way. It also helps force a change of context"},{"line_number":281,"context_line":"from the developer of the code to the deployer that uses the configuration."}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_c8808d49","line":278,"updated":"2016-04-08 23:11:35.000000000","message":"nit: has","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"83b5549b83e9eab712406ebb6a07c92a734d12bc","unresolved":false,"context_lines":[{"line_number":278,"context_line":"Keystone have found a centralized approach to defining options has proved a"},{"line_number":279,"context_line":"useful way to help developers consider the configuration options as a whole,"},{"line_number":280,"context_line":"rather than in a more piecemeal way. It also helps force a change of context"},{"line_number":281,"context_line":"from the developer of the code to the deployer that uses the configuration."},{"line_number":282,"context_line":"Keystone adopted a single module that contains all options:"},{"line_number":283,"context_line":"http://git.openstack.org/cgit/openstack/keystone/tree/keystone/common/config.py"},{"line_number":284,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"9a061dce_28966994","line":281,"updated":"2016-04-08 23:11:35.000000000","message":"+1!","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":283,"context_line":"http://git.openstack.org/cgit/openstack/keystone/tree/keystone/common/config.py"},{"line_number":284,"context_line":""},{"line_number":285,"context_line":"Nova is currently moving towards a more centralized approach, in"},{"line_number":286,"context_line":"`Nova\u0027s centralize config options spec`_. Previous experience has show that"},{"line_number":287,"context_line":"Nova has too many options for it to be practical to have a single module that"},{"line_number":288,"context_line":"contains options. Nova has taken the approach of a ``conf`` sub-module"},{"line_number":289,"context_line":"containing a module containing configuration option definitions for a"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_a36062d0","line":286,"range":{"start_line":286,"start_character":66,"end_line":286,"end_character":70},"updated":"2016-04-14 14:32:54.000000000","message":"nit shown","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":308,"context_line":"and listed via a uniform API."},{"line_number":309,"context_line":""},{"line_number":310,"context_line":"Further, the ``__init__.py`` file for ``nova.conf`` holds a single ``CONF``"},{"line_number":311,"context_line":"object and registers all of the options to it so that consumers can simply do:"},{"line_number":312,"context_line":""},{"line_number":313,"context_line":".. code-block:: python"},{"line_number":314,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_c33d9e90","line":311,"updated":"2016-04-14 14:32:54.000000000","message":"I don\u0027t know that we want to promote the single CONF object. It makes sense for Nova because Nova is old and built on this assumption.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"733f3ec49e90786acee6b4986c258d09f99f41b2","unresolved":false,"context_lines":[{"line_number":308,"context_line":"and listed via a uniform API."},{"line_number":309,"context_line":""},{"line_number":310,"context_line":"Further, the ``__init__.py`` file for ``nova.conf`` holds a single ``CONF``"},{"line_number":311,"context_line":"object and registers all of the options to it so that consumers can simply do:"},{"line_number":312,"context_line":""},{"line_number":313,"context_line":".. code-block:: python"},{"line_number":314,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_97df5a68","line":311,"in_reply_to":"5a18252c_c33d9e90","updated":"2016-04-14 16:45:04.000000000","message":"Oslo libraries, in particular, do *not* make this assumption and register options at runtime as they are needed.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":317,"context_line":"    CONF \u003d nova.conf.CONF"},{"line_number":318,"context_line":""},{"line_number":319,"context_line":"This provides a simple and uniform interface to configuration options while"},{"line_number":320,"context_line":"avoiding potential problems references in the `original mailing list thread`_"},{"line_number":321,"context_line":"with circular dependencies caused by ``import_opt``."},{"line_number":322,"context_line":"You can see an example of what is being done here:"},{"line_number":323,"context_line":"https://git.openstack.org/cgit/openstack/nova/tree/nova/conf/pci.py"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_8350c6d5","line":320,"range":{"start_line":320,"start_character":28,"end_line":320,"end_character":38},"updated":"2016-04-14 14:32:54.000000000","message":"nit referenced","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":323,"context_line":"https://git.openstack.org/cgit/openstack/nova/tree/nova/conf/pci.py"},{"line_number":324,"context_line":""},{"line_number":325,"context_line":"We also use a \"single point of entry\" for the generation of the sample"},{"line_number":326,"context_line":"configuration file. This help make is much harder to accidentally not"},{"line_number":327,"context_line":"include options in the sample configuration file. The doc job generates"},{"line_number":328,"context_line":"a sample config file on every build, to keep it working."},{"line_number":329,"context_line":"You can see more details on how that works here:"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_230d72e8","line":326,"range":{"start_line":326,"start_character":20,"end_line":326,"end_character":37},"updated":"2016-04-14 14:32:54.000000000","message":"this help make is - what?","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":332,"context_line":"Alternatives"},{"line_number":333,"context_line":"------------"},{"line_number":334,"context_line":""},{"line_number":335,"context_line":"#. oslo_config could add an opt_catagory rather than adding advanced"},{"line_number":336,"context_line":""},{"line_number":337,"context_line":"   There are many ways we could change the opt definition to allow developers"},{"line_number":338,"context_line":"   to categories the configuration options. Given we already have required and"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_03295637","line":335,"range":{"start_line":335,"start_character":28,"end_line":335,"end_character":40},"updated":"2016-04-14 14:32:54.000000000","message":"nit opt_category","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":339,"context_line":"   deprecated, it seems easiest to add \"advanced\" rather than deprecate all"},{"line_number":340,"context_line":"   the old flags and add a new category flag. However, this spec is mostly"},{"line_number":341,"context_line":"   worrying about consistent use of these features. The implementation should"},{"line_number":342,"context_line":"   be agreed by the team working on oslo_config"},{"line_number":343,"context_line":""},{"line_number":344,"context_line":"#. Use data files to provide configuration options to the operator."},{"line_number":345,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_4cbd6867","line":342,"updated":"2016-04-13 22:27:29.000000000","message":"See earlier comments about adding more configuration groups within the file to handle advanced and related options without any library code changes.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":344,"context_line":"#. Use data files to provide configuration options to the operator."},{"line_number":345,"context_line":""},{"line_number":346,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":347,"context_line":"   updated as frequently as the options themselves will be."},{"line_number":348,"context_line":""},{"line_number":349,"context_line":"#. Use a global object to control access to the ``CONF`` object."},{"line_number":350,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_8371e646","line":347,"updated":"2016-04-14 14:32:54.000000000","message":"this concern seems out of sync with the centralize-config approach advocated. Is it a problem or isn\u0027t it? Besides, the data files would still be side-by-side in the filesystem.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a3ea1026ad5a4eba7d7adee790abfad4e276e040","unresolved":false,"context_lines":[{"line_number":344,"context_line":"#. Use data files to provide configuration options to the operator."},{"line_number":345,"context_line":""},{"line_number":346,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":347,"context_line":"   updated as frequently as the options themselves will be."},{"line_number":348,"context_line":""},{"line_number":349,"context_line":"#. Use a global object to control access to the ``CONF`` object."},{"line_number":350,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a122d0e_691e5160","line":347,"in_reply_to":"5a18252c_8371e646","updated":"2016-04-19 11:46:24.000000000","message":"Right that what this alternative is not adopted.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"9c4c4ce39ba9fbc1dc3287e95487991cae155170","unresolved":false,"context_lines":[{"line_number":350,"context_line":""},{"line_number":351,"context_line":"   This would allow for a number of things - testability, cleaner code, and"},{"line_number":352,"context_line":"   the ability to follow Object-Oriented Programming best practices - but an"},{"line_number":353,"context_line":"   `initial implementation`_ proved it to be cumbersome."},{"line_number":354,"context_line":""},{"line_number":355,"context_line":""},{"line_number":356,"context_line":"Implementation"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_cc7858c7","line":353,"updated":"2016-04-13 22:27:29.000000000","message":"It looks like that work would also subvert the desire to have options be reloadable without restarting the application (something we added in Mitaka).","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"8f2768f123f350d4ccf6610e76bca45818160132","unresolved":false,"context_lines":[{"line_number":350,"context_line":""},{"line_number":351,"context_line":"   This would allow for a number of things - testability, cleaner code, and"},{"line_number":352,"context_line":"   the ability to follow Object-Oriented Programming best practices - but an"},{"line_number":353,"context_line":"   `initial implementation`_ proved it to be cumbersome."},{"line_number":354,"context_line":""},{"line_number":355,"context_line":""},{"line_number":356,"context_line":"Implementation"}],"source_content_type":"text/x-rst","patch_set":8,"id":"5a18252c_636f6a2b","line":353,"in_reply_to":"5a18252c_cc7858c7","updated":"2016-04-14 14:32:54.000000000","message":"I\u0027d like this alternative removed, imo the \u0027advantages\u0027 are unsubstantiated and false while there are many negatives.","commit_id":"c4720c9edc2df0b23e6613274ca2d31ce3b30401"},{"author":{"_account_id":1297,"name":"Joshua Harlow","email":"jxharlow@godaddy.com","username":"harlowja"},"change_message_id":"98ea4e5fd2a868fd4eb78420564f339102fec94e","unresolved":false,"context_lines":[{"line_number":21,"context_line":"Problem description"},{"line_number":22,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"One of the largest barriers to adoption of OpenStack is perceived complexity."},{"line_number":25,"context_line":"This surfaces in attempting to understand and properly set configurations"},{"line_number":26,"context_line":"on initial deployment, when trying to scale out deployments, and again after"},{"line_number":27,"context_line":"upgrading."}],"source_content_type":"text/x-rst","patch_set":9,"id":"7aa08908_aacbed51","line":24,"updated":"2016-06-14 00:27:42.000000000","message":"I\u0027m pretty sure its not \u0027perceived\u0027 anymore ;)","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":91,"context_line":""},{"line_number":92,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/advanced-option"},{"line_number":93,"context_line":"  Mark options as \"advanced\" so it\u0027s clear which options are rarely used"},{"line_number":94,"context_line":"  While olso_config is considering if this approach makes sense, it\u0027s possible"},{"line_number":95,"context_line":"  to instead group the advanced options into their own option group called"},{"line_number":96,"context_line":"  something like: \u003cgroup\u003e.advanced"},{"line_number":97,"context_line":"  The aim is to allow docs and config file generation to treat these options"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_501c4d13","line":94,"range":{"start_line":94,"start_character":8,"end_line":94,"end_character":19},"updated":"2016-04-21 16:06:26.000000000","message":"nit oslo.config","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"e2b664771eef2dfced5b824c067a3167de17a427","unresolved":false,"context_lines":[{"line_number":93,"context_line":"  Mark options as \"advanced\" so it\u0027s clear which options are rarely used"},{"line_number":94,"context_line":"  While olso_config is considering if this approach makes sense, it\u0027s possible"},{"line_number":95,"context_line":"  to instead group the advanced options into their own option group called"},{"line_number":96,"context_line":"  something like: \u003cgroup\u003e.advanced"},{"line_number":97,"context_line":"  The aim is to allow docs and config file generation to treat these options"},{"line_number":98,"context_line":"  differently. Hiding them could help users understand the more important"},{"line_number":99,"context_line":"  configuration options."}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_b5f1ce03","line":96,"updated":"2016-04-19 15:35:24.000000000","message":"Doesn\u0027t this both cause deprecation cycles as options move and produce a more complicated configuration file in the end? \n\nGrouping seems like it might be easier for developers today but shifts complexity to operators and drags out the resolution of this work due to those deprecations.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"2fb9447acaa45fdab2a1bc1436fdee79b17a8f2c","unresolved":false,"context_lines":[{"line_number":93,"context_line":"  Mark options as \"advanced\" so it\u0027s clear which options are rarely used"},{"line_number":94,"context_line":"  While olso_config is considering if this approach makes sense, it\u0027s possible"},{"line_number":95,"context_line":"  to instead group the advanced options into their own option group called"},{"line_number":96,"context_line":"  something like: \u003cgroup\u003e.advanced"},{"line_number":97,"context_line":"  The aim is to allow docs and config file generation to treat these options"},{"line_number":98,"context_line":"  differently. Hiding them could help users understand the more important"},{"line_number":99,"context_line":"  configuration options."}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_bfc76563","line":96,"in_reply_to":"1a122d0e_b5f1ce03","updated":"2016-04-21 18:24:40.000000000","message":"oslo.config will find a moved option in its old location, so it is possible to deprecate the old name or group and still use the same configuration file.\n\nNote, you can\u0027t actually use a \".\" in the group name, but an underscore would work.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"1959ea103ae83cf6149a3005219f9a86fa4b4a89","unresolved":false,"context_lines":[{"line_number":93,"context_line":"  Mark options as \"advanced\" so it\u0027s clear which options are rarely used"},{"line_number":94,"context_line":"  While olso_config is considering if this approach makes sense, it\u0027s possible"},{"line_number":95,"context_line":"  to instead group the advanced options into their own option group called"},{"line_number":96,"context_line":"  something like: \u003cgroup\u003e.advanced"},{"line_number":97,"context_line":"  The aim is to allow docs and config file generation to treat these options"},{"line_number":98,"context_line":"  differently. Hiding them could help users understand the more important"},{"line_number":99,"context_line":"  configuration options."}],"source_content_type":"text/x-rst","patch_set":9,"id":"bab6814e_ac956e89","line":96,"in_reply_to":"1a122d0e_bfc76563","updated":"2016-05-24 08:58:28.000000000","message":"yeah, the moves are, however, very disruptive to your users, either way we look at it.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":103,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":104,"context_line":"  information in the docs and sample file."},{"line_number":105,"context_line":"  While this could be done purely in comments, it makes it hard to have links"},{"line_number":106,"context_line":"  between related options in the documentation."},{"line_number":107,"context_line":""},{"line_number":108,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":109,"context_line":"  This is work to let the generator have an option to produce configuration"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_d0985d1e","line":106,"updated":"2016-04-21 16:06:26.000000000","message":"Surely Sphinx can cross-link? You\u0027ll have to markup eg `nova.scheduler.subset_size`_ but that\u0027s no harder than setting related_options\u003d[\u0027nova.scheduler.subset_size\u0027]","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"1959ea103ae83cf6149a3005219f9a86fa4b4a89","unresolved":false,"context_lines":[{"line_number":103,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":104,"context_line":"  information in the docs and sample file."},{"line_number":105,"context_line":"  While this could be done purely in comments, it makes it hard to have links"},{"line_number":106,"context_line":"  between related options in the documentation."},{"line_number":107,"context_line":""},{"line_number":108,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":109,"context_line":"  This is work to let the generator have an option to produce configuration"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bab6814e_cce39232","line":106,"in_reply_to":"1a122d0e_7f94ad43","updated":"2016-05-24 08:58:28.000000000","message":"Yeah, the current RST style approach is OK for the sample config file, but is actually breaking in the HTML docs.\n\nI don\u0027t think links will work here.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"2fb9447acaa45fdab2a1bc1436fdee79b17a8f2c","unresolved":false,"context_lines":[{"line_number":103,"context_line":"  should describe the relationship, but this allows better handling of that"},{"line_number":104,"context_line":"  information in the docs and sample file."},{"line_number":105,"context_line":"  While this could be done purely in comments, it makes it hard to have links"},{"line_number":106,"context_line":"  between related options in the documentation."},{"line_number":107,"context_line":""},{"line_number":108,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":109,"context_line":"  This is work to let the generator have an option to produce configuration"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_7f94ad43","line":106,"in_reply_to":"1a122d0e_d0985d1e","updated":"2016-04-21 18:24:40.000000000","message":"Embedding markup in the help text will make the sample config file \"ugly\" unless we do some work there to strip it.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":108,"context_line":"* https://blueprints.launchpad.net/oslo.config/+spec/oslo-generator-required"},{"line_number":109,"context_line":"  This is work to let the generator have an option to produce configuration"},{"line_number":110,"context_line":"  files that make it easy for users to complete the initial configuration of"},{"line_number":111,"context_line":"  the system. This includes things like uncomment required configurations"},{"line_number":112,"context_line":"  in the generated file."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"* Improved the appearance of deprecated options in the generated sample file."}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_3043916e","line":111,"range":{"start_line":111,"start_character":40,"end_line":111,"end_character":49},"updated":"2016-04-21 16:06:26.000000000","message":"nit uncommenting","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":19686,"name":"Ramamani Yeleswarapu","email":"ramamani.yeleswarapu@intel.com","username":"Rama_Y"},"change_message_id":"5b9ddc8073a3a19586f122c92b3c9cf34d32ddd1","unresolved":false,"context_lines":[{"line_number":111,"context_line":"  the system. This includes things like uncomment required configurations"},{"line_number":112,"context_line":"  in the generated file."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"* Improved the appearance of deprecated options in the generated sample file."},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"There are also some other efforts that are related to this work:"},{"line_number":117,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"dab17558_9b9409e9","line":114,"updated":"2016-05-13 22:59:57.000000000","message":"Hi, is it \"Improve\" instead of \"Improved\" as it is a proposed change? Thanks.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":122,"context_line":"  that don\u0027t have a valid value (including failing on required options that"},{"line_number":123,"context_line":"  are not set). This tool is aiming at a best effort check, not a full"},{"line_number":124,"context_line":"  validation. Initially it should focus on ensuring the keys are valid."},{"line_number":125,"context_line":"  Correct validation of all the values is much harder, and should by out of"},{"line_number":126,"context_line":"  scope for the first version. The initial version will only be able to check"},{"line_number":127,"context_line":"  if the values pass the olso_config type checks."},{"line_number":128,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_2b568406","line":125,"range":{"start_line":125,"start_character":59,"end_line":125,"end_character":68},"updated":"2016-04-21 16:06:26.000000000","message":"nit will be","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":124,"context_line":"  validation. Initially it should focus on ensuring the keys are valid."},{"line_number":125,"context_line":"  Correct validation of all the values is much harder, and should by out of"},{"line_number":126,"context_line":"  scope for the first version. The initial version will only be able to check"},{"line_number":127,"context_line":"  if the values pass the olso_config type checks."},{"line_number":128,"context_line":""},{"line_number":129,"context_line":"* There will need to be changes to the sphinx integration that helps generate"},{"line_number":130,"context_line":"  the documentation, to make use of these new conventions, in a similar way to"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_2b6de4cc","line":127,"range":{"start_line":127,"start_character":25,"end_line":127,"end_character":36},"updated":"2016-04-21 16:06:26.000000000","message":"nit oslo.config","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":133,"context_line":"Categorizing configuration options"},{"line_number":134,"context_line":"----------------------------------"},{"line_number":135,"context_line":""},{"line_number":136,"context_line":"To help solve the above problems, all projects could go through each of their"},{"line_number":137,"context_line":"options, looking at which configuration options should be marked with one of"},{"line_number":138,"context_line":"the following:"},{"line_number":139,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_4692d7a0","line":136,"range":{"start_line":136,"start_character":47,"end_line":136,"end_character":52},"updated":"2016-04-21 16:06:26.000000000","message":"I suggest \"may\"","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":144,"context_line":"    this option."},{"line_number":145,"context_line":""},{"line_number":146,"context_line":"  * Required options generally have empty defaults, but we should make use"},{"line_number":147,"context_line":"    of the ``sample_default`` option and the description, so it\u0027s easy for"},{"line_number":148,"context_line":"    operators to work out what value they need to set when doing the initial"},{"line_number":149,"context_line":"    setup of their cloud."},{"line_number":150,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_e69fa363","line":147,"updated":"2016-04-21 16:06:26.000000000","message":"do we need some tests to tell us about options missing sample_defaults etc?","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":15334,"name":"Stephen Finucane","display_name":"stephenfin","email":"stephenfin@redhat.com","username":"sfinucan"},"change_message_id":"8c5b460275b66215818ef55ce30afb97d7b2d509","unresolved":false,"context_lines":[{"line_number":137,"context_line":"options, looking at which configuration options should be marked with one of"},{"line_number":138,"context_line":"the following:"},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"},{"line_number":141,"context_line":""},{"line_number":142,"context_line":"  * Before marking an option as required, we should check that it\u0027s not"},{"line_number":143,"context_line":"    possible to have a better default, so the operator doesn\u0027t have to set"},{"line_number":144,"context_line":"    this option."},{"line_number":145,"context_line":""},{"line_number":146,"context_line":"  * Required options generally have empty defaults, but we should make use"},{"line_number":147,"context_line":"    of the ``sample_default`` option and the description, so it\u0027s easy for"},{"line_number":148,"context_line":"    operators to work out what value they need to set when doing the initial"},{"line_number":149,"context_line":"    setup of their cloud."},{"line_number":150,"context_line":""},{"line_number":151,"context_line":"* ``advanced\u003dTrue``: these options rarely need to be set by deployers"},{"line_number":152,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_a9206eb1","line":149,"range":{"start_line":140,"start_character":0,"end_line":149,"end_character":25},"updated":"2016-04-25 19:16:46.000000000","message":"I don\u0027t get the point of this option. Maybe it\u0027s a semantic thing, but IMO all non-null options are inherently \"required\", and not setting them is going to break the code in most cases. More importantly, a user should be able to take the sample Nova conf and run with that, which means the defaults should be sane defaults. This seems like a step away from that?\n\nMaybe we could mark some opts as \"important\", but this is sort of implicit via \"advanced\u003dFalse\"?","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"4c774dbd0b5be73c243078a910878c0959b1d00d","unresolved":false,"context_lines":[{"line_number":137,"context_line":"options, looking at which configuration options should be marked with one of"},{"line_number":138,"context_line":"the following:"},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"},{"line_number":141,"context_line":""},{"line_number":142,"context_line":"  * Before marking an option as required, we should check that it\u0027s not"},{"line_number":143,"context_line":"    possible to have a better default, so the operator doesn\u0027t have to set"},{"line_number":144,"context_line":"    this option."},{"line_number":145,"context_line":""},{"line_number":146,"context_line":"  * Required options generally have empty defaults, but we should make use"},{"line_number":147,"context_line":"    of the ``sample_default`` option and the description, so it\u0027s easy for"},{"line_number":148,"context_line":"    operators to work out what value they need to set when doing the initial"},{"line_number":149,"context_line":"    setup of their cloud."},{"line_number":150,"context_line":""},{"line_number":151,"context_line":"* ``advanced\u003dTrue``: these options rarely need to be set by deployers"},{"line_number":152,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"dab17558_2efdf56e","line":149,"range":{"start_line":140,"start_character":0,"end_line":149,"end_character":25},"in_reply_to":"1a122d0e_1f1b9081","updated":"2016-05-12 12:54:25.000000000","message":"so null/no default, is a valid default for some configuration options, in many cases that maps to \"auto\"","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"eb29f597bc658eeacb2e4fae987463853c4481bd","unresolved":false,"context_lines":[{"line_number":137,"context_line":"options, looking at which configuration options should be marked with one of"},{"line_number":138,"context_line":"the following:"},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"* ``required\u003dTrue``: you must set this during the initial setup"},{"line_number":141,"context_line":""},{"line_number":142,"context_line":"  * Before marking an option as required, we should check that it\u0027s not"},{"line_number":143,"context_line":"    possible to have a better default, so the operator doesn\u0027t have to set"},{"line_number":144,"context_line":"    this option."},{"line_number":145,"context_line":""},{"line_number":146,"context_line":"  * Required options generally have empty defaults, but we should make use"},{"line_number":147,"context_line":"    of the ``sample_default`` option and the description, so it\u0027s easy for"},{"line_number":148,"context_line":"    operators to work out what value they need to set when doing the initial"},{"line_number":149,"context_line":"    setup of their cloud."},{"line_number":150,"context_line":""},{"line_number":151,"context_line":"* ``advanced\u003dTrue``: these options rarely need to be set by deployers"},{"line_number":152,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_1f1b9081","line":149,"range":{"start_line":140,"start_character":0,"end_line":149,"end_character":25},"in_reply_to":"1a122d0e_a9206eb1","updated":"2016-04-25 21:43:40.000000000","message":"So sample_default already exists today.  The main issue is how it\u0027s presented in sample files.  Right now, it overrides a default value or null default value, basically giving a false indication that there is a default value or overriding the actual default value.  We would present the sample_default as an example if no default exists or if a default exists treat it as an example, but not override.\n\nThe required\u003dTrue is any option that is absolutely required to start a service and requires input.  These options would be put to the top of the section and uncommented in sample files.  This would allow users to easily see where input is required and not have to dig into the sample files to figure this out.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":156,"context_line":"* Review configuration option groups and their descriptions"},{"line_number":157,"context_line":""},{"line_number":158,"context_line":"  * Every group should have a description set. This is done by using"},{"line_number":159,"context_line":"    ``OptGroup`` and it\u0027s help attribute."},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"  * Many options are already in a configuration group. Having a good set of"},{"line_number":162,"context_line":"    groups makes it easier to understand the full list of configuration"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_4622d702","line":159,"range":{"start_line":159,"start_character":21,"end_line":159,"end_character":25},"updated":"2016-04-21 16:06:26.000000000","message":"sorry, \"its\" - possessives usually use an apostrophe but not when the noun is it :)","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":15334,"name":"Stephen Finucane","display_name":"stephenfin","email":"stephenfin@redhat.com","username":"sfinucan"},"change_message_id":"8c5b460275b66215818ef55ce30afb97d7b2d509","unresolved":false,"context_lines":[{"line_number":168,"context_line":"  deprecated_reason to state when it is planned to be removed, and give extra"},{"line_number":169,"context_line":"  context on why it is being removed."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"  * We should remove the need to add \"DEPRECATED\" as the first words of the"},{"line_number":172,"context_line":"    help text for such options, by ensuring the documentation and sample file"},{"line_number":173,"context_line":"    generators do that work for us."},{"line_number":174,"context_line":""},{"line_number":175,"context_line":"We may add more categories over time, but this should help with the use cases"},{"line_number":176,"context_line":"described above. The required options make it clear what things must be set"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_291bbe81","line":173,"range":{"start_line":171,"start_character":0,"end_line":173,"end_character":35},"updated":"2016-04-25 19:16:46.000000000","message":"oops :) https://review.openstack.org/#/c/307685/ I\u0027ll change the subject when/if this is approved","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":218,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"},{"line_number":219,"context_line":"    # min value, max value, 0, -1) and what they mean."},{"line_number":220,"context_line":"    # Further, for choices which are not obviously named, please describe"},{"line_number":221,"context_line":"    # the affect of each choice."},{"line_number":222,"context_line":"    # Note: this should not duplicate the information that is defined in"},{"line_number":223,"context_line":"    # the option, such as -1 is the min_value, the aim here is to describe"},{"line_number":224,"context_line":"    # what and special values mean in the context of this option."}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_86a6af51","line":221,"range":{"start_line":221,"start_character":10,"end_line":221,"end_character":16},"updated":"2016-04-21 16:06:26.000000000","message":"nit I affect, an effect","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":5202,"name":"Erno Kuvaja","email":"jokke@usr.fi","username":"jokke"},"change_message_id":"9a1351eca545dd0545a4508c8eda5115521290ae","unresolved":false,"context_lines":[{"line_number":229,"context_line":"    # one? If it stands solely on its own, use \"None\"."},{"line_number":230,"context_line":"    # Note: this does not replace the new Opt.related_options, it used"},{"line_number":231,"context_line":"    # when extra details are required."},{"line_number":232,"context_line":""},{"line_number":233,"context_line":"When reviewing the description of the configuration, it\u0027s worth reviewing the"},{"line_number":234,"context_line":"other parameters passed to ``oslo.config``. There have been features added to"},{"line_number":235,"context_line":"make the opt definition more precise, but some of the options have not been"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bab6814e_d2120058","line":232,"updated":"2016-05-24 11:17:00.000000000","message":"Hemanth started to implement this principle in the Glance lately and it looked really neat in the code. Then I started to look what config generator brings in and how this templating would sit into our config files (as all the helptext is included there) and it comes horrible. We\u0027re talking about XXXX lines of clutter in a small set (Glance has ~120 config options of it\u0027s own split to multiple config files for each service).\n\nSo I sent my entreat out http://lists.openstack.org/pipermail/openstack-dev/2016-May/095760.html\n\nPlease let\u0027s keep the clutter out of the config files and utilize our documentations for more detailed info.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":268,"context_line":""},{"line_number":269,"context_line":"Note the above is assuming deployers that base their deployments on updates"},{"line_number":270,"context_line":"to a freshly generated sample file are using tooling that is not affected"},{"line_number":271,"context_line":"by the ordering of the sample file. As far as the oslo_config library is"},{"line_number":272,"context_line":"concerned, the order of values in the file doesn\u0027t make any difference."},{"line_number":273,"context_line":""},{"line_number":274,"context_line":"Centralize Configuration options (optional)"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_a18f5574","line":271,"range":{"start_line":271,"start_character":50,"end_line":271,"end_character":61},"updated":"2016-04-21 16:06:26.000000000","message":"femtonit: oslo.config","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":335,"context_line":"avoiding potential problems referenced in the `original mailing list thread`_"},{"line_number":336,"context_line":"with circular dependencies caused by ``import_opt``."},{"line_number":337,"context_line":"You can see an example of what is being done here:"},{"line_number":338,"context_line":"https://git.openstack.org/cgit/openstack/nova/tree/nova/conf/pci.py"},{"line_number":339,"context_line":""},{"line_number":340,"context_line":"We also use a \"single point of entry\" for the generation of the sample"},{"line_number":341,"context_line":"configuration file. This helps make it much harder to accidentally leave out"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_2143456e","line":338,"updated":"2016-04-21 16:06:26.000000000","message":"How should projects not heavily tied to this idea do it? Maybe:\n\n import nova.foo_conf\n import nova.bar_conf\n\n FOO_CONF \u003d nova.foo_conf.CONF\n BAR_CONF \u003d nova.bar_conf.CONF","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"82fa70e970be7ad2d6e5a49322e7387644ff997b","unresolved":false,"context_lines":[{"line_number":335,"context_line":"avoiding potential problems referenced in the `original mailing list thread`_"},{"line_number":336,"context_line":"with circular dependencies caused by ``import_opt``."},{"line_number":337,"context_line":"You can see an example of what is being done here:"},{"line_number":338,"context_line":"https://git.openstack.org/cgit/openstack/nova/tree/nova/conf/pci.py"},{"line_number":339,"context_line":""},{"line_number":340,"context_line":"We also use a \"single point of entry\" for the generation of the sample"},{"line_number":341,"context_line":"configuration file. This helps make it much harder to accidentally leave out"}],"source_content_type":"text/x-rst","patch_set":9,"id":"dab17558_6eda5deb","line":338,"in_reply_to":"1a122d0e_2143456e","updated":"2016-05-12 12:57:45.000000000","message":"some libs can just define options locally, as thats the only place they are used, and that can work OK.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"7a64b65d05d98bc122baffec659cf6750339f23d","unresolved":false,"context_lines":[{"line_number":335,"context_line":"avoiding potential problems referenced in the `original mailing list thread`_"},{"line_number":336,"context_line":"with circular dependencies caused by ``import_opt``."},{"line_number":337,"context_line":"You can see an example of what is being done here:"},{"line_number":338,"context_line":"https://git.openstack.org/cgit/openstack/nova/tree/nova/conf/pci.py"},{"line_number":339,"context_line":""},{"line_number":340,"context_line":"We also use a \"single point of entry\" for the generation of the sample"},{"line_number":341,"context_line":"configuration file. This helps make it much harder to accidentally leave out"}],"source_content_type":"text/x-rst","patch_set":9,"id":"dab17558_4178fe8f","line":338,"in_reply_to":"dab17558_6eda5deb","updated":"2016-05-12 17:32:23.000000000","message":"Yes, I would not expect the handling of options in Oslo libs to change as the result of this spec. We define them inline and register them on a config object passed in to the library (rather than the global object) as a matter of design policy within Oslo.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"7a64b65d05d98bc122baffec659cf6750339f23d","unresolved":false,"context_lines":[{"line_number":342,"context_line":"options from the generated sample configuration file. The doc job generates"},{"line_number":343,"context_line":"a sample config file on every build, to keep it working."},{"line_number":344,"context_line":"You can see more details on how that works here:"},{"line_number":345,"context_line":"https://github.com/openstack/nova/blob/master/nova/conf/opts.py"},{"line_number":346,"context_line":""},{"line_number":347,"context_line":"Alternatives"},{"line_number":348,"context_line":"------------"}],"source_content_type":"text/x-rst","patch_set":9,"id":"dab17558_c1d98e85","line":345,"updated":"2016-05-12 17:32:23.000000000","message":"This isn\u0027t something we should enforce across projects. Some, such as glance, generate different sample configuration files based on the service since some of the options don\u0027t apply to some of the services. We want to continue to support this, because it makes the config reference and config sample files more usable.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"1959ea103ae83cf6149a3005219f9a86fa4b4a89","unresolved":false,"context_lines":[{"line_number":342,"context_line":"options from the generated sample configuration file. The doc job generates"},{"line_number":343,"context_line":"a sample config file on every build, to keep it working."},{"line_number":344,"context_line":"You can see more details on how that works here:"},{"line_number":345,"context_line":"https://github.com/openstack/nova/blob/master/nova/conf/opts.py"},{"line_number":346,"context_line":""},{"line_number":347,"context_line":"Alternatives"},{"line_number":348,"context_line":"------------"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bab6814e_2c5dfeec","line":345,"in_reply_to":"dab17558_c1d98e85","updated":"2016-05-24 08:58:28.000000000","message":"Yeah, I thought I tried to word this as optional, to try and represent that. I should take another look.\n\nI certainly want to bring some level of split out samples to Nova soon, if possible.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":354,"context_line":"   deprecated, it seems easiest to add \"advanced\" rather than deprecate all"},{"line_number":355,"context_line":"   the old flags and add a new category flag. However, this spec is mostly"},{"line_number":356,"context_line":"   worrying about consistent use of these features. The implementation should"},{"line_number":357,"context_line":"   be agreed by the team working on oslo_config"},{"line_number":358,"context_line":""},{"line_number":359,"context_line":"#. Could use sub groups of options, rather than adding advanced to oslo_config"},{"line_number":360,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_0573b4b5","line":357,"updated":"2016-04-21 16:06:26.000000000","message":"Being able to tag an option as a member of multiple trans-group sets appeals more than a boolean.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"7a64b65d05d98bc122baffec659cf6750339f23d","unresolved":false,"context_lines":[{"line_number":354,"context_line":"   deprecated, it seems easiest to add \"advanced\" rather than deprecate all"},{"line_number":355,"context_line":"   the old flags and add a new category flag. However, this spec is mostly"},{"line_number":356,"context_line":"   worrying about consistent use of these features. The implementation should"},{"line_number":357,"context_line":"   be agreed by the team working on oslo_config"},{"line_number":358,"context_line":""},{"line_number":359,"context_line":"#. Could use sub groups of options, rather than adding advanced to oslo_config"},{"line_number":360,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"dab17558_c1f50ecc","line":357,"in_reply_to":"1a122d0e_0573b4b5","updated":"2016-05-12 17:32:23.000000000","message":"The config reference generation has a similar tagging concept in place for selecting a few options out of a larger group to provide some description for the subset. The doc team manages this mapping in their source tree, but we\u0027re talking with them about adding it to the option definitions directly. Perhaps we can reuse the same capability here instead of adding the boolean flag?","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"1eb3575d0d7171ca66bc0c47cc9348cc282653e1","unresolved":false,"context_lines":[{"line_number":364,"context_line":"   sample file. While we could have a group name convention of \u003cit\u003e.advanced"},{"line_number":365,"context_line":"   it is not easy to have tools that don\u0027t add the advanced options into the"},{"line_number":366,"context_line":"   sample file, or a toggle to hide such options when reviewing the docs."},{"line_number":367,"context_line":"   An middle group may be to use this approach while we test out the"},{"line_number":368,"context_line":"   usefulness of this distinction."},{"line_number":369,"context_line":""},{"line_number":370,"context_line":"#. Use data files to provide configuration options to the operator."}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_c5b89c2d","line":367,"range":{"start_line":367,"start_character":3,"end_line":367,"end_character":18},"updated":"2016-04-21 16:06:26.000000000","message":"a middle way?","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"2fb9447acaa45fdab2a1bc1436fdee79b17a8f2c","unresolved":false,"context_lines":[{"line_number":365,"context_line":"   it is not easy to have tools that don\u0027t add the advanced options into the"},{"line_number":366,"context_line":"   sample file, or a toggle to hide such options when reviewing the docs."},{"line_number":367,"context_line":"   An middle group may be to use this approach while we test out the"},{"line_number":368,"context_line":"   usefulness of this distinction."},{"line_number":369,"context_line":""},{"line_number":370,"context_line":"#. Use data files to provide configuration options to the operator."},{"line_number":371,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_7a403b36","line":368,"updated":"2016-04-21 18:24:40.000000000","message":"I do like the idea of at least testing the move, but if we move the options through the deprecation machinery this cycle we would have to wait I think before we could move them back. \n\nWe could also consider adding the advanced flag to the group, rather than the individual options.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"},{"author":{"_account_id":2472,"name":"Doug Hellmann","email":"dhellmann@redhat.com","username":"doug-hellmann"},"change_message_id":"2fb9447acaa45fdab2a1bc1436fdee79b17a8f2c","unresolved":false,"context_lines":[{"line_number":375,"context_line":"#. Don\u0027t add which service uses a configuration option in the comments use"},{"line_number":376,"context_line":"   oslo generator\u0027s ability to generate a separate config file for each"},{"line_number":377,"context_line":"   service."},{"line_number":378,"context_line":"   Needs thought on how this gets integrated into the doc generation."},{"line_number":379,"context_line":""},{"line_number":380,"context_line":"Implementation"},{"line_number":381,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a122d0e_1aa947e0","line":378,"updated":"2016-04-21 18:24:40.000000000","message":"I think that both forms of the doc generation support the same input file argument as the config generator. If not, we can certainly extend it.","commit_id":"fc649d03cf86b09956c41658cdc1988cb3b7fc5b"}],"specs/centralized-configuration-option-definition.rst":[{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"250cf310d24ff8216041cd847dc0f6bedfb9286b","unresolved":false,"context_lines":[{"line_number":29,"context_line":""},{"line_number":30,"context_line":"- shows their interdependency with other configuration options"},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"- and explains which of the components of the service they influence"},{"line_number":33,"context_line":""},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"Proposed change"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_27aa6f19","line":32,"updated":"2016-03-24 12:43:31.000000000","message":"Please see the new name, and ideas here:\nhttps://review.openstack.org/#/c/291406/7","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":29,"context_line":""},{"line_number":30,"context_line":"- shows their interdependency with other configuration options"},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"- and explains which of the components of the service they influence"},{"line_number":33,"context_line":""},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"Proposed change"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_3e44ff72","line":32,"in_reply_to":"fa0719c6_27aa6f19","updated":"2016-03-28 23:44:33.000000000","message":"Done","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"fbf09d84ab9f41566e1eda2a55f1e60a85602484","unresolved":false,"context_lines":[{"line_number":42,"context_line":""},{"line_number":43,"context_line":"1. The technical centralization of the options (described briefly above)"},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"1. The quality control of the each option\u0027s description"},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"The **technical component** of this centralization is the recommendation that"},{"line_number":48,"context_line":"projects follow a design like Nova\u0027s current design. In particular, Nova has"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_c545dd70","line":45,"updated":"2016-03-22 17:16:06.000000000","message":"Need 2. here","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":42,"context_line":""},{"line_number":43,"context_line":"1. The technical centralization of the options (described briefly above)"},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"1. The quality control of the each option\u0027s description"},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"The **technical component** of this centralization is the recommendation that"},{"line_number":48,"context_line":"projects follow a design like Nova\u0027s current design. In particular, Nova has"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_1ecf7bb1","line":45,"in_reply_to":"fa0719c6_c545dd70","updated":"2016-03-28 23:44:33.000000000","message":"reStructuredText does this wonderful thing where you don\u0027t need to enumerate each number. That said, I was using Markdown\u0027s equivalent instead of reStructuredText\u0027s. Fixed.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":8434,"name":"Rochelle Grober","email":"rochelle.grober@huawei.com","username":"rockyg"},"change_message_id":"37b9de44e9f3f4f3612929b18be8989a856191ba","unresolved":false,"context_lines":[{"line_number":45,"context_line":"1. The quality control of the each option\u0027s description"},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"The **technical component** of this centralization is the recommendation that"},{"line_number":48,"context_line":"projects follow a design like Nova\u0027s current design. In particular, Nova has"},{"line_number":49,"context_line":"structured their configuration centralization like so:"},{"line_number":50,"context_line":""},{"line_number":51,"context_line":".. code::"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_c0fe6037","line":48,"updated":"2016-03-22 21:36:23.000000000","message":"\"follow a design similar to\" would be better here.  It gives a bit more room for projects that are different enough from Nova to be confused about some/all of Nova\u0027s choices in implementation.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":45,"context_line":"1. The quality control of the each option\u0027s description"},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"The **technical component** of this centralization is the recommendation that"},{"line_number":48,"context_line":"projects follow a design like Nova\u0027s current design. In particular, Nova has"},{"line_number":49,"context_line":"structured their configuration centralization like so:"},{"line_number":50,"context_line":""},{"line_number":51,"context_line":".. code::"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_3e123f63","line":48,"in_reply_to":"fa0719c6_c0fe6037","updated":"2016-03-28 23:44:33.000000000","message":"Done","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"fbf09d84ab9f41566e1eda2a55f1e60a85602484","unresolved":false,"context_lines":[{"line_number":75,"context_line":"and listed via a uniform API."},{"line_number":76,"context_line":""},{"line_number":77,"context_line":"Further, the ``__init__.py`` file for ``nova.conf`` holds a single ``CONF``"},{"line_number":78,"context_line":"object and registers all of the options to it so that consumers can simply do:"},{"line_number":79,"context_line":""},{"line_number":80,"context_line":".. code-block:: python"},{"line_number":81,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_257e59ae","line":78,"updated":"2016-03-22 17:16:06.000000000","message":"This is an excellent approach to centralizing.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":8873,"name":"Assaf Muller","email":"amuller@redhat.com","username":"amuller"},"change_message_id":"1b743fb32851ce306aa07c2205ed632bfb9b2964","unresolved":false,"context_lines":[{"line_number":77,"context_line":"Further, the ``__init__.py`` file for ``nova.conf`` holds a single ``CONF``"},{"line_number":78,"context_line":"object and registers all of the options to it so that consumers can simply do:"},{"line_number":79,"context_line":""},{"line_number":80,"context_line":".. code-block:: python"},{"line_number":81,"context_line":""},{"line_number":82,"context_line":"    import nova.conf"},{"line_number":83,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_30a42e56","line":80,"updated":"2016-03-28 22:25:25.000000000","message":"For testing purposes I\u0027d like to see a way to avoid the global CONF object, and instead to do something like:\n\nimport nova.conf\nCONF \u003d nova.conf.register_options()\n\nThis way each test can have its own Oslo config instance, separate from that of the test runner. Sometimes we also register multiple Oslo config instances for a single test, so we definitely need a way to keep doing that.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":9656,"name":"Ihar Hrachyshka","email":"ihrachys@redhat.com","username":"ihrachys","status":"Red Hat Networking Systems Engineer"},"change_message_id":"682b3ae1918a567159d108a17ef480f1d60f6428","unresolved":false,"context_lines":[{"line_number":92,"context_line":"provided for each option of relocated options in Nova now describes what each"},{"line_number":93,"context_line":"option does, what other options are related to it,  and which of Nova\u0027s"},{"line_number":94,"context_line":"services rely on it. When used with Oslo\u0027s confguration generator tooling,"},{"line_number":95,"context_line":"this provides very well documented example configuration files."},{"line_number":96,"context_line":""},{"line_number":97,"context_line":"A generic template for help text was provided as part of the Nova"},{"line_number":98,"context_line":"specification and is replicated here for simplicity:"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_8904db15","line":95,"updated":"2016-03-29 13:02:33.000000000","message":"It may not apply to those services that already separate their options into per-agent files. Like in Neutron, we maintain global + neutron-server options in neutron.conf, and each agent has a separate file for it, like openvswitch_agent.ini.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":8434,"name":"Rochelle Grober","email":"rochelle.grober@huawei.com","username":"rockyg"},"change_message_id":"37b9de44e9f3f4f3612929b18be8989a856191ba","unresolved":false,"context_lines":[{"line_number":108,"context_line":"    Services which consume this:"},{"line_number":109,"context_line":""},{"line_number":110,"context_line":"    # A list of services which consume this option. Operators should not"},{"line_number":111,"context_line":"    # read code to know which one of the services will change its behavior."},{"line_number":112,"context_line":"    # Nor should they set this in every ``nova.conf`` file to be sure."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"    Possible values:"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_bb0f212d","line":111,"updated":"2016-03-22 21:36:23.000000000","message":"should not be required to read code to discover which one of the services\u0027 behavior will be affected.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":108,"context_line":"    Services which consume this:"},{"line_number":109,"context_line":""},{"line_number":110,"context_line":"    # A list of services which consume this option. Operators should not"},{"line_number":111,"context_line":"    # read code to know which one of the services will change its behavior."},{"line_number":112,"context_line":"    # Nor should they set this in every ``nova.conf`` file to be sure."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"    Possible values:"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_1ee2db03","line":111,"in_reply_to":"fa0719c6_bb0f212d","updated":"2016-03-28 23:44:33.000000000","message":"Done","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"fbf09d84ab9f41566e1eda2a55f1e60a85602484","unresolved":false,"context_lines":[{"line_number":111,"context_line":"    # read code to know which one of the services will change its behavior."},{"line_number":112,"context_line":"    # Nor should they set this in every ``nova.conf`` file to be sure."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"    Possible values:"},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"    # description of possible values. Especially if this is an option"},{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_e80f182c","line":114,"updated":"2016-03-22 17:16:06.000000000","message":"Should try to make use of the choices \u003d [\u0027choice_a\u0027,\u0027choice_b\u0027] as this provides a nice output in oslo config generator.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"3e929c62c941e548c615cd856047fe312c531222","unresolved":false,"context_lines":[{"line_number":111,"context_line":"    # read code to know which one of the services will change its behavior."},{"line_number":112,"context_line":"    # Nor should they set this in every ``nova.conf`` file to be sure."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"    Possible values:"},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"    # description of possible values. Especially if this is an option"},{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_fb2fc085","line":114,"in_reply_to":"fa0719c6_5b5fe5e4","updated":"2016-03-23 10:54:21.000000000","message":"@Rochelle: The \"oslo.config\" opts provide already the attributes \"default\" and \"required\", which should be used where possible. The oslo-config-generator outputs the default values (but not the info if they are required).","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":8434,"name":"Rochelle Grober","email":"rochelle.grober@huawei.com","username":"rockyg"},"change_message_id":"37b9de44e9f3f4f3612929b18be8989a856191ba","unresolved":false,"context_lines":[{"line_number":111,"context_line":"    # read code to know which one of the services will change its behavior."},{"line_number":112,"context_line":"    # Nor should they set this in every ``nova.conf`` file to be sure."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"    Possible values:"},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"    # description of possible values. Especially if this is an option"},{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_5b5fe5e4","line":114,"in_reply_to":"fa0719c6_8f7adeef","updated":"2016-03-22 21:36:23.000000000","message":"Also state what the default value is (or none/nil/etc) and whether the option is required always or only if set to nondefault values.  This is to make sure the pattern here and for Related options are consistent.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"0bbe6c1bcd2e02ffc1b1c10335d03cf495d9d81a","unresolved":false,"context_lines":[{"line_number":111,"context_line":"    # read code to know which one of the services will change its behavior."},{"line_number":112,"context_line":"    # Nor should they set this in every ``nova.conf`` file to be sure."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"    Possible values:"},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"    # description of possible values. Especially if this is an option"},{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_8f7adeef","line":114,"in_reply_to":"fa0719c6_e80f182c","updated":"2016-03-22 18:46:26.000000000","message":"+1 on choices, this was really here to describe the edge cases, but we should be more precise on its usage.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":111,"context_line":"    # read code to know which one of the services will change its behavior."},{"line_number":112,"context_line":"    # Nor should they set this in every ``nova.conf`` file to be sure."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"    Possible values:"},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"    # description of possible values. Especially if this is an option"},{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_3edd1f43","line":114,"in_reply_to":"fa0719c6_fb2fc085","updated":"2016-03-28 23:44:33.000000000","message":"So at the moment, you can use choices to provide a list, but the description of what each choice does is not necessarily obvious at all times. For that reasoning, I\u0027m choosing to keep this with a better description of why you would include the possible values.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"fbf09d84ab9f41566e1eda2a55f1e60a85602484","unresolved":false,"context_lines":[{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"},{"line_number":118,"context_line":"    # min value, max value, 0, -1)."},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"    Related options:"},{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_2848f05a","line":120,"updated":"2016-03-22 17:16:06.000000000","message":"Would be nice to put this in as a parameter in olso.config with a decent output.\n\n# Related Options: option_b, option_c, option_d\noption_a \u003d myvalue","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"0bbe6c1bcd2e02ffc1b1c10335d03cf495d9d81a","unresolved":false,"context_lines":[{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"},{"line_number":118,"context_line":"    # min value, max value, 0, -1)."},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"    Related options:"},{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_af87e2d5","line":120,"in_reply_to":"fa0719c6_2848f05a","updated":"2016-03-22 18:46:26.000000000","message":"+1 on that","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"3e929c62c941e548c615cd856047fe312c531222","unresolved":false,"context_lines":[{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"},{"line_number":118,"context_line":"    # min value, max value, 0, -1)."},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"    Related options:"},{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_a0e513dd","line":120,"in_reply_to":"fa0719c6_2848f05a","updated":"2016-03-23 10:54:21.000000000","message":"@Brian: +1 That would be great. We\u0027ve chosen the \"free form\" approach in Nova to start right away in Mitaka without a new version of \"oslo.config\". It also made a good template to give a hint to even think about related options (like we do with features in the spec template).","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":117,"context_line":"    # with numeric values (int, float), describe the edge cases (like the"},{"line_number":118,"context_line":"    # min value, max value, 0, -1)."},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"    Related options:"},{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_fe03a774","line":120,"in_reply_to":"fa0719c6_a0e513dd","updated":"2016-03-28 23:44:33.000000000","message":"Certainly oslo.config could use some metadata, but I think having this be more \"free form\" allows a developer to explain how it affects an option in default. Unless the effect is described in the long description. I think calling this out specifically will provoke thought from the developer and reviewer alike.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"fbf09d84ab9f41566e1eda2a55f1e60a85602484","unresolved":false,"context_lines":[{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"Alternatives"},{"line_number":126,"context_line":"------------"},{"line_number":127,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_28aab070","line":124,"updated":"2016-03-22 17:16:06.000000000","message":"Also, for options that require editing, the default should state that it requires this.  We should fix the sample_default behavior so it outputs something a bit more friendly.\n\n# Example: option_a \u003d http://www.myurl.com:9696/v2.0\noption_a \u003d \u003cREQUIRES_INPUT\u003e\n\nToday, the sample_default overrides the default on output.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"3e929c62c941e548c615cd856047fe312c531222","unresolved":false,"context_lines":[{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"Alternatives"},{"line_number":126,"context_line":"------------"},{"line_number":127,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_5b06ac86","line":124,"in_reply_to":"fa0719c6_0fdd2ee0","updated":"2016-03-23 10:54:21.000000000","message":"@John: True. In Nova we used phrases like \"you probably never have to change the default value unless you know exactly what you\u0027re doing\" or similar hints.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"3e929c62c941e548c615cd856047fe312c531222","unresolved":false,"context_lines":[{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"Alternatives"},{"line_number":126,"context_line":"------------"},{"line_number":127,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_5b918c46","line":124,"in_reply_to":"fa0719c6_28aab070","updated":"2016-03-23 10:54:21.000000000","message":"@Brian: Rochelle commented on line 114 for the \"required\" attribute. I tested locally with an option which had \"required\u003dTrue\" and no default value. The oslo-config-generator didn\u0027t output a hint that this option is required and will result in a fail of the service if not provided.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"0bbe6c1bcd2e02ffc1b1c10335d03cf495d9d81a","unresolved":false,"context_lines":[{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"Alternatives"},{"line_number":126,"context_line":"------------"},{"line_number":127,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_0fdd2ee0","line":124,"in_reply_to":"fa0719c6_28aab070","updated":"2016-03-22 18:46:26.000000000","message":"Yeah, lets make it clear what needs to be changed, and make that first usage easier.\n\nAlso make it clear what are \"advanced\" options that most folk don\u0027t want to tweak.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"cd7d11e46f204a14b41ec9cdbbb912dd65ce92f2","unresolved":false,"context_lines":[{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"Alternatives"},{"line_number":126,"context_line":"------------"},{"line_number":127,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_c94b0186","line":124,"in_reply_to":"fa0719c6_5b918c46","updated":"2016-03-23 15:45:14.000000000","message":"@Markus: We discussed this.  Required might be better suited to uncomment the option on the sample file output and bubble it up to the top of the section or subsection and marked as required.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":121,"context_line":""},{"line_number":122,"context_line":"    # Which other config options have to be considered when I change this"},{"line_number":123,"context_line":"    # one? If it stand solely on its own, use \"None\""},{"line_number":124,"context_line":""},{"line_number":125,"context_line":"Alternatives"},{"line_number":126,"context_line":"------------"},{"line_number":127,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_fe49e78f","line":124,"in_reply_to":"fa0719c6_c94b0186","updated":"2016-03-28 23:44:33.000000000","message":"Done","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"fbf09d84ab9f41566e1eda2a55f1e60a85602484","unresolved":false,"context_lines":[{"line_number":130,"context_line":"   For most projects (e.g., Nova) this is unreasonable and would result in"},{"line_number":131,"context_line":"   merge conflicts and an incredibly large file."},{"line_number":132,"context_line":""},{"line_number":133,"context_line":"1. Use data files to provide configuration options to the operator."},{"line_number":134,"context_line":""},{"line_number":135,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":136,"context_line":"   updated as frequently as the options themselves will be."}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_08d36c05","line":133,"updated":"2016-03-22 17:16:06.000000000","message":"Need 2.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":130,"context_line":"   For most projects (e.g., Nova) this is unreasonable and would result in"},{"line_number":131,"context_line":"   merge conflicts and an incredibly large file."},{"line_number":132,"context_line":""},{"line_number":133,"context_line":"1. Use data files to provide configuration options to the operator."},{"line_number":134,"context_line":""},{"line_number":135,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":136,"context_line":"   updated as frequently as the options themselves will be."}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_7e7797d4","line":133,"in_reply_to":"fa0719c6_08d36c05","updated":"2016-03-28 23:44:33.000000000","message":"Done","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":19611,"name":"Brian Stajkowski","email":"brian.stajkowski@rackspace.com","username":"ski"},"change_message_id":"fbf09d84ab9f41566e1eda2a55f1e60a85602484","unresolved":false,"context_lines":[{"line_number":135,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":136,"context_line":"   updated as frequently as the options themselves will be."},{"line_number":137,"context_line":""},{"line_number":138,"context_line":"1. Use a global object to control access to the ``CONF`` object."},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"   This would allow for a number of things - testability, cleaner code, and"},{"line_number":141,"context_line":"   the ability to follow Object-Oriented Programming best practices - but an"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_48dd640d","line":138,"updated":"2016-03-22 17:16:06.000000000","message":"Need 3.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"3e929c62c941e548c615cd856047fe312c531222","unresolved":false,"context_lines":[{"line_number":135,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":136,"context_line":"   updated as frequently as the options themselves will be."},{"line_number":137,"context_line":""},{"line_number":138,"context_line":"1. Use a global object to control access to the ``CONF`` object."},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"   This would allow for a number of things - testability, cleaner code, and"},{"line_number":141,"context_line":"   the ability to follow Object-Oriented Programming best practices - but an"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_fbe2202e","line":138,"in_reply_to":"fa0719c6_2cf2b26f","updated":"2016-03-23 10:54:21.000000000","message":"I\u0027m with Ken here. \u0027#\u0027 is the easiest and makes a reshuffle of list items easier too. But that\u0027s just a nit from my POV.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":16157,"name":"Ken Johnston","email":"kenny@kencjohnston.com","username":"kencjohnston"},"change_message_id":"08203f377edd5fc8b66ade1e60320ccb2979ebef","unresolved":false,"context_lines":[{"line_number":135,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":136,"context_line":"   updated as frequently as the options themselves will be."},{"line_number":137,"context_line":""},{"line_number":138,"context_line":"1. Use a global object to control access to the ``CONF`` object."},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"   This would allow for a number of things - testability, cleaner code, and"},{"line_number":141,"context_line":"   the ability to follow Object-Oriented Programming best practices - but an"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_2cf2b26f","line":138,"in_reply_to":"fa0719c6_2ff9124e","updated":"2016-03-23 01:34:47.000000000","message":"Another option is to use \u0027#.\u0027 and it will automatically fill the numbers.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"0bbe6c1bcd2e02ffc1b1c10335d03cf495d9d81a","unresolved":false,"context_lines":[{"line_number":135,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":136,"context_line":"   updated as frequently as the options themselves will be."},{"line_number":137,"context_line":""},{"line_number":138,"context_line":"1. Use a global object to control access to the ``CONF`` object."},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"   This would allow for a number of things - testability, cleaner code, and"},{"line_number":141,"context_line":"   the ability to follow Object-Oriented Programming best practices - but an"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_2ff9124e","line":138,"in_reply_to":"fa0719c6_48dd640d","updated":"2016-03-22 18:46:26.000000000","message":"technically, its fine, as it will get rendered correctly, although agree it looks funny here.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":135,"context_line":"   The concern is that if not side-by-side with the code, this would not be"},{"line_number":136,"context_line":"   updated as frequently as the options themselves will be."},{"line_number":137,"context_line":""},{"line_number":138,"context_line":"1. Use a global object to control access to the ``CONF`` object."},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"   This would allow for a number of things - testability, cleaner code, and"},{"line_number":141,"context_line":"   the ability to follow Object-Oriented Programming best practices - but an"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_de67c323","line":138,"in_reply_to":"fa0719c6_fbe2202e","updated":"2016-03-28 23:44:33.000000000","message":"Done","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"3e929c62c941e548c615cd856047fe312c531222","unresolved":false,"context_lines":[{"line_number":139,"context_line":""},{"line_number":140,"context_line":"   This would allow for a number of things - testability, cleaner code, and"},{"line_number":141,"context_line":"   the ability to follow Object-Oriented Programming best practices - but an"},{"line_number":142,"context_line":"   `initial implementation`_ proved it to be cumbersome."},{"line_number":143,"context_line":""},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"Implementation"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_5b334c14","line":142,"range":{"start_line":142,"start_character":36,"end_line":142,"end_character":55},"updated":"2016-03-23 10:54:21.000000000","message":"A little context: I spent 3 days for the failed PoC. The possibility to declare a config option as \"mutable\" will add a little more complexity to that too. This means a config option can be changed during the runtime of a service. Before that, each service has to be restarted to make use of a changed config option value.\n\n[1] http://docs.openstack.org/developer/oslo.config/opts.html","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":308,"name":"Thierry Carrez","email":"thierry@openstack.org","username":"ttx"},"change_message_id":"069be943789bc952f21c571e6a3d16bc611d4b69","unresolved":false,"context_lines":[{"line_number":158,"context_line":"Work Items"},{"line_number":159,"context_line":"----------"},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"TODO"},{"line_number":162,"context_line":""},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"Dependencies"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_5592edf6","line":161,"updated":"2016-03-23 13:53:24.000000000","message":"Could you list the affected projects ? I suspect most of them are, so this would give a rough idea of the amount of work involved in this spec.","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":158,"context_line":"Work Items"},{"line_number":159,"context_line":"----------"},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"TODO"},{"line_number":162,"context_line":""},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"Dependencies"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_9ea70b4f","line":161,"in_reply_to":"fa0719c6_5592edf6","updated":"2016-03-28 23:44:33.000000000","message":"Done","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":11303,"name":"Markus Zoeller (markus_z)","email":"mzoeller@linux.vnet.ibm.com","username":"mzoeller"},"change_message_id":"04cab3986833044ce8087b551985b4ddacb48e61","unresolved":false,"context_lines":[{"line_number":173,"context_line":".. list-table:: Revisions"},{"line_number":174,"context_line":"   :header-rows: 1"},{"line_number":175,"context_line":""},{"line_number":176,"context_line":"   * - Newton"},{"line_number":177,"context_line":"     - Introduced"},{"line_number":178,"context_line":""},{"line_number":179,"context_line":".. note::"},{"line_number":180,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa0719c6_36678d4e","line":177,"range":{"start_line":176,"start_character":0,"end_line":177,"end_character":17},"updated":"2016-03-23 11:02:55.000000000","message":"Should be:\n\n   * - Release Name\n     - Description\n   * - Newton\n     - Introduced\n\nOtherwise the \"header-rows: 1\" will result in an error","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"468eda34e6d45db7aceeba2b65c80e47d3f67252","unresolved":false,"context_lines":[{"line_number":174,"context_line":"   :header-rows: 1"},{"line_number":175,"context_line":""},{"line_number":176,"context_line":"   * - Newton"},{"line_number":177,"context_line":"     - Introduced"},{"line_number":178,"context_line":""},{"line_number":179,"context_line":".. note::"},{"line_number":180,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba0121b8_5ead7330","line":177,"in_reply_to":"fa0719c6_36678d4e","updated":"2016-03-28 23:44:33.000000000","message":"Done","commit_id":"41d752c19389d962cb1a93e0576e6dcd4be2e7f4"}]}