docs: dump plugin docs don't provide enough information to even get started

Metadata

Project: snapcraft
Number: #5770
Type: issue
State: open
Author: artiepoole
Labels: Type: Documentation
Created: 2025-09-11 04:42 PM UTC
Updated: 2026-09-01 11:10 AM UTC
Closed: —

Current evaluation

Docs request: dump plugin reference lacks examples and key descriptions. Partly addressed by merged craft-parts PR #1547 and the include_files how-to, but the Keys section still has no per-key type/default/description; maintainer asked about reader context.

Suggested action: keep open

Reason: A maintainer (medubelko) acknowledged the gap — "The design of the plugin references need refinement and rethinking... We have the intention to improve them, but that will take time" — and a second user (@WyvernIXTL) confirmed 31 days ago that the problem persists: dump_plugin.rst still only says "This plugin has no unique keys" with no per-key descriptions, unlike rust_plugin.rst which uses kitbash-field entries. Commit fb57e5a3 (craft-parts#1547) added one nginx example and the shared how-to include_files.rst now covers local/deb/tar/git examples, so the original ask is partly met, but the Keys section gap and organize:/override-build guidance remain unaddressed. Keeping open because the remaining work is valid and was explicitly acknowledged rather than rejected.

Evaluated by: mr-cal-bot

Impact: 38 Quick Win: 21 Complexity: 22 Confidence: 82 Actionability: 72

Issue body

*Please describe the question or issue you're facing with "Dump plugin - Snapcraft 8.12.0 documentation".* How do you use the dump plugin? This does not give adequate information to even know how to start. I do not need this document immediately, but was hoping to link it to someone else to give them some help. Instead I have to scour the internet for examples and provide links to those in order to find out what options there are. Just adding three examples would be extremely helpful: 1) how to use this with a git repository 2) how to use this to add local files to a target path in the installed snap 3) how to include a subset of files Explanations of the following would also be great 1) How to override-build to customise the subset of files which end up in the final snap. 2) What all of the options are (e.g. options for source-type and with or without `organize:` etc.). 3) Explain how `organize:` can be used/how it works (or link to where it is explained). edit: I am willing to provide a rough draft based on what I have found, if it would help enough *Reported from: https://documentation.ubuntu.com/snapcraft/stable/common/craft-parts/reference/plugins/dump_plugin/*

Evaluation history

Date	Model	Scores	Action	Summary
2026-10-02 05:09 PM UTC	stealth/space-bunny-alpha	Impact: 38 Quick Win: 21 Complexity: 22 Confidence: 82 Actionability: 72	keep open	Docs request: dump plugin reference lacks examples and key descriptions. Partly addressed by merged craft-parts PR #1547 and the include_files how-to, but the Keys section still has no per-key type/default/description; maintainer asked about reader context.
2026-09-20 10:39 AM UTC	qwen/qwen3.6-35b-a3b	Impact: 35 Quick Win: 20 Complexity: 25 Confidence: 75 Actionability: 75	keep open	Documentation for the dump plugin lacks examples and key explanations. Maintainers acknowledged the gap and an open PR may address it, but improvements remain incomplete.
2026-09-06 11:11 AM UTC	qwen3.6-35b-a3b-mtp-q6	Impact: 50 Quick Win: 40 Staleness: 15 Complexity: 20 Confidence: 85 Support Request: 10	keep open	Documentation for dump plugin lacks examples and key descriptions. Maintainer acknowledged; PR craft-parts#1597 adding examples is actively in review (updated 4 days ago).
2026-09-01 02:54 AM UTC	qwen/qwen3.8-27b	Impact: 45 Quick Win: 32 Staleness: 55 Complexity: 30 Confidence: 75 Support Request: 20	keep open	Dump plugin docs lack examples and explanations for common use cases (git, local files, organize). Maintainer acknowledged and redirected to craft-parts; a PR adding an example was merged, but the broader request remains partially unaddressed.
2026-07-22 12:14 PM UTC	qwen/qwen3.6-35b-a3b	Staleness: 75 Complexity: 15 Confidence: 85 Support Request: 10	keep open	Documentation request for the Snapcraft dump plugin lacks basic examples and option explanations. Maintainer acknowledged it as a known design flaw but requested more context on the reporter's background before proceeding.
2026-07-08 11:40 AM UTC	qwen3.6-35b-a3b-mtp-q6	Staleness: 80 Complexity: 20 Confidence: 75 Support Request: 10	keep open	Documentation request to add usage examples and option explanations for the Snapcraft dump plugin. Acknowledged by a maintainer but inactive for 9 months with no concrete action plan.

Update history

Date	Change
2026-09-01 11:10 AM UTC	updated

Related work

Duplicate Of: craft-parts#1531 (confidence 88%)
The issue was moved to craft-parts as the canonical tracking issue for adding explanation/examples to dump_plugin; that issue is still open. The docs live in craft-parts (docs/common/craft-parts/reference/plugins/dump_plugin.rst) and are bundled into snapcraft docs.
Likely Fixed By: craft-parts#1547 (confidence 80%)
Merged PR fb57e5a3 ('docs: add example to dump plugin') added a single organize/nginx example to the dump plugin reference — it addresses only part of the ask (examples 2/3 and organize:) and did not touch the Keys section.

Related issues

Issue	Project	State	Summary	Similarity
#1531 docs: Add more explanation and/or examples to dump_plugin	craft-parts	open	Doc request for examples on the dump plugin reference page; resolved by merged PR #1547 (fb57e5a3), which added a YAML example with local source and organize remapping. Issue still open in tracker.	74%
#676 docs(plugins): add dump plugin docs	craft-parts	merged	Merged dump-plugin documentation covering usage, source behavior, overrides, and an example via commit 2c7b7170.	73%