Add feature-specification section for charm-spec guidance
Change-Id: I7b5096b371b85ea3dbd5748aa36676ebbd1bdad4
This commit is contained in:
parent
8c2d07c968
commit
8fd845a7c7
|
@ -8,6 +8,7 @@ Create A Charm
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
|
feature-specification
|
||||||
charm-anatomy
|
charm-anatomy
|
||||||
new-sdn-charm
|
new-sdn-charm
|
||||||
new-api-charm
|
new-api-charm
|
||||||
|
|
|
@ -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
|
|
@ -14,6 +14,7 @@ to the OpenStack Charms.
|
||||||
:titlesonly:
|
:titlesonly:
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
|
feature-specification
|
||||||
coding-guidelines
|
coding-guidelines
|
||||||
testing
|
testing
|
||||||
making-a-change
|
making-a-change
|
||||||
|
|
|
@ -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
|
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
|
discussed more readily available so that others who have the same
|
||||||
question can search for (and find) those answers.
|
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`_.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue