openstack/glance
Code Issues Proposed changes

Add guideline to refresh config files shipped with source

Browse Source 
This commit adds documentation to help authors identify the steps they
need to take while updating the config files and thereafter.

This documentation is being added as per question asked on change
I534a0dc2d9f82ab70517cde12bfd40d4f5ae69e2

There is some discussion as to when we will be getting rid of the config
file from the tree on the change
Iee695870aefc9cb6142dbc7400672b335588fcc9

Until we do get rid of the config files from source, we need to document
this process for any further updates to configs.

Change-Id: I2e3d43e43e00cd2a13b5a0fb794ac6e6d2e24dc2
This commit is contained in:
Nikhil Komawar 2016-08-12 12:06:20 -04:00
parent d0f4316752
commit 7df813bba4
1 changed files with 61 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
doc/source/contributing/refreshing-configs.rst Normal file
View File

@ -0,0 +1,61 @@
..
Copyright 2016-present OpenStack Foundation
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Guideline On Refreshing Configuration Files Under etc/
======================================================
During a release cycle many configuration options are changed or updated. The
sample configuration files provided in tree (under ``etc/*``) need to be
updated using the autogeneration tool as these files are being used in
different places. Some examples are devstack gates, downstream packagers
shipping with the same (or using defaults from these files), etc. Hence, before
we cut a release we need to refresh the configuration files shipped with tree
to match the changes done in the source code during the release cycle.
In an ideal world, every review that proposes an addition, removal or update to
a configuration option(s) should use the tox tool to refresh only the
configuration options(s) that were changed. However, many of the configuration
options like those coming from oslo.messaging, oslo_middleware, etc. may have
changed in the meantime. So, whenever someone uses the tool to autogenerate the
configuration files based on the options in tree, there are more changes than
those made just by the author.
We do not recommend the authors to manually edit the autogenerated files so, a
reasonable tradeoff is for the authors to include **only those files** that are
affected by their change(s).
$ tox -e genconfig
When To Refresh The Sample Configuration Files
==============================================
* Every review that proposes an addition, removal or update to a configuration
option(s) should use the tox tool to refresh only the configuration option(s)
they have changed.
* Ideally reviewers should request updates to sample configuration files for
every change that attempts to add/delete/modify a configuration option(s) in
the code.
* In some situations however, there may be a bunch of similar changes that are
affecting the configuration files. In this case, in order to make the
developers' and reviewers' effort easier, we recommend an update to the
configuration files in bulk right after all the update changes have been
made/merged.
**IMPORTANT NOTE**: All sample configuration files mush be updated before the
milestone-3 (or the final release) of the project.