docs: adding the icon part to a charm is too hidden away
Metadata
Current evaluation
Docs gap closed by merged PR #2711 (commit 037c5b41): the Manage icons how-to now documents packaging icon.svg via a dump part, and the icon.svg reference page links to it.
Resolution: closed resolved
Reason: Maintainer jahn-junior confirmed in the closing comment that PR #2711 improved the icon pages, adding explicit Dump plugin guidance to the how-to and de-duplicating by linking the reference page to it. The PR is merged as commit 037c5b41, which also completed related issue #2593.
Evaluated by: mr-cal-bot
No scores available.
Issue body
*Please describe the question or issue you're facing with "Manage icons - Charmcraft dev documentation".*
It took me a looong time to discover that [this doc](https://documentation.ubuntu.com/charmcraft/4.2/reference/files/icon-svg-file/) has exactly what I needed - a method for including the icon in the charm:
```yaml
parts:
icon:
plugin: dump
source: .
stage:
- icon.svg
```
This is because:
1. The **most important information** is hidden (collapsed). <img width="1498" height="296" alt="Image" src="https://github.com/user-attachments/assets/d0cb0232-57ea-47cc-a54a-44a29c374d33" />
2. The "[manage icons](https://documentation.ubuntu.com/charmcraft/4.2/howto/manage-icons/)" doc, which is what I was following more closely, mentions nothing about it and doesn't link to the `icon.svg` doc.
---
*Reported from: https://documentation.ubuntu.com/charmcraft/4.2/howto/manage-icons/*
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Docs gap closed by merged PR #2711 (commit 037c5b41): the Manage icons how-to now documents packaging icon.svg via a dump part, and the icon.svg reference page links to it. | |
| stealth/space-bunny-alpha | — | closed resolved | Fixed by merged PR #2711: the Manage icons how-to now explains how to package icon.svg with a Dump part, and the reference page links to it as the single source of truth. | |
| qwen/qwen3.6-35b-a3b | — | — | Resolved via a linked PR. The main how-to now explicitly guides users on using the Dump plugin for icons, and the reference page links to it to maintain a single source of truth. | |
| qwen/qwen3.6-35b-a3b | — | — | Fixed via documentation update. The main how-to guide now explicitly covers adding icons via the Dump plugin, and the reference page links to it, resolving discoverability issues. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
15
Complexity:
20
Confidence:
90
Support Request:
10
|
keep open | Issue: Icon documentation is hard to find. The relevant info is hidden in a collapsed section and not linked from the main 'manage icons' how-to. Needs documentation improvement. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
10
Complexity:
15
Confidence:
85
Support Request:
10
|
needs triage | Documentation issue where icon inclusion instructions are buried in a collapsed section and not linked from the main how-to. Currently unlabelled and awaiting formal triage. |
Update history
| Date | Change |
|---|---|
| closed |
Related work
-
Likely Fixed By:
canonical/charmcraft#2711
(confidence 97%)
Merged docs PR (commit 037c5b41) adding Dump plugin icon-packaging guidance to the Manage icons how-to and linking the reference page to it; cited in the closing comment.
-
Related To:
canonical/charmcraft#2593
(confidence 85%)
Earlier issue where icon.svg is missing from built charms; closed with the same docs work in #2711.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2809 docs: refresh icon guidance | charmcraft | merged | Docs PR merged as commit 211b4130: rewrote the 'Manage icons' how-to, added icon.svg file paths to plugin migration guides, and trimmed the icon.svg reference to link to the how-to. Resolves #2593 and #2744. | |
| #2253 docs: add charm docs exemplars links | charmcraft | merged | Merged #2253 as commit 982a6c16, adding links to small and large charm documentation exemplars. | |
| #2129 docs: add additional anchors on the "manage charms" page for linking to | charmcraft | closed | Closed as a duplicate of #2128, which was merged as commit e880b4bd and added the requested intersphinx anchors to the Manage charms documentation. |