Docs: Rewrite `overlay` field description
Metadata
Current evaluation
Resolved by PR #1418 (commit 4497ece3), which rewrote the overlay field description to clarify exhaustive filtering, negation syntax, and examples.
Resolution: closed resolved
Reason: PR #1418 updated the overlay field documentation in commit 4497ece3, clarifying that an explicit list is exhaustive and improving the filtering examples, resolving #1401.
Evaluated by: mr-cal-bot
No scores available.
Issue body
## Situation
In canonical/rockcraft/pull/1041, we're transcluding the docs of the `overlay` key for the first time.
The key's documentation needs improvement and additional context:
https://github.com/canonical/craft-parts/blob/f2227aac531a1de6cf454081717c3256b2663462/craft_parts/parts.py#L387
## Request
- [ ] Fix "overly" typo.
- [ ] Remove "overlay filesystem" as a term, as it's unhelpful to users.
- [ ] Rewrite the description so that it informs how the user will use the key to productive effect:
- Describe what happens when the list is set at all. It's an _exhaustive_ list.
- Describe the path negation syntax.
- [ ] Review the second example. Why would `-etc/...` be needed when it automatically excludes everything that's not listed?
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Resolved by PR #1418 (commit 4497ece3), which rewrote the overlay field description to clarify exhaustive filtering, negation syntax, and examples. | |
| stealth/space-bunny-alpha | — | closed resolved | Updated the `overlay` documentation to clarify its exhaustive filtering behavior and examples; PR #1418 closed issue #1401. | |
| qwen/qwen3.6-35b-a3b | — | — | Overlay field documentation was rewritten to fix typos, clarify exhaustive list behavior, and explain path negation syntax. The issue was closed after documentation updates clarifying example usage and negation behavior. | |
| qwen/qwen3.6-35b-a3b | — | — | Closed and tracked via internal Jira ticket for documentation updates. The overlay field description was slated for rewriting to fix typos, clarify usage, and correct examples. | |
| qwen/qwen3.6-35b-a3b | — | — | Closed without resolution. Documentation improvements for the overlay field were requested, including typo fixes, usage explanations, and negation syntax clarification. Author provided follow-up comments, but no changes were merged or implemented. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Closed without resolution. Requested documentation improvements for the overlay field, including typo fixes, clearer explanations of exhaustive lists and path negation, and example corrections. No changes were applied, leaving it abandoned. |
Update history
No update history recorded yet.
Related work
-
Likely Fixed By:
canonical/craft-parts#1418
(confidence 100%)
The documentation update was merged in commit 4497ece3 and closed issue #1401.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1418 docs: update overlay filter field description | craft-parts | merged | Merged PR #1418 (commit 4497ece3) clarified the overlay field’s exhaustive filtering behavior and examples, resolving #1401. | |
| #370 docs: explanation section for overlays | craft-parts | merged | Merged PR #370 as commit a90caeb4, adding overlay documentation and incorporating #365’s lifecycle changes; it resolved CRAFT-1560. |