docs: Guidance on charm naming best practices could be clearer
Metadata
Current evaluation
Docs request for clearer charm naming guidance (charm name vs Git repo name) across charmcraft.yaml reference and init how-to. Resolved by merged PR #2748 / commit 0389aeb4, which now links to Ops naming docs.
Suggested action: close resolved
Reason: Merged PR #2748 (commit 0389aeb4, "docs: improve charm naming docs, with links to detailed guidance") resolved this; its PR summary explicitly states it resolves #2582. Verified in the current tree: docs/reference/files/charmcraft-yaml-file.rst:620 now documents the `name` value as ``<workload name>[<function>][-k8s]`` and defers to ``Ops | Decide your charm's name``, while docs/howto/manage-charms.rst:16-22 now states "The Ops guidance also explains how to name your charm's Git repository" — the exact cross-doc confusion the reporter hit. The old "Don't add an operator or charm prefix or suffix" best-practice block the maintainer quoted no longer exists in the repo.
Evaluated by: mr-cal-bot
Impact:
25
Quick Win:
20
Complexity:
8
Confidence:
95
Actionability:
88
Issue body
### Check existing issues
- [x] 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
1. https://documentation.ubuntu.com/charmcraft/latest/howto/manage-charms/#initialise-a-charm
1. 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](https://documentation.ubuntu.com/charmcraft/latest/howto/manage-charms/#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
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha |
Impact:
25
Quick Win:
20
Complexity:
8
Confidence:
95
Actionability:
88
|
close resolved | Docs request for clearer charm naming guidance (charm name vs Git repo name) across charmcraft.yaml reference and init how-to. Resolved by merged PR #2748 / commit 0389aeb4, which now links to Ops naming docs. | |
| stealth/space-bunny-alpha |
Impact:
25
Quick Win:
20
Complexity:
12
Confidence:
95
Actionability:
90
|
close resolved | Docs request for clearer charm naming guidance (charm name vs. repo name, init/name mismatch) across three circular cross-linked pages. Resolved in merged PR #2748 (commit 0389aeb4), which added Ops naming links and init name guidance. | |
| stealth/space-bunny-alpha |
Impact:
22
Quick Win:
17
Complexity:
12
Confidence:
92
Actionability:
88
|
close resolved | Docs request for clearer charm naming guidance across three pages. Maintainers triaged it; dwilding took it via roadmap work and merged PR #2748 (commit 0389aeb4), which rewrote the naming sections and added cross-links. | |
| qwen/qwen3.6-35b-a3b |
Impact:
30
Quick Win:
19
Complexity:
20
Confidence:
90
Actionability:
80
|
keep open | Documentation improvement request for clearer charm naming guidelines. Maintainers have acknowledged the issue and assigned it to roadmap work. | |
| qwen/qwen3.8-27b |
Impact:
35
Quick Win:
30
Staleness:
35
Complexity:
15
Confidence:
75
Support Request:
30
|
keep open | Docs request to clarify charm vs repository naming conventions in charmcraft docs; maintainer acknowledged and PR #2748 improved naming docs with links to detailed guidance, addressing the core confusion. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
55
Complexity:
15
Confidence:
85
Support Request:
5
|
keep open | Documentation request to clarify charm naming conventions and resolve circular references. Acknowledged by maintainers with related roadmap work, but currently unlabelled and inactive for over four months. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
65
Complexity:
20
Confidence:
85
Support Request:
10
|
keep open | Documentation on charm naming conventions is confusing due to circular links and unclear best practices. A contributor offered to improve it, but activity has stalled for four months. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
45
Complexity:
15
Confidence:
85
Support Request:
10
|
keep open | Documentation request to clarify charm naming conventions and reconcile best practices with the charmcraft init workflow. A contributor has volunteered to implement improvements. |
Update history
No update history recorded yet.
Related work
-
Likely Fixed By:
charmcraft#2748
(confidence 97%)
Merged PR titled 'docs: improve charm naming docs, with links to detailed guidance'; commit 0389aeb4 touches docs/howto/manage-charms.rst, and its summary says it resolves #2582.
-
Related To:
charmcraft#734
(confidence 45%)
Adjacent naming-clarity work on the 'not a valid charm name' validation error (PR #711); surfaced as a semantic match, not an explicit cross-reference.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2748 docs: improve charm naming docs, with links to detailed guidance | charmcraft | merged | Docs PR #2748 merged (commit 0389aeb4): rewrote charm naming guidance in the charmcraft.yaml reference and manage-charms how-to, replacing inline best-practice notes with links to the Ops docs. Fixes #2582; relied on canonical/operator#2610. | |
| #2844 docs: add how-to guide for packing charms in monorepos | charmcraft | merged | Merged into main. PR #2844 added docs/howto/pack-a-charm-in-a-monorepo.rst, linked it from docs/howto/index.rst, updated Charmcraft 4.5 release notes, and added 'monorepos?' to the wordlist, fixing CHARMCRAFT-721. | |
| #471 config: add charm part to documentation (CRAFT-356) | charmcraft | merged | Merged PR #471 via commit e0b18661, documenting the charm part in the configuration schema for CRAFT-356. |