openstack
/
charm-guide
Code Issues Proposed changes

Add feature-specification section for charm-spec guidance 

Change-Id: I7b5096b371b85ea3dbd5748aa36676ebbd1bdad4
This commit is contained in:
Ryan Beisner 2019-04-24 12:13:37 -05:00
parent 8c2d07c968
commit 8fd845a7c7
No known key found for this signature in database
GPG Key ID: 952BACDC1C1A05FB
4 changed files with 53 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/creating-charms.rst
View File

@ -8,6 +8,7 @@ Create A Charm
.. toctree::
:maxdepth: 1
feature-specification
charm-anatomy
new-sdn-charm
new-api-charm

49
doc/source/feature-specification.rst Normal file
View File

@ -0,0 +1,49 @@
.. _feature_specification:
=====================
Feature Specification
=====================
The OpenStack Charms project uses specifications to identify and define the
implementation details of new major features. Features that require new charm
config options, new charm interfaces, and new charm relations should have an
agreed spec prior to proposing code for review. Likewise, a spec should be
landed before work begins on wholly new charms.
The following resources provide reference to existing accepted specs, the
source code repository, recent activity on that repository, and a template
to use as a base for new specs.
* `published charm specs`_
* `charm-specs source repository`_
* `charm-specs history`_
* `charm-specs template`_
Recommended work flow for introducing a new feature specification:
1. `Have a conversation <find-us.html>`_ with core charmers to avoid overlapping or
duplicate work.
2. Discuss the high-level design with core charmers to arrive at an
optimal approach (before writing code).
3. Compose the specification with the aim to remove all doubt as to "what it is"
and "what it isn't." This should be based on the `charm-specs template`_
and posted as a Gerrit review.
4. Include one or more specific user stories or use cases which support the
pratical application of the feature specification.
5. Support the proposal by including relevant bug references in the
specification.
6. Circulate the proposal on the `mailing list <mailing-list.html>`_ to ensure
wider visibility.
7. Engage in `further discussion <find-us.html>`_ surrounding the spec proposal
and the mailing list post so that it can be reviewed and landed.
.. _published charm specs: https://specs.openstack.org/openstack/charm-specs/
.. _charm-specs source repository: https://opendev.org/openstack/charm-specs
.. _charm-specs history: https://review.opendev.org/#/q/project:openstack/charm-specs+status:merged
.. _charm-specs template: https://opendev.org/openstack/charm-specs/src/branch/master/specs/template.rst

1
doc/source/how-to-contribute.rst
View File

@ -14,6 +14,7 @@ to the OpenStack Charms.
:titlesonly:
:maxdepth: 1
feature-specification
coding-guidelines
testing
making-a-change

4
doc/source/mailing-list.rst
View File

@ -1,4 +1,4 @@
.. _mailing_list: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
.. _mailing list: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
============
Mailing list
@ -8,5 +8,5 @@ Please use the mailing list when possible as it makes the information
discussed more readily available so that others who have the same
question can search for (and find) those answers.
All communication regarding charms should contain **[charms]** in the subject line when sending to the `mailing_list`_.
All communication regarding charms should contain **[charms]** in the subject line when sending to the `mailing list`_.