Merge "Add config-ref-common-options.rst"

specs/mitaka/config-ref-common-options.rst

@@ -0,0 +1,91 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+=========================================
+Config Reference: document common options
+=========================================
+
+https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-common-sections
+
+Problem description
+===================
+
+In the configuration reference, configuration options such as database,
+AMQP, keystone middleware are poorly documented, or worse, documented
+differently in multiple places.
+
+This might be confusing for the reader, and adds maintenance burden.
+
+Proposed change
+===============
+
+Common libraries define several configuration options, used by all the
+OpenStack projects. Instead of documenting these options for each project,
+we could have a specific chapter documenting the configuration options for
+common libraries, and refer to this chapter in the projects chapters.
+
+At the moment these options are poorly documented, so this change would also be
+a chance to add missing information, or at least provide a better structure to
+do so in the future.
+
+This spec only impacts the configuration reference.
+
+
+Alternatives
+------------
+
+* Document everything in all the projects chapters, leading to a lot of
+  duplication
+
+Implementation
+==============
+
+
+Assignee(s)
+-----------
+
+Primary assignee: gpocentek
+
+
+Work Items
+----------
+
+* Generate options tables using ``autohelp`` for the common libraries. The
+  options would not be removed from the projects tables, to keep providing a
+  complete set of options for each project.
+
+* Add a new ``Common configuration options`` chapter to the configuration
+  reference, documenting configuration options available in ``oslo`` and
+  ``keystonemiddleware`` libraries. Documented libraries include
+  (non-exhaustive list):
+
+  * ``oslo.concurrency``
+  * ``oslo.db``
+  * ``oslo.log``
+  * ``oslo.messaging``
+  * ``keystonemiddleware.auth_token``
+
+* Remove documentation for these options in the projects chapters, if necessary
+  (AMQP with ``oslo.messaging`` is sometimes documented).
+
+* In each component chapter, add references to the common options sections.
+
+
+Dependencies
+============
+
+None
+
+Testing
+=======
+
+* Validate the existence of documented options using the tables generated with
+  ``autohelp``.
+
+References
+==========
+
+None