← Back to issue list

snapcraft syntax documentation is incomplete

View original Launchpad issue

Metadata

Project
snapcraft (launchpad)
Number
#1617253
Type
issue
State
open
Author
~rogpeppe
Labels
—
Created
Updated
Closed
—

Current evaluation

The former syntax page omitted app-level plugs; the current source-backed snapcraft.yaml reference documents App plugs and other project fields.

Suggested action: close resolved

Reason: Commit 8a046bb00 (canonical/snapcraft#5421) added the snapcraft.yaml reference, whose App keys section includes App plugs through the source-backed pydantic-kitbash mechanism enabled in docs/conf.py. The current reference therefore addresses both the reported omission and the concern about documentation drifting from source models.

Evaluated by: mr-cal-bot

Impact: 43 Quick Win: 25 Complexity: 34 Confidence: 97 Actionability: 88

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
stealth/space-bunny-alpha
Impact: 43
Quick Win: 25
Complexity: 34
Confidence: 97
Actionability: 88
close resolved The former syntax page omitted app-level plugs; the current source-backed snapcraft.yaml reference documents App plugs and other project fields.
qwen/qwen3.6-35b-a3b
Impact: 30
Quick Win: 7
Complexity: 20
Confidence: 50
Actionability: 30
close stale Documentation for snapcraft.yaml syntax was reported as incomplete, with suggestions for auto-generation from source code. Issue has been open for 10 years with no maintainer response.
qwen/qwen3.8-27b
Impact: 25
Quick Win: 18
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.

Update history

Date Change
created

Related work

  • Likely Fixed By: canonical/snapcraft#5421 (confidence 98%)

    Commit 8a046bb00 added the snapcraft.yaml reference that now includes apps.<app-name>.plugs.

  • Related To: canonical/snapcraft#5466 (confidence 91%)

    Merged commit 2670e8278 moved snapcraft.yaml documentation into the Read the Docs project-file reference.

Related issues

No related issues found above the similarity threshold.