docs: Guidance on charm naming best practices could be clearer

[YanisaHS]

Check existing issues

• I've verified that this request isn't described by any existing issues.

Request

Relevant links:

1. https://documentation.ubuntu.com/charmcraft/latest/reference/files/charmcraft-yaml-file/#charmcraft-yaml-key-name
2. https://documentation.ubuntu.com/charmcraft/latest/howto/manage-charms/#initialise-a-charm
3. https://documentation.ubuntu.com/charmcraft/latest/howto/manage-charms/#specify-a-name

Just my opinion, but it's easy to look at these pages and see them as unclear and even having conflicting information at first pass

A "quick fix" could be in the "best practices" section on the charmcraft.yaml doc could change to something like:

"Don’t add an operator or charm prefix or suffix in your charmcraft.yaml file. For charm repository naming conventions, see Initialise a charm."

(although I'm far from a charm expert - so keep that perspective in mind :))

But in general, it might be helpful to have something more explicit about the naming standards for charms - what the charm itself should be named, and what the git repository should be named, what shows up in Charmhub, etc.

The experience I had which led me to opening this issue was that I wanted to find the naming conventions for a new charm repository in GitHub, so I Googled something like "charmcraft docs new charm name standards" and got doc 1, which points to doc 2, which points to doc 3, which points back to doc 1. I cycled a bit through them before realizing the charm name and charm repository name are explicitly supposed to be different

Document location

https://documentation.ubuntu.com/charmcraft/latest/reference/files/charmcraft-yaml-file/#charmcraft-yaml-key-name

[tonyandrewmeyer]

FYI, it's unfortunate your web search didn't point you to the appropriate how-to guide, which tells you how to name the repository (which is somewhat outside the scope of charmcraft, really), and gives you a clear link to information about naming the charm itself. I assume that's because you put "charmcraft" in the search rather than "charming" or "charm" (although none of those gives me the ops docs, maybe our SEO is munted because we've moved the docs around so much?).

The best practice already says:

Don’t add an operator or charm prefix or suffix. For naming a repository, see Initialise a charm.

Although maybe we could also link to the write-and-structure-charm-code how-to from here. Maybe the charmcraft how-to manage best practice could also link back to there as well (we're a bit one-way at the moment, which falls off a bit when people start in charmcraft for some reason).

I don't see any conflicting information - @YanisaHS do you have a specific example of that? If there is conflicting instructions, I'd definitely like to fix that ASAP.

For what it's worth, I asked AI "what's the naming guidance for juju charms? both for the charm name and the repository" and got:

Claude's answer

Charm Name

The name field in charmcraft.yaml determines the .charm filename, the Charmhub URL, and the juju deploy <name> command.

Format rules:

• Lowercase ASCII letters (a-z), numbers (0-9), and hyphens (-) only (slug format)
• Follow the pattern: <workload-name>[<function>][-k8s]
  • Example: argo-server-k8s

Do:

• Use the -k8s suffix for charms that run on Kubernetes, unless the charm has no workload or you're certain a machine version will never exist
• Use the full workload name

Don't:

• Include an organization or publisher name
• Add an operator or charm prefix/suffix to the charm name itself

The "principle of least surprise" applies: a charm bearing a well-known name (e.g., postgresql) should provide the best/definitive operator
for that workload. If you're unsure you meet that bar, use a qualified name like yourname-charmname.

Repository Name

• Use the -operator suffix: <charm-name>-operator (e.g., mysql-operator, argo-server-k8s-operator)
• Prefer suffix over prefix (don't do operator-mysql)
• The -operator suffix aligns with the broader Juju ecosystem naming (Charmed Operator Framework, Charmed Operator SDK)
• Only use plural form if the repo actually contains multiple charm implementations
• Many older repos use -charm as the suffix; -operator is the current recommendation

cc @dwilding

[dwilding]

I have roadmap work that's related to this, so would be happy to tackle the improvements.

One other confusion/complication: If I create my repo called foo-operator, then run charmcraft init, the name in charmcraft.yaml is foo-operator because that's what the parent directory is called. IOW, the happy path doesn't follow our best practices.