Add explanation for how `organize` works
Metadata
Current evaluation
A maintainer-requested explanation of organize is still missing; a contributor volunteered a focused page and a correction to the existing build-area-to-stage wording.
Suggested action: keep open
Reason: The documentation still describes organize as copying directly from the building area to staging, but part_handler.py shows it rearranges install-layout files at the end of the build step. The need is explicit, longstanding since 2017, and gcomneno has proposed a focused explanation page, but no implementation or resolving change exists.
Evaluated by: mr-cal-bot
Impact:
38
Quick Win:
24
Complexity:
26
Confidence:
94
Actionability:
84
Issue body
People have been wondering about the behaviour of `organize` since at least 2017 (https://bugs.launchpad.net/snapcraft/+bug/1669908). We should have an explanation to explain how it works.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha |
Impact:
38
Quick Win:
24
Complexity:
26
Confidence:
94
Actionability:
84
|
keep open | A maintainer-requested explanation of organize is still missing; a contributor volunteered a focused page and a correction to the existing build-area-to-stage wording. | |
| stealth/space-bunny-alpha |
Impact:
45
Quick Win:
22
Complexity:
40
Confidence:
93
Actionability:
82
|
keep open | Maintainer-opened documentation gap for `organize`; a contributor volunteered a focused explanation and wording correction, but the requested conceptual guide is not yet present. | |
| qwen3.6-35b-a3b-mtp-q6 |
Impact:
45
Quick Win:
34
Staleness:
35
Complexity:
25
Confidence:
75
Support Request:
15
|
keep open | Documentation improvement to add an explanation page for the `organize` feature, clarifying its lifecycle and file mapping semantics. A contributor has volunteered to implement it. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
10
Complexity:
15
Confidence:
85
Support Request:
10
|
needs triage | Request to add a dedicated documentation page explaining the organize directive's lifecycle and file mapping semantics, correcting existing inaccuracies. A contributor has volunteered to implement it. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
5
Complexity:
10
Confidence:
90
Support Request:
0
|
needs triage | Request to document the behavior of the organize directive, which has caused user confusion since 2017. Currently unlabelled and awaiting maintainer triage. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
0
Complexity:
10
Confidence:
90
Support Request:
10
|
needs triage | Request to document the behavior of the organize directive, citing long-standing user confusion since 2017. Currently unlabelled and awaiting maintainer triage. |
Update history
| Date | Change |
|---|---|
| updated |
Related work
-
Related To:
canonical/craft-parts#1582
(confidence 78%)
An earlier merged documentation correction addressed organize wording, but the current explanation still contains the lifecycle inaccuracy identified here.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1725 docs: explain organize behavior | craft-parts | open | Adds documentation explaining how organize works and corrects existing docs that misdescribed it as copying files from build to stage area. Closes #1644. CI passing except unrelated OSV-scanner findings. |