docs: Guidance on charm naming best practices could be clearer
Metadata
Current evaluation
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.
Suggested action: keep open
Reason: Maintainer @dwilding committed on 2026-03-09 to tackle the improvements as part of roadmap work, and PR #2748 (commit 0389aeb4) already improved the naming docs with links to detailed guidance. However, the issue also raised a secondary concern about `charmcraft init` defaulting to the directory name (e.g. `foo-operator`) which contradicts best practices — this behavioral aspect may still need addressing, so the issue should remain open until that is resolved or explicitly dismissed.
Impact:
35
Quick Win:
29.75
Staleness:
35
Complexity:
15
Confidence:
75
Support Request:
30
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 |
|---|---|---|---|---|
| qwen/qwen3.8-27b |
Impact:
35
Quick Win:
29.75
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. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
20
Complexity:
25
Confidence:
90
Support Request:
5
|
keep open | Clarify charm versus repository naming conventions in docs and address UX mismatch where charmcraft init defaults to the repo name. Under discussion; a contributor volunteered to implement improvements as part of related roadmap work. |
Update history
No update history recorded yet.
Related work
-
Likely Fixed By:
charmcraft#2748
(confidence 80%)
Commit 0389aeb4 'docs: improve charm naming docs, with links to detailed guidance' directly addresses the documentation clarity concern raised in this issue, adding explicit links to Ops guidance on charm and repository naming.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2748 docs: improve charm naming docs, with links to detailed guidance | charmcraft | merged | Merged documentation updates improving charm naming guidance. Changes remove outdated best practice notes, add value descriptions, link to detailed Ops documentation, and clarify the init command workflow. Approved and merged to resolve issue #2582. |