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. Please see the Writing 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…”). Ask 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 (e.g. https://charmhub.io/keystone). 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 master branch on opendev.org (e.g. https://opendev.org/openstack/charm-keystone/src/branch/master/README.md).

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. Examples:

For tech-preview:

> **Note**: The ceph-dashboard charm is currently in tech-preview.

For requirements/limitations:

> **Note**: The placement charm is supported starting with the train/stable
> channel.

Section Configuration

Always include this section.

This is boilerplate text:

# 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, 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:

# 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:

# 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 alert the team if your charm is not conceptually covered in the specified resource:

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:

# Policy overrides

This charm supports the policy overrides feature.

Policy overrides allow 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:

# 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:

# 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:

# Bugs

Please report bugs on [Launchpad][<charm>-filebug].

Fill in the placeholder for the charm’s bug-filing link.