Charm Store Policy¶

This document serves to record the policies around charms included in the charm store, and the management of said charm collection.

Content¶

All charms ...

must follow the spirit of the Ubuntu Values.
must serve a useful purpose and have well defined behavior.
must also be valid for the charm format defined in juju's documentation.
must verify that any software installed or utilized is verified as coming from the intended source. Any software installed from the Ubuntu archive satisfies this due to the apt sources including cryptographic signing information. See this site for a list of common methods.
must include a full description of what the software does in the metadata.
must provide a means to protect users from known security vulnerabilities in a way consistent with best practices as defined by either Ubuntu policies or upstream documentation. Basically this means there must be instructions on how to apply updates if you use software not from Ubuntu.
must pass "charm proof" with no errors (lines prefixed with E:), remember this step!
must have a maintainer email address in metadata.yaml attached to a team or individual who are responsive to contact regarding the charm.
must include a license. Call the file 'copyright' and make sure all files' licenses are specified clearly. [#]_
must be under a Free license. [#]_
must have hooks that are idempotent1.
must not run any network services using default passwords.
should default to use software that is included in the Ubuntu archive, however we encourage that charm authors have a config options for allowing users to deploy from newer upstream releases, or even right from VCS if it's useful to users.
should not use anything infrastructure-provider specific (i.e. querying EC2 metadata service) symlinks must be self contained within a charm.
should make use of AppArmor <https://juju.ubuntu.com/AppArmor> to increase security

Terminology¶

Please see the official Juju Documentation for a definition of various terms used within this document.

charm store¶

The charm store referred to in this document is the collection of Juju charms hosted at https://launchpad.net/charms.

official charm¶

Any charm that has been accepted into the charm store.

de-facto¶

If any aspect of a charm has been committed and untouched for 30 days in an official charm, that is said to be a de-facto aspect of the charm.

Metadata¶

metadata.yaml¶

name: Name must succinctly communicate what sort of service the charm deploys.
description: description should give a long form description of the service and the way that the charm configures it.
maintainer: all charms must have a maintainer email address. This can be an email list, as long as it is an unmoderated list (subscription required is ok).
requires: despite the name, any interface that the charm can connect to, even one that is not required, can be enumerated here. All requires relationships must function with the same behavior as any existing de-facto implementations of said interface.
provides: All provdes relationships listed must function with the same behavior as any existing de-facto implementations of said interface

revision¶

All changes must increment revision. Groups of changes made all at once can increment it only once, but there are no exceptions as to what types of changes can cause the revision to go up.

config.yaml¶

Any de-facto config options must be kept at least until the next major charm series release. Removed config options should be deprecated first by noting that they are deprecated, and why, in their description. Instructions for converting values must be added to README as well.

README¶

Charms that want to display instructions to users can do so in either plain text by including a file called README. If the author would like to use markdown, the file should be called README.md, and if the author would like to use restructured text, the file should be called README.rst. Only one of these files can be included in the charm.

Interfaces¶

Charms should only implement a new interface when existing interfaces are insufficient to achieve the goal of the charm.
Interfaces that have an official requires/provides in the charm store cannot be changed by adding required fields or removing existing fields. New optional fields can be added at any time.

Series¶

The charm store series denotes the OS release that the charms which are contained within it are intended to run on.

State¶

Each series can be in one of these states:

Experimental - Charms can be added, but are in a state of flux.
Active - The Charm store is actively accepting new charms and changes.
Frozen - Only critical fixes are accepted.
EOL - The OS version is not supported by the vendor, and thus, neither are the charms.

Experimental¶

Experimental series charms should adhere to the charm policy except that interfaces are never made 'de-facto' in an experimental series.

Active¶

When a series is active, all changes are subject to the de-facto rules above.

Frozen¶

The charmers team on launchpad has discretion when a series is frozen as to whether or not a change should be accepted.

EOL¶

No changes will be accepted except those which help users who need to migrate to a supported series.

Process¶

Charm store releases will be moved from Active to Frozen periodically to allow de-facto changes to settle and allow testing of infrastructure. New releases of target OS's will be reflected in the charm store as an experimental series. There can be multiple Active series at one time. Maintainers can choose whether or not to support their charm in all of the Active series, as long as the charm is maintained in at least one Active series.

[1]	Its recommended that all non-trivial works in your charm include a copyright and license header in case they are copied to another charm.

[2]	We recommend GPLv3+. See OSI approved licenses <http://www.opensource.org/licenses/> for other licenses.