docs: improve `charmcraft clean` command documentation
Metadata
Current evaluation
Closed unmerged; maintainer @lengau rejected the proposed charmcraft clean documentation as subpar, and no documentation commit or replacement PR landed.
Resolution: closed stale
Reason: PR #2795 was closed unmerged after @lengau commented, "No this is really subpar." The proposed documentation was abandoned without a resolving commit or identified superseding PR.
Evaluated by: mr-cal-bot
No scores available.
Issue body
The `clean` command's help text was inherited verbatim from `craft-application` with minimal description, giving users no actionable guidance on when or how to use it.
## Changes
- **`charmcraft/application/commands/lifecycle.py`**: Override `CleanCommand` from `craft-application` with:
- Updated `help_msg`: `"Remove a charm's build artefacts"` (was `"Remove a part's assets"`)
- Comprehensive `overview` explaining no-args behaviour (destroys managed build instance) vs. named-parts behaviour (selective artefact removal), with usage examples
- `get_lifecycle_commands()` now returns the local `CleanCommand`
- **`docs/howto/manage-charms.rst`**: New "Clean charm build artefacts" section between Pack and Publish, covering when to clean (config/plugin changes, ensuring fresh builds), both full and per-part invocation, and a cross-reference to the command reference page.
The auto-generated reference docs at `ref_commands_clean` will reflect the improved overview on next build.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed stale | Closed unmerged; maintainer @lengau rejected the proposed charmcraft clean documentation as subpar, and no documentation commit or replacement PR landed. | |
| stealth/space-bunny-alpha | — | closed stale | PR #2795 was closed unmerged after maintainer @lengau rejected the proposed `charmcraft clean` documentation as “subpar”; no resolving commit was added. | |
| qwen/qwen3.6-35b-a3b | — | — | Documentation improvements for the charmcraft clean command were rejected and closed after a reviewer criticized the changes as subpar. The pull request was not merged. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Rejected by a maintainer as subpar. The pull request proposed updated help text and documentation for the charmcraft clean command but was closed without merging. |
Update history
| Date | Change |
|---|---|
| created |
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1434 Improve Documentation for 'charmcraft help clean' Command | charmcraft | open | Documentation request for `charmcraft clean` help text; current overview is brief and issue lacks specific gaps. Related PR #2795 was rejected as subpar; no maintainer triage on issue. | |
| #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). | |
| #1851 How-to doc for charmcraft test | charmcraft | open | Documentation request from a maintainer to write a how-to guide for the undocumented `charmcraft test` command. Open with no labels, assignee, or maintainer triage; only an automated Jira-sync bot comment (CRAFT-3957). | |
| #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. | |
| #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. | |
| #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. | |
| #188 Small text cleanups for README and charmcraft help | charmcraft | merged | Merged README and charmcraft help-text cleanups in ffc44697, updating 13 files after approval by two reviewers. | |
| #1420 fix: use craft-application clean command | charmcraft | closed | PR #1420 (switch clean to craft-application) was closed unmerged, with no matching commit in charmcraft/commands/clean.py history. The same cleanup landed later via merged PR #1571 (commit 053d5a2d), which deleted the redundant clean command. | |
| #2154 docs: replace occurrences of "charmcraft.yaml" and "recipe" | charmcraft | merged | Merged PR #2154 (a6ccb3d4) updated 23 documentation files to use “project” or “project file” instead of “charmcraft.yaml” and “recipe.” | |
| #1668 Update command docs for the unification of charmcraft.yaml | charmcraft | open | Command help still uses metadata.yaml for list-lib while lifecycle help uses charmcraft.yaml; later documentation cleanups were partial, leaving the unification task unresolved. |