openstack
/
charm-guide
Code Issues Proposed changes

Add README template 

Import and convert the charm README template from an
internal document, and improve upon it.

A few significant changes is the removal of a list of
"important/common" configuration options and the removal
of a definitive list of actions:

* options - It is felt that a list is too subjective. It
  is also redundant: the options are also available via
  config.yaml and/or viewed in the Charmhub. We should
  instead put more effort into ensuring the options are
  properly described when developing the charm. As a
  mitigating factor towards a loss of value, many
  "important/common" options will naturally surface in
  the Deployment section. Showcasing the use of various
  options can also be the subject of future tutorials.

* actions - Similar to options, the actions are already
  listed elsewhere (actions.yaml). It is also onerous to
  maintain an up-to-date list from the documentation
  standpoint.

Depends-On: Iae5cdfad42b6775a053a5de8d8e73def318d277d
Depends-On: Ib3d02d716bdad0bce52ed72b7528ad1ccb301bb3
Depends-On: I433d0b8d7d865c0cbc9647eb30838a6db87ce9c8
Change-Id: Ic8c31d88c5770e306bba2b28d8a88634f852ad8c
This commit is contained in:
Peter Matulis 2022-02-08 23:27:48 -05:00
parent 4828158856
commit efb8decbd6
3 changed files with 307 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

303
doc/source/community/charm-readme-template.rst Normal file
View File

