← Back to issue list

Documentation doesn't describe which keys can use advanced grammar

View original Github issue

Metadata

Project
snapcraft
Number
#5995
Type
issue
State
open
Author
waveform80
Labels
Status: Triaged Type: Documentation
Created
Updated
Closed
—

Current evaluation

Docs gap: advanced-grammar reference never lists which snapcraft.yaml keys support the syntax (only hinted via examples). Maintainer confirmed the omission and pointed to a separate feature request for broader key coverage; doc fix still pending.

Suggested action: keep open

Reason: Maintainer @mr-cal explicitly acknowledged the gap ("You are right - this isn't documented") and the issue is labelled Status: Triaged / Type: Documentation, so it is triaged and valid. The current docs/reference/advanced-grammar.rst still only shows build-packages/build-environment examples with no key list, so the fix is not yet done. The related feature request (canonical/snapcraft#5469 for package-repositories) is a separate scope, not a fix for this doc gap.

Impact: 35 Quick Win: 29.75 Staleness: 45 Complexity: 15 Confidence: 80 Support Request: 20

Issue body

Where can the advanced grammar be used? This is never defined by the documentation, merely hinted at by the examples. From the examples, we can see `build-packages` and `build-environment` can be affected, but the text is vague enough to imply this *might* be useable elsewhere? Though, when attempting this with `parts.*.cmake-parameters` apparently that's not one of the places it works. --- *Reported from: https://documentation.ubuntu.com/snapcraft/stable/reference/advanced-grammar/*

Evaluation history

Date Model Scores Action Summary
qwen/qwen3.8-27b
Impact: 35
Quick Win: 29.75
Staleness: 45
Complexity: 15
Confidence: 80
Support Request: 20
keep open Docs gap: advanced-grammar reference never lists which snapcraft.yaml keys support the syntax (only hinted via examples). Maintainer confirmed the omission and pointed to a separate feature request for broader key coverage; doc fix still pending.
qwen/qwen3.6-35b-a3b
Staleness: 60
Complexity: 20
Confidence: 85
Support Request: 10
keep open Documentation gap regarding which snapcraft.yaml keys support advanced grammar. Maintainer acknowledged the lack of documentation and suggested splitting the feature request to expand grammar usage into a separate issue. Currently awaiting further action or documentation update.
qwen3.6-35b-a3b-mtp-q6
Staleness: 50
Complexity: 10
Confidence: 85
Support Request: 0
keep open Documentation gap detailing which snapcraft.yaml keys support advanced grammar. Maintainer clarified scope but docs remain unupdated. Issue is triaged and valid, awaiting documentation update.
qwen3.6-35b-a3b-mtp-q6
Staleness: 40
Complexity: 10
Confidence: 90
Support Request: 5
keep open Documentation lacks clarity on which snapcraft.yaml keys support advanced grammar. Maintainers confirmed it applies to common plugin keys only. Triaged and awaiting a docs update, with broader expansion requests deferred to separate issues.

Update history

No update history recorded yet.

Related work

  • Related To: canonical/snapcraft#5469 (confidence 85%)

    Referenced by maintainer as the only other advanced-grammar expansion request (package-repositories); separate feature scope from this documentation gap.

Related issues

Issue Project State Summary Similarity
#6064 Extend advanced grammer to all keys of snapcraft snapcraft open Request to extend advanced grammar (on/to/else) to all snapcraft.yaml keys (apps, plugin params like cmake-parameters, per-arch part skipping). Grammar currently limited to 6 part keys. Unlabeled; cross-referenced to craft-application#985.
74%
#1688 Documentation for advanced grammar for sources snapcraft closed Documentation for advanced grammar in snapcraft.yaml was added to the canonical-docs/snappy-docs repository. The syntax update pull request was reviewed and merged, fulfilling the request to document grammar expansion for strings and sources.
73%