Stage 1: Important qualities

Charm maturity > Stage 1: Important qualities

The power of a charm lies in the fact that it packages expert knowledge in a way that is shareable and reusable. But, for this to work as intended, the charm must meet certain quality standards. This document outlines the first round of standards – standards intended to ensure that your charm is ready to be shared with others.

While every charm can be published on Charmhub, only charms that meet this first set of standards will be listed, that is, be visible when a user browses or searches for content on Charmhub.

These standards keep evolving. Revisit this doc to get the latest updates.

Contents:

The charm is reliable

A charm is no good if it does not work reliably as intended. To that end, make sure that your charm has unit testing and integration testing.

Unit testing

Objectives Tips, examples, further reading
The charm has appropriate unit tests. These tests cover all the actions of the charm and are executed as part of a CI/CD pipeline. :link: Get started with charm testing

:link: Charm development best practices - Unit tests

Integration testing

Objectives Tips, examples, further reading
The charm has suitable integration tests. These tests cover installation and basic functionality and are executed automatically as part of a CI/CD pipeline.

The implementation of a basic integration test or a smoke test (“turn on and see if smoke comes out”) is not crucial, but the definition of basic or minimal functionality testing is required.

To make integration tests possible in the ecosystem, charm authors provide the following information:

• Definition of the project’s reference setup, such as substrate version and required settings. Testers need to understand the setup which developers have considered.
• In addition to the reference setup, the test documentation lists anticipated substrates/platforms/setups to show the community opportunities for additional testing.
• Description about the use and expected behaviour of relevant integration points subject to testing, e.g. API, service endpoints, relations.Integration tests should be executed automatically and visible to the community.

 :link: Charm development best practices - Functional tests

Real-world examples for an integration test:
• traefik-route-k8s tests
• prometheus-k8s tests

The charm is collaboration-ready

The power of a charm compounds every time someone else finds it, uses it, and contributes to it. As such, make sure that your charm has a good name and icon, is well documented, and has readable code.

Consistent naming

Objectives Tips, examples, further reading
The charm is named similarly to existing charms, in accordance with the naming guidelines.

The name of the publisher identifies the organisation responsible for publishing the charm.

 :link: Charm naming guidelines

Icon

Objectives Tips, examples, further reading
The charm has an appropriate and recognizable icon that can be displayed on Charmhub or the Juju dashboard as a symbol instead of the charm name. The icon helps users identify the charm both when searching and selecting on Charmhub and when using the charm in models displayed in the juju dashboard.

The workload/application icon is considered for the charm in many cases. If the publisher of the charm and the publisher of the workload/application do not belong to the same legal entity, trademark rules may apply when using existing icons.

:link: How to create an icon for your charm

Documentation

Objectives Tips, examples, further reading
The charm has documentation that covers:

1. how to use the charm

2. how to modify the charm

3. how to contribute to the development

Usage documentation covers configuration, limitations, and deviations in behaviour from the “non-charmed” version of the application.

There is a concise summary field, with a more detailed description field in the charmcraft.yaml.

 For contributions, many OSS projects have adopted the best practice of providing a CONTRIBUTING.md’ file at the project’s root level.

Readable code

Objectives Tips, examples, further reading
The code favours a simple, readable approach. There is sufficient documentation for any integration points with the charm, such as libraries, to aid the forming of relations. PEP 8 for general code style:

PEP 257 for in-code documentation style

:link: Charm development best practices - Code style

The charm is compliant

When publishing charms as open source, on Charmhub or other public places, the published content must comply with copyright and trademarks usage rights.

Objectives Tips, examples, further reading
If trademarks and/or logos are used, their use must comply with the permissions of the trademark holder.

If 3rd party software or content is used in the charm repository, it must be handled as such.

In the detailed view of the charm in Charmhub.io: The “by”- entry should identify the charm’s author, not the application’s author.

 For trademarks:

• Use of trademarks in accordance with the trademark guidelines by the trademark owner.

For third-party content (source, images, texts, etc.):

• Use of the content only according to the licence of the copyright owner.

The charm stays up-to-date

Charms cover applications which need to be updated regularly. In today’s world of vulnerabilities and cyber security threats, efficient ways of updating software are crucial. Therefore, the automated production of charms is essential.

Objectives Tips, examples, further reading
The charm is up-to-date, that is, it has build, test and delivery automation. This automation is important to ensure the project can roll out updates quickly.

For this, you need CI/CD in place, including publishing edge and beta/candidate builds.

CI/CD is important to ensure that the most recent developments are also accessible to the community for testing.

 • CI/CD builds are triggered ideally at a commit to the main line / master of the charm code.

• In the sense of “CD”, the charm is being published to its beta or edge channel on Charmhub

• The charm development best practices provide an introduction about integration tests.

The charm maintainers are reachable

Users must know where to reach out to ask questions or find relevant information.

Contact and URLs

Objectives Tips, examples, further reading
The charm homepage provides links that are important to the user. Interested developers should be able to contact the charming project and directions on where and how to submit questions and issues must be provided. URLs must be provided to enable collaboration and exchange on the charm, ideally as metadata on Charmhub.
A best practice is to have an issue template configured for the issue tracker! (Example see, e.g., alertmanager-k8s issue template)
The homepage should point to the source code repository, providing an entry point to charm development and contributions.
:warning: Further support is coming for the distinct identification of the project homepage, source code repository and issue tracker in charm metadata, and on Charmhub.

Community discussions

Objectives Tips, examples, further reading
A Discourse link or Mattermost channel must be available for discussion, announcements and the exchange of ideas, as well as anything else which would not fit into an issue.

For the application, links to the referring forums can also be provided.

 Discourse is preferred because framework topics and other charms are also discussed there. It is the most popular place for the community of charms. Therefore, technical questions are most likely covered there.

For the forum, get started with an introduction.
Issues can also be discussed in the public chat.

Last updated 6 months ago. Help improve this document in the forum or File an issue .