Charm Naming Guideline

Here we are: guidelines (and requirements) for naming Charms, filling out maintainer lists and naming repositories - it is collected feedback input from various charmers and juju developers!

Naming is important for ensuring an intuitive discovery and handling of Charms - good names can be easily searched for and accessed when working with command line tools.

Contents:

Naming Charms

Of course, there is a large number of existing charms already with all their variants on naming. Please check, if naming of existing Charms can be improved, it will help others to find your Charms. But more importantly, consider the following points for new charming efforts:

Required / Recommended Background Examples
Slug-oriented naming required: ASCII lowercase letters, numbers, and hyphens. Ensure URL-safeness,
finding charms easier.
:stop_sign: node_red
:white_check_mark: node-red
Do not abbreviate application names. Finding charms easier. :stop_sign: matterm
:white_check_mark: mattermost
Do not consider camelcase naming. Think of slugs, also not supported. :stop_sign: NodeRed
:white_check_mark: node-red
No charm or operator suffix It is about Charms
Exception: Bundles need to be distinguished from the Charm.
:stop_sign: ghost-operator
:white_check_mark: ghost
:stop_sign: grafrana-charm
:white_check_mark: grafana
However:
:white_check_mark: discourse
:white_check_mark: discourse-bundle
No organisation as prefix Hard to have it consistently across all charms,
Belongs to metadata.yaml
:stop_sign: apache-kafka
:white_check_mark: kafka
:stop_sign: oracle-mysql
:white_check_mark: mysql
No publisher name as prefix to the charm name. Hard to have it consistently across all charms,
Belongs to metadata.yaml
:stop_sign: mysql-charmers-mysql-server
:white_check_mark: mysql
:stop_sign: charmteam-kafka
:white_check_mark: kafka
Avoid the purpose, use the name of the application instead. Multiple charms for same purpose exist or will come. :stop_sign: general-cache
:white_check_mark: varnish (if the varnish OSS project represents the application)
Do not use non-production identifiers, for public. Not useful for the community of Charmhub users. :stop_sign: jenkins-test
:stop_sign: mysql-draft
:stop_sign: hadoop-internal
:stop_sign: kafka-demo
Single charms: Avoid mix of app name and purpose. Suffixes or prefixes shall be omitted and can be part of summary. :stop_sign: drupal-server
:white_check_mark: drupal
However:
:white_check_mark: kubeflow-dashboard
:white_check_mark: kubeflow-pipeline
:white_check_mark: kubeflow-volumes
Multiple charms: Put the name before the function. Sorting. :stop_sign: pipeline-kubeflow
:white_check_mark: kubeflow-pipeline
Explain short names if used. Three letter acronyms: prone to be confused.
Exception: Use “-k8s” for kubernetes only charms In general, do not use a suffix for platforms. Only for “kubernetes only” charms, use the suffix =-k8s” :white_check_mark: graylog-k8s

Maintainer Contact

Currently, the metadata.yaml supports the maintainer of the Charm being listed :

A list of maintainers in the format "First Last <email>

The naming of the maintainer has three main goals:

  • Identify the right person to contact
  • Visibility (for merits) of the publisher(s) or author(s) of the Charm
  • Transparent responsibility for the published software. However, please note that the maintainer list does not necessarily denote the responsible party (copyright holder) of the published Charm implementation.

The maintainer field in metadata.yaml must be filled out, either with

  1. A maintaining individual contact

  2. Multiple maintaining individual contacts if that applies (preferred),

  3. The maintaining organisation if that applies.

  4. Do not use fantasy / virtual team names as feedback has shown it causes confusion.

Naming Repositories

Charms shall have a publicly accessible (git) repository. Opposed to the charm listing on Charmhub.io, a distinguishing element in the name of a repository helps to identify the right repository with the Charm implementation.

The distinguishing element is the suffix “-operator”, because that aligns also with the names of the other parts in the Juju world, such as the Charmed Operator Framework or the Charmed Operator SDK. So, in summary, we have the following steps:

  1. Name the repository like your charm (see naming rules above)

  2. Add a suffix to it: -operator (because: Charmed Operator SDK)

  3. Prefer suffix over prefix (:stop_sign: operator-mydatabaseserver)

  4. Plural form only if there are in fact multiple charm implementations in the repository, do not mimic an (adverbial) genitive.

It is understood that many repositories already exist with the suffix -charm along to the repositories with -operator. Repository renaming can be hard in some cases. The naming guide defines the preferred naming.

Of course, some organisations have their own naming conventions for their repositories which cannot be easily overruled.

Final Remarks

There are more considerations, let’s discuss them on discourse!


Last updated 6 days ago.