docs: improve charm naming docs, with links to detailed guidance
Metadata
Current evaluation
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.
Suggested action: —
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 |
|---|---|---|---|---|
| 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. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
0
Complexity:
5
Confidence:
90
|
needs review | Updates charm naming documentation with clearer value blocks, updated examples, and links to Ops docs guidance. Currently awaiting maintainer review. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2253 docs: add charm docs exemplars links | charmcraft | merged | Merged after approval and CI checks. Added links to charm documentation exemplars to improve guidance. Updated one file with 34 additions and 5 deletions as part of a documentation standardization initiative. | |
| #2582 docs: Guidance on charm naming best practices could be clearer | charmcraft | 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. | |
| #2240 docs: update charm definition in security doc | charmcraft | merged | Merged documentation update revising the charm definition in the security guide. Incorporated feedback from a prior discussion, approved by two reviewers, passed CI checks, and successfully merged with minimal line changes. | |
| #2262 docs: hotfix for links syntax for charm docs examples | charmcraft | merged | Merged following approval by three reviewers. The change corrected link syntax in the Manage charms documentation and added a Charmhub Discourse link. All required CI checks passed before integration. | |
| #242 Add init documentation for a gentle introduction to the charm operator | charmcraft | merged | Merged PR adding starter docs to charmcraft init. Reviewer requested moving content to a Charmhub discourse wiki and linking it. Contributor adapted the change, and the PR was merged with the external link integrated. | |
| #2601 docs: Redo in-page links for: Mange charm revisions, Manage the current charmhub user, and Manage tracks | charmcraft | merged | Merged documentation update fixing in-page links and adding introductory sentences to three how-to guides. Reviewer feedback was implemented before merge, completing a series for the Open Documentation Academy. | |
| #2172 docs: update release step with resource details | charmcraft | merged | Merged documentation update adding resource attachment details to the charm release example, resolving issue #2171. Standardizes charm names across the Publish section. Approved by two reviewers, passed CI, and applied with a minimal eight-line change. | |
| #471 config: add charm part to documentation (CRAFT-356) | charmcraft | merged | Merged changes adding charm configuration documentation to the configuration schema. Approved by two reviewers with zero unresolved comments. Updated two files with 15 additions and one deletion. Resolves CRAFT-356. | |
| #2734 docs: improve versioning logic | charmcraft | merged | Merged after approval and passing CI checks. Updated documentation versioning logic to label the latest release as Charmcraft dev documentation. Integrated with minimal changes ahead of the 4.3 tag. | |
| #2659 docs: remove charmhub config | charmcraft | merged | Merged into main. Documentation references to charmhub were removed while keeping the underlying code intact for backward compatibility. Closes issue 1787 after reviewer approval and CI validation. |