docs: options for links in charmcraft unclear
Metadata
Current evaluation
Docs gap: charmcraft.yaml reference doesn't list which sub-keys are allowed under `links:`; reporter's `upstream` key was rejected. Maintainer confirmed valid values live in the Links model; docs redo in progress.
Suggested action: keep open
Reason: The gap is real and still present: in docs/reference/files/charmcraft-yaml-file.rst the `links` section still only has 'Status' and 'Purpose' plus an example dropdown, with dangling anchors (_charmcraft-yaml-key-links-contact/-source/-issues/-website/-documentation) where per-key subsections were meant to go, while the model (charmcraft/models/charmcraft.py, class Links) allows only contact, documentation, issues, source, website. Maintainer @lengau explicitly acknowledged it ('I believe @jahn-junior is working on redoing these docs, but in the meantime the valid values in `links` are the values in this model: ...') and it is tracked internally as CHARMCRAFT-638, so it is triaged and valid, not stale. Fix is a small doc addition (list allowed keys and their value types), and docs/howto/manage-charms.rst already contains ready-made per-key examples to lift.
Evaluated by: mr-cal-bot
Issue body
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha |
Impact:
30
Quick Win:
22
Complexity:
12
Confidence:
88
Actionability:
85
|
keep open | Docs gap: charmcraft.yaml reference doesn't list which sub-keys are allowed under `links:`; reporter's `upstream` key was rejected. Maintainer confirmed valid values live in the Links model; docs redo in progress. | |
| qwen/qwen3.6-35b-a3b |
Impact:
45
Quick Win:
31
Complexity:
15
Confidence:
85
Actionability:
80
|
keep open | Documentation for charmcraft.yaml links section is unclear; valid fields (contact, documentation, issues, source, website) are not listed in docs. | |
| qwen/qwen3.8-27b |
Impact:
20
Quick Win:
18
Staleness:
55
Complexity:
10
Confidence:
78
Support Request:
20
|
keep open | charmcraft.yaml links section docs don't list allowed fields (contact, documentation, issues, source, website). Maintainer acknowledged and pointed to model definition; docs redo in progress but not yet merged. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
85
Complexity:
15
Confidence:
90
Support Request:
85
|
close not a bug | Clarification request for allowed fields in charmcraft.yaml links section. Maintainer pointed to the source schema, resolving the query. Issue has been inactive for over a year. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
85
Complexity:
20
Confidence:
80
Support Request:
10
|
keep open | Unclear documentation for valid values in the links section of charmcraft.yaml. Reporter encountered validation errors for unsupported fields. Maintainer pointed to source code model and noted docs are being rewritten. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
80
Complexity:
15
Confidence:
80
Support Request:
65
|
needs triage | Documentation request clarifying valid fields for the links section in charmcraft.yaml. A maintainer pointed to the source code model, but the issue remains unlabelled and pending official documentation updates. |
Update history
No update history recorded yet.
Related work
-
Related To:
canonical/charmcraft#2262
(confidence 70%)
Merged hotfix (commit 675e5e7e) that corrected the links syntax in the manage-charms doc examples, i.e. earlier work on the same links documentation; it did not add the missing list of allowed keys to the reference page.
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. | |
| #2859 Documentation links created by charmcraft are invalid | charmcraft | closed | Invalid help links were traced to incorrect Read the Docs configuration for Charmcraft 4.4; correcting the documentation setup restored valid versioned URLs without a Charmcraft code change. | |
| #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. |