snapcraft syntax documentation is incomplete
Metadata
Current evaluation
10-year-old report that snapcraft.yaml syntax docs omitted app-level plugs. Docs have since been fully restructured into docs/reference/ (58 files); the old URL paths no longer exist. No maintainer interaction, zero comments.
Suggested action: close stale
Reason: The issue is 10 years old with zero comments and no labels. The documentation it references (snapcraft.io/docs/build-snaps/syntax) no longer matches the current repo structure, which now has a comprehensive docs/reference/ directory with 58 files. The specific gap (missing plugs under apps) is almost certainly addressed in the current reference docs, and the broader auto-generation suggestion is a separate enhancement that would need its own issue.
Impact:
25
Quick Win:
17.5
Staleness:
95
Complexity:
30
Confidence:
72
Support Request:
10
Issue body
The "definitive" snapcraft.yaml documentation at http://snapcraft.io/docs/build-snaps/syntax does not mention some crucial pieces.
For example, it does not mention that an app entry under the "apps" section can have a "plugs" section (it's mentioned in http://snapcraft.io/docs/build-snaps/metadata), which is essential for knowing how to allow access to resources for an app.
Perhaps the definitive syntax could be automatically generated from something in the snapcraft source so that there's less danger of it becoming out of sync.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.8-27b |
Impact:
25
Quick Win:
17.5
Staleness:
95
Complexity:
30
Confidence:
72
Support Request:
10
|
close stale | 10-year-old report that snapcraft.yaml syntax docs omitted app-level plugs. Docs have since been fully restructured into docs/reference/ (58 files); the old URL paths no longer exist. No maintainer interaction, zero comments. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
99
Complexity:
10
Confidence:
95
Support Request:
5
|
close stale | Reports incomplete snapcraft.yaml syntax documentation, specifically missing app-level plugs. Suggests auto-generating docs from source. No activity in ~10 years. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
100
Complexity:
15
Confidence:
90
Support Request:
10
|
close stale | Documentation for snapcraft.yaml syntax is incomplete and lacks details like app-level plugs. No maintainer response or labels after nearly 10 years. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
98
Complexity:
20
Confidence:
90
Support Request:
10
|
close stale | Documentation for snapcraft.yaml syntax lacks details like app-level plugs. Suggests auto-generating docs from source. Issue is nearly 10 years old with no maintainer response. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
99
Complexity:
25
Confidence:
92
Support Request:
10
|
close stale | snapcraft.yaml syntax documentation lacks crucial details like app plugs. Suggests auto-generating docs from source to prevent drift. Open, inactive, and unlabelled, requiring triage and assignment. |
Update history
No update history recorded yet.
Related work
-
Related To:
canonical/snapcraft#131
(confidence 80%)
PR that originally added the snapcraft.yaml syntax documentation this issue is complaining about.
-
Related To:
canonical/snapcraft#5511
(confidence 70%)
Later issue about missing part key descriptions in the same reference docs, resolved by PR #5566 — shows the reference docs have been actively maintained and expanded since this issue.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1654899 snapcraft.yaml syntax docs missing ‘classic’ confinement mode | snapcraft (launchpad) | open | Docs gap: snapcraft-syntax.md listed only devmode/strict confinement, omitting classic. 9.6 years old, 0 comments, no maintainer response; the referenced doc file predates the current restructured docs/reference layout. | |
| #1607249 docs/snapcraft-syntax.md should refer to source related syntax | snapcraft (launchpad) | closed | Abandoned and closed as outdated by maintainer @mr-cal. No documentation updates were implemented. | |
| #131 add document detailing the snapcraft.yaml syntax | snapcraft | merged | Successfully merged documentation detailing the snapcraft.yaml syntax. The author rebased changes to master and resolved a minor version control mix-up, integrating the new syntax reference guide into the repository. | |
| #1533021 Documentation refresh for 2.0 features | snapcraft (launchpad) | closed | Closed without resolution. Documentation for snapcraft 2.0 features remains outdated regarding format, licenses, and CLI lifecycle help. Likely abandoned or superseded by newer releases due to prolonged inactivity. | |
| #1741091 Installing snapcraft (and its dependencies) | snapcraft (launchpad) | open | Reports a missing 'cd snapcraft' step in the HACKING.md install guide. Open 8+ years with zero comments, no labels, and no maintainer interaction; the referenced HACKING.md no longer exists at the repo root (docs restructured into docs/contribute/). | |
| #5511 snapcraft.yaml reference documentation missing descriptions for part keys | snapcraft | closed | Missing snapcraft.yaml part key descriptions were added and integrated with Craft Parts source code. The documentation update was completed and merged via pull request #5566 in the canonical/snapcraft repository. | |
| #1869542 snapcraft unable to find snap/snapcraft.yaml file | snapcraft (launchpad) | open | snapcraft 3.11 (2019) loses snap/snapcraft.yaml after a few builds and drops to the VM shell; workaround is snapcraft clean. 6+ years old, no labels, no maintainer comments, tied to a long-superseded build environment. | |
| #1845276 snapcraft shouldn't complain about snap/README.md | snapcraft (launchpad) | open | Request to stop snapcraft warning about snap/README.md as a non-snapcraft path so docs can live in the snap/ dir. 7 years old, zero comments, no labels or maintainer response; the warning is intentional and already documents the snap/local/ workaround. |