← Back to issue list

docs: Document that resources are bound to channels, not revisions.

View original Github issue

Metadata

Project
charmcraft
Number
#2866
Type
issue
State
open
Author
marcusboden
Labels
Type: Documentation
Created
Updated
Closed
—

Current evaluation

Docs request: clarify resources bind to channels, not revisions, since 'charmcraft release --resource' help text implies per-revision pinning. Behavior is correct; misleading docs/help only. No maintainer response yet.

Suggested action: needs triage

Reason: The gap is verified in-repo: the release command help at charmcraft/application/commands/store.py:796-802 states resources are 'attached to that release' and shows 'charmcraft release mycharm --revision=14 --channel=beta --resource=thedb:4', and a repo-wide grep for 'resource' returns no hits anywhere under docs/, so the requested explanation genuinely does not exist. The reporter supplies a clean reproducer (revisions 15/16/18 to edge with images 7/8/9, deploying --revision 15 yields image 9), which is correct Charmhub channel-binding semantics, so this is a docs/clarity request rather than a bug. With 0 comments, no assignee, and no maintainer response in 31 days, the issue shows no sign of categorization, so it needs triage — the one open decision is scope, since the cited page lives in the external juju docs site while the misleading help text is in this repo.

Evaluated by: mr-cal-bot

Impact: 35 Quick Win: 21 Complexity: 15 Confidence: 70 Actionability: 72

Issue body

Resources are bound to channels, not revision. This does not seem to be documented anywhere. The syntax of `charmcraft release` (e.g. in [publish charm](https://canonical.com/juju/docs/charmcraft/4/howto/manage-charms/#publish-a-charm)) indicates that you pin a resource to a revision: ``` charmcraft release my-awesome-charm --revision=1 --channel=beta--resource someresource:1 ``` But that is not the case. I released three revisions with three different resources: ``` 0 $ charmcraft release headscale-k8s --revision=15 --channel=edge --resource headscale-image:7 Revision 15 of 'headscale-k8s' released to edge (attaching resources: 'headscale-image' r7) 15:53:12 | m.b@c.c@mboden-laptop | ~ 0 $ charmcraft release headscale-k8s --revision=16 --channel=edge --resource headscale-image:8 Revision 16 of 'headscale-k8s' released to edge (attaching resources: 'headscale-image' r8) 15:53:17 | m.b@c.c@mboden-laptop | ~ 0 $ charmcraft release headscale-k8s --revision=18 --channel=edge --resource headscale-image:9 Revision 18 of 'headscale-k8s' released to edge (attaching resources: 'headscale-image' r9) 15:53:22 | m.b@c.c@mboden-laptop | ~ ``` When deploying with `--revision 15`, the attached resource was image 9. Having the images bound to channels is fine as well, but it should be clearly documented. --- *Reported from: https://canonical.com/juju/docs/charmcraft/4/howto/manage-resources/*

Evaluation history

Date Model Scores Action Summary
stealth/space-bunny-alpha
Impact: 35
Quick Win: 21
Complexity: 15
Confidence: 70
Actionability: 72
needs triage Docs request: clarify resources bind to channels, not revisions, since 'charmcraft release --resource' help text implies per-revision pinning. Behavior is correct; misleading docs/help only. No maintainer response yet.
stealth/space-bunny-alpha
Impact: 40
Quick Win: 25
Complexity: 25
Confidence: 80
Actionability: 83
needs triage Request to document that resources bind to Charmcraft release channels, not revisions, with a reproduced three-revision example; awaiting maintainer triage.
qwen3.6-35b-a3b-mtp-q6
Impact: 40
Quick Win: 32
Staleness: 5
Complexity: 20
Confidence: 80
Support Request: 10
needs triage Documentation issue requesting clarification that resources are bound to channels, not revisions, with a clear example showing the current behavior.

Update history

Date Change
created

Related work

  • Related To: charmcraft#2172 (confidence 55%)

    Commit df9125d6 'docs: update release step with resource details' previously adjusted resource release docs, but the channel-vs-revision distinction is still absent from the help text and docs/, so the gap persists.

Related issues

Issue Project State Summary Similarity
#877 [Documentation] What to do when api-error: Resource doesn't have a released revision on channel charmcraft closed Closed as expected behavior: every declared Charmhub resource must have a released revision. The maintainer annotated the docs and filed snapstore-server#1990845 to improve the unclear API error.
71%