docs: improve charm naming docs, with links to detailed guidance
Metadata
Current evaluation
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.
Resolution: closed resolved
Reason: The PR was approved and merged into main as commit 0389aeb4 after review comments from medubelko were addressed. It removes the 'best practice' notes from charmcraft.yaml's name field and the init how-to, adding 'Value' descriptions that link to the detailed Ops naming guidance, thereby resolving issue #2582.
Evaluated by: mr-cal-bot
No scores available.
Issue body
This PR fixes #2582.
I'm updating two docs:
- [charmcraft.yaml file > name](https://documentation.ubuntu.com/charmcraft/latest/reference/files/charmcraft-yaml-file/#name) (**[Preview doc](https://canonical-charmcraft--2748.com.readthedocs.build/2748/reference/files/charmcraft-yaml-file/#name)**) - Removed the best practice note after the example. Added a "Value" block before the example to describe the name format and link to more detailed guidance in the Ops docs. The removed info about `-k8s` suffix and organization/publisher name was added to the Ops docs by [operator#2610](https://github.com/canonical/operator/pull/2610).
- [Manage charms > Initialise a charm](https://documentation.ubuntu.com/charmcraft/latest/howto/manage-charms/#initialise-a-charm) (**[Preview doc](https://canonical-charmcraft--2748.com.readthedocs.build/2748/howto/manage-charms/#initialise-a-charm)**):
- Removed the best practice note about naming a Git repo.
- Added a summary of how charms and repos are typically named, with a link to more detailed guidance in the Ops docs.
- Tidied up the subsequent info about how to use the `init` command. Mainly to clarify that we recommend specifying `--name` (and why). Also updated the example session to use terminal directives in the latest supported way.
---
- [x] I've followed the [contribution guidelines](https://github.com/canonical/charmcraft/blob/main/CONTRIBUTING.md).
- [x] I've signed the [CLA](http://www.ubuntu.com/legal/contributors/).
- [x] I've successfully run `make lint && make test`.
- [x] I've added or updated any relevant documentation.
- [ ] In documents I changed, I [added a meta description](https://canonical-starflow.readthedocs-hosted.com/how-to/add-a-page-meta-description/) if one was missing.
- [ ] I've updated the relevant release notes.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | 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. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged PR #2748, clarifying charm naming and init guidance, linking to detailed Ops docs, and resolving #2582. | |
| qwen/qwen3.6-35b-a3b | — | — | 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. |
Update history
No update history recorded yet.
Related work
-
Likely Fixed By:
canonical/charmcraft#2582
(confidence 97%)
Issue #2582 ('Guidance on charm naming best practices could be clearer') is the docs request this PR states it fixes, and it is recorded as resolved by this PR/commit.
-
Blocked By:
operator#2610
(confidence 80%)
The charmcraft changes delete the inline details on the -k8s suffix and organization/publisher naming because that content was moved into the Ops docs by operator#2610, which the new links target.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2582 docs: Guidance on charm naming best practices could be clearer | charmcraft | open | 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. | |
| #2262 docs: hotfix for links syntax for charm docs examples | charmcraft | merged | Merged PR #2262 as commit 675e5e7e, fixing links in the Manage charms docs and adding a Charmhub Discourse link. | |
| #2253 docs: add charm docs exemplars links | charmcraft | merged | Merged #2253 as commit 982a6c16, adding links to small and large charm documentation exemplars. | |
| #2300 docs: update "manage configurations" | charmcraft | merged | Docs PR #2300 merged as commit dc4bedb1: updated Charmcraft links to operator's renamed "Manage configuration" howto and renamed the section heading to "Manage the app configuration" per maintainer request. | |
| #2128 docs: add anchors and fix a few small things | charmcraft | merged | Docs PR merged as commit e880b4bd: added intersphinx anchors (e.g. _manage-charms, _initialise-a-charm) for Ops/Juju linking, retitled 'Set up Charmcraft' to 'Manage Charmcraft', expanded content, and fixed a rendering error. | |
| #1498 docs: Fix 404 in charmcraft.yaml.j2 | charmcraft | closed | Merged in canonical/charmcraft#1498, correcting a broken charmcraft.yaml.j2 documentation link that returned 404. | |
| #2299 docs: fix formatting issues | charmcraft | merged | Merged docs formatting fixes for local documentation builds in charmcraft#2299 via commit 5ffb80fe; two files changed (+3/-1). | |
| #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. | |
| #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. | |
| #2010 docs: add, refactor, and reformat discourse docs feat. charmcraft | charmcraft | merged | Merged PR #2010 as commit a1a3d4b1, migrating Charmcraft content to RTD-ready docs, reformatting it, and separating Ops-related material. |