← Back to issue list

Weird phrasing in documentation

View original Github issue

Metadata

Project
snapcraft
Number
#5884
Type
issue
State
closed
Author
dilyn-corner
Labels
Status: Triaged Type: Documentation
Created
Updated
Closed

Current evaluation

Docs wording fix: the layouts reference heading in docs/reference/layouts.rst was clarified to "Disallowed target paths", removing the confusing phrasing. Resolved by merged PR #5928 (commit dfc406fa0).

Resolution: closed resolved

Reason: The requested wording change was made to docs/reference/layouts.rst in commit dfc406fa0 ("docs: fix confusing wording in 'layouts' reference"), merged via PR #5928, which resolves the report. The file at HEAD now reads "**Disallowed target paths**. The target path in a layout definition can't be:" followed by the list of forbidden paths.

Evaluated by: mr-cal-bot

No scores available.

Issue body

https://github.com/canonical/snapcraft/blob/3249bed8e4980bd31e4f789b8f4ce9dfcd63216e/docs/reference/layouts.rst?plain=1#L49 The phrase is confusing -- are these paths allowed or not? These aren't allowed paths, so I'd make the bold `Disallowed target paths` (considering it's probably phrased this way as the allow-list is far larger than the disallow list).

Evaluation history

Date Model Scores Action Summary
stealth/space-bunny-alpha — closed resolved Docs wording fix: the layouts reference heading in docs/reference/layouts.rst was clarified to "Disallowed target paths", removing the confusing phrasing. Resolved by merged PR #5928 (commit dfc406fa0).
stealth/space-bunny-alpha — closed resolved Doc wording nit on docs/reference/layouts.rst: the bold heading was changed to "Disallowed target paths". Fixed by merged PR #5928, commit dfc406fa0.
stealth/space-bunny-alpha — closed resolved Confusing layouts docs wording fixed by PR #5928 (commit dfc406fa0), which reworded the bold heading to "Disallowed target paths" in docs/reference/layouts.rst. The issue was closed as resolved.
stealth/space-bunny-alpha — closed resolved Docs wording in layouts.rst made unambiguous by renaming the confusing bold heading to "Disallowed target paths". Fixed via merged PR #5928, commit dfc406fa0.
stealth/space-bunny-alpha — closed resolved Clarified the layouts documentation to say “Disallowed target paths.” Resolved by merged PR #5928, commit dfc406fa0.
qwen/qwen3.6-35b-a3b — — Closed without documentation updates. The report was synced to internal Jira ticket SNAPCRAFT-1261 for tracking, but no repository changes were merged or applied.
qwen/qwen3.6-35b-a3b — — Abandoned after closure. An internal Jira ticket was created, but the suggested documentation wording change regarding allowed and disallowed paths was never implemented or addressed.
qwen/qwen3.6-35b-a3b — — Closed without a fix. Documentation phrasing regarding allowed paths was flagged as confusing, but no changes were applied. Feedback was routed to an internal Jira ticket.
qwen3.6-35b-a3b-mtp-q6 — — Abandoned. Documentation phrasing regarding allowed paths was flagged as confusing, but no changes were made. Feedback was synced to Jira ticket SNAPCRAFT-1261.

Update history

No update history recorded yet.

Related work

  • Likely Fixed By: canonical/snapcraft#5928 (confidence 97%)

    Merged PR titled 'docs: fix confusing wording in layouts reference' (commit dfc406fa0); commit appears in the git history of docs/reference/layouts.rst and updates the heading to 'Disallowed target paths'.

  • Related To: canonical/snapcraft#5392 (confidence 30%)

    Commit a161f0715 'docs: migrate layouts' is the prior migration commit that introduced the originally reported wording; superseded by dfc406fa0.

Related issues

Issue Project State Summary Similarity
#5928 docs: fix confusing wording in 'layouts' reference snapcraft merged Merged PR #5928 (commit dfc406fa0) clarified confusing layouts documentation and resolved #5884.
81%