@ -0,0 +1,303 @@
:orphan:
=====================
Charm README template
=====================
Overview
--------
The purpose of the README template is to help in providing consistency across
the collection of charms. It also helps to reduce the amount of effort needed
during the commit review phase (for both author and reviewer) when new charms
are developed.
The writing format is Markdown, which can be validated using a `Markdown
viewer`_. The README also gets rendered on the charm's landing page in the
`Charmhub`_ (with the `Mistune`_ Python parser).
Please see the :doc:`Writing style guide <doc-style-guide>` for the OpenStack
Charms project.
General approach
----------------
The README should encapsulate the purpose of a charm and its basic usage. It
should be streamlined yet informative enough to allow a user to deploy the
charm and to benefit from the charm's most common use case.
Any surplus documentation should be submitted to the `OpenStack Charm Guide`_
and then linked to (i.e. "For more information see..."). :doc:`Ask <contact>`
for advice if you're unsure about how to submit this sort of documentation.
When referencing another charm in a general way, link to the charm's Charmhub
entry. When referring specifically to information in another charm's README,
link directly to the file, or to a header in the file, by way of the charm's
repository on `opendev.org`_.
Structure
---------
The file's structure is given below in terms of section headers. The sections
in bold are required. Any other sections must be included if they apply to the
charm.
**# Overview**
**# Configuration**
**# Deployment**
# Actions
# <charm feature X>
# <charm feature Y>
# <charm feature Z>
# High availability
# Policy overrides
# Deferred service events
**# Documentation**
**# Bugs**
Section **Overview**
~~~~~~~~~~~~~~~~~~~~
Always include this section.
Typically the charm is associated with an upstream project - often, but not
always, an OpenStack project. Very briefly give the purpose of that project's
service.
Directly state what the charm does and in what context it is deployed. For
instance, if it works in tandem with another charm then state that.
Use an admonishment to indicate whether the charm is in a tech-preview state
and/or whether the charm has requirements/limitations in terms of an OpenStack
release or an Ubuntu series.
Section **Configuration**
~~~~~~~~~~~~~~~~~~~~~~~~~
Always include this section.
This is boilerplate text:
.. code-block:: none
# Configuration
To display all configuration option information run `juju config
<application>`. If the application is not deployed then see the charm's
[Configure tab][<charm>-configure] in the Charmhub. Finally, the [Juju
documentation][juju-docs-config-apps] provides general guidance on
configuring applications.
Fill in the placeholder for the charm's Charmhub entry.
.. important::
There is no need to call out specific configuration options in the README.
However, make sure that the ``config.yaml`` file explains each option well.
Section **Deployment**
~~~~~~~~~~~~~~~~~~~~~~
Always include this section.
The user should be able to deploy the charm for the most common use cases by
following the instructions given in this section.
Although an application typically never exists in isolation, strive to avoid
duplicating deployment instructions for other charms. Instead, call out those
applications that the new application requires a relation to. Then provide all
the commands necessary to make the associated model "go green" (no unsatisfied
relations or configurations). The `nova-cloud-controller`_ README is a good
example.
Give any general requirements. For example, whether a pre-existing Ceph cluster
is assumed.
As exceptions to the above rule, subordinate charms can include the deployment
steps of a principal charm (e.g. `cinder-ceph`_ and cinder). Also, some charms
are so closely related that it makes sense for each to show both (e.g.
`swift-proxy`_ and `swift-storage`_, or `ceph-mon`_ and `ceph-osd`_),
especially if the space required is minimal. Use common sense.
Section **Actions**
~~~~~~~~~~~~~~~~~~~
Include this section if it applies to the charm.
This is boilerplate text:
.. code-block:: none
# Actions
This charm supports actions.
[Actions][juju-docs-actions] allow specific operations to be performed on a
per-unit basis. To display actions and their descriptions run `juju actions
--schema <application>`. If the application is not deployed then see the
charm's [Actions tab][<charm>-actions] in the Charmhub.
Fill in the placeholder for the charm's Charmhub entry.
.. important::
There is no need to call out specific actions in the README. However, make
sure that the ``actions.yaml`` file explains each action well.
Section **<charm feature>**
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Include a section for each noteworthy feature the charm may have.
Section **High availability**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Include this section if it applies to the charm.
Most services support some form of high availability. When one does, it is
either natively HA or non-natively HA (requires HAcluster). Include text for a
charm's HA implementation.
This is boilerplate text for a non-native HA service:
.. code-block:: none
# High availability
This charm supports high availability via HAcluster.
When more than one unit is deployed with the [hacluster][hacluster-charm]
application the charm will bring up an HA active/active cluster.
See the `rabbitmq-server`_ charm for an example of a native HA service.
Regardless of the nature of the charm's HA implementation, the section should
always include this boilerplate text, and :doc:`Alert <contact>` the team if
your charm is not conceptually covered in the specified resource:
.. code-block:: none
See [Infrastructure high availability][cg-ha-apps] for more information.
Section **Policy overrides**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Include this section if it applies to the charm.
This is boilerplate text:
.. code-block:: none
# Policy overrides
This charm supports the policy overrides feature.
Policy overrides is a feature that allows an operator to override the
default policy of an OpenStack service.
See [Policy overrides][cg-policy-overrides] for more information on this
feature.
Section **Deferred service events**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Include this section if it applies to the charm.
This is boilerplate text:
.. code-block:: none
# Deferred service events
This charm supports the deferred service events feature.
Operational or maintenance procedures applied to a cloud often lead to the
restarting of various OpenStack services and/or the calling of certain charm
hooks. Although normal, such events can be undesirable due to the service
interruptions they can cause.
The deferred service events feature provides the operator the choice of
preventing these service restarts and hook calls from occurring, which can
then be resolved at a more opportune time.
See [Deferred service events][cg-deferred-service-events] for more
information on this feature.
Section **Documentation**
~~~~~~~~~~~~~~~~~~~~~~~~~
Always include this section.
This is boilerplate text:
.. code-block:: none
# Documentation
The OpenStack Charms project maintains two documentation guides:                                                                                             
* [OpenStack Charm Guide][cg]: the primary source of information for
OpenStack charms
* [OpenStack Charms Deployment Guide][cdg]: a step-by-step guide for
deploying OpenStack with charms
Section **Bugs**
~~~~~~~~~~~~~~~~
Always include this section.
This is boilerplate text:
.. code-block:: none
# Bugs
Please report bugs on [Launchpad][<charm>-filebug].
Fill in the placeholder for the charm's bug-filing link.
Links
-----
Put all links at the bottom. For example:
.. code-block:: none
<!-- LINKS -->
[cg]: https://docs.openstack.org/charm-guide
[cg-deferred-service-events]: https://docs.openstack.org/charm-guide/latest/admin/deferred-events.html
[cg-policy-overrides]: https://docs.openstack.org/charm-guide/latest/admin/policy-overrides.html
[cg-ha-apps]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/ha.html#ha-applications
[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
[hacluster-charm]: https://charmhub.io/hacluster
[juju-docs-actions]: https://juju.is/docs/working-with-actions
[juju-docs-config-apps]: https://juju.is/docs/configuring-applications
[<charm>-actions]: https://charmhub.io/<charm>/actions
[<charm>-configure]: https://charmhub.io/<charm>/configure
[<charm>-filebug]: https://bugs.launchpad.net/charm-<charm>/+filebug
.. LINKS
.. _Charmhub: https://charmhub.io
.. _opendev.org: https://opendev.org/explore/repos?tab=&sort=recentupdate&q=charm-
.. _Markdown viewer: https://jbt.github.io/markdown-editor
.. _Mistune: https://mistune.readthedocs.io/en/latest
.. _OpenStack Charm Guide: https://docs.openstack.org/charm-guide
.. _rabbitmq-server: https://opendev.org/openstack/charm-rabbitmq-server/src/branch/master/README.md#high-availability
.. _swift-proxy: https://opendev.org/openstack/charm-swift-proxy/src/branch/master/README.md
.. _swift-storage: https://opendev.org/openstack/charm-swift-storage/src/branch/master/README.md
.. _nova-cloud-controller: https://opendev.org/openstack/charm-nova-cloud-controller/src/branch/master/README.md
.. _cinder-ceph: https://opendev.org/openstack/charm-cinder-ceph/src/branch/master/README.md
.. _ceph-mon: https://opendev.org/openstack/charm-ceph-mon/src/branch/master/README.md
.. _ceph-osd: https://opendev.org/openstack/charm-ceph-osd/src/branch/master/README.md

9
doc/source/community/doc-style-guide.rst
View File

@ -15,12 +15,9 @@ project documentation:
Both the above guides are published using the `Sphinx`_ documentation
generator. As such, enhanced `reStructuredText`_ (RST) formatting is used.
The charm README files are formatted in Markdown (MD).
.. REPLACE THE ABOVE LINE WITH THIS ONCE THE CITED DOCUMENT IS MERGED
The charm README files are formatted in Markdown. The :doc:`Charm README
template <charm-readme-template>` provides guidance on how to produce a
README file.
The charm README files are formatted in Markdown. The :doc:`Charm README
template <charm-readme-template>` provides guidance on how to produce a README
file.
Other resources
~~~~~~~~~~~~~~~

1
doc/source/community/index.rst
View File

@ -11,6 +11,7 @@ interested in hearing from you!
contact
software-contrib
charm-readme-template
doc-contrib
doc-style-guide
bug-submitting