openstack/openstack-helm
Code Issues Proposed changes

Cleanup specs folder

Browse Source 
Specs are not ordered currently, and every rst file inside the
specs folder is included in the TOC tree, but manually.

This is a problem as:
- the current readability of the specs was reduced due to inclusion
  of non-specs files
- the process of writing a spec was more tedious, due to the
  update of the specs/index.rst.

This fixes it by removing the extra files included by mistake in
the middle of the specs (the template for spec writing, and
the specs purpose/process), and automatically load all the
remaining files using a glob.

The content of the files removed is not lost: The template was
simply renamed COPYME to clearly state a spec writer should
copy the file (and will understand it needs to be named .rst)
with the other files present. The specs process/purpose is
now part of the main page of specs, which therefore doesn't need
extra including.

Change-Id: I8aa15c8a8f2d8b3ffb764c3fb2411eb27477d0b6
This commit is contained in:
Jean-Philippe Evrard 2019-03-04 14:38:05 +01:00
parent 66ba0be81c
commit 630ca71e3c
3 changed files with 35 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
doc/source/specs/template.rst → doc/source/specs/COPYME
View File

49
doc/source/specs/index.rst
View File

@ -1,19 +1,40 @@
Specifications
==============
Project Specifications
======================
Contents:
Specifications in this repository represent a consensus on the topics covered
within. They should be considered a mandate on the path forward with regards
to the content on which they are drafted.
Here is a list of the current specs:
.. toctree::
:maxdepth: 1
:glob:
developer-environment.rst
osh-lma-stack.rst
specifications.rst
template.rst
neutron-multiple-sdns.rst
nginx-sidecar.rst
support-linux-bridge-on-neutron.rst
fluentbit-fluentd-architecture.rst
osh-1.0-requirements.rst
values-ordering.rst
tenant-ceph.rst
*
Specifications Purpose
----------------------
A specification should precede any broad-reaching technical changes or proposals
to OpenStack-Helm. Examples of changes requiring a specification include: a
standard format to the values.yaml files, multiple backend support for neutron,
and the approach for logging and monitoring in OpenStack-Helm. Some additional
features will not need an accompanying specification, but may be tied back to an
existing specification. An example of this would be introducing a service in
OpenStack-Helm that could be included under the scope of a specification already
drafted and approved.
Specifications Process
----------------------
Before drafting a specification, a blueprint should be filed in Storyboard_
along with any dependencies the blueprint requires. Once the blueprint has been
registered, submit the specification as a patch set to the specs/ directory
using the supplied template.
More information about the blueprint + specification lifecycle can be found
here_.
.. _Storyboard: https://storyboard.openstack.org/#!/project_group/64
.. _here: https://wiki.openstack.org/wiki/Blueprints#Blueprints_and_Specs

33
doc/source/specs/specifications.rst
View File

@ -1,33 +0,0 @@
=====================
Project Specfications
=====================
Specifications in this repository represent a consensus on the topics covered
within. They should be considered a mandate on the path forward with regards
to the content on which they are drafted.
Purpose
-------
A specification should precede any broad-reaching technical changes or proposals
to OpenStack-Helm. Examples of changes requiring a specification include: a
standard format to the values.yaml files, multiple backend support for neutron,
and the approach for logging and monitoring in OpenStack-Helm. Some additional
features will not need an accompanying specification, but may be tied back to an
existing specification. An example of this would be introducing a service in
OpenStack-Helm that could be included under the scope of a specification already
drafted and approved.
Process
-------
Before drafting a specification, a blueprint should be filed in Storyboard_
along with any dependencies the blueprint requires. Once the blueprint has been
registered, submit the specification as a patch set to the specs/ directory
using the supplied template.
More information about the blueprint + specification lifecycle can be found
here_.
.. _Storyboard: https://storyboard.openstack.org/#!/project_group/64
.. _here: https://wiki.openstack.org/wiki/Blueprints#Blueprints_and_Specs