docs: explain organize behavior
Metadata
Current evaluation
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.
Suggested action: needs review
Reason: This is a straightforward documentation PR (+303/-10 lines) that addresses maintainer-requested issue #1644. CI is passing (the failing OSV-scanner jobs are unrelated security findings in urllib3, as the author noted). No reviewers have been assigned yet and no review comments exist, so it is ready for maintainer review.
Evaluated by: mr-cal-bot
Impact:
30
Quick Win:
22
Complexity:
10
Confidence:
80
Actionability:
80
Issue body
## Summary
Add a focused explanation of how `organize` works.
The new page describes when `organize` is applied and explains its file,
directory, pattern, build-directory, partition, overlay, ordering, conflict,
and source-path semantics.
It also corrects existing documentation that described `organize` as copying
files directly from the build area to the stage area. `organize` instead
rearranges the part's install layout at the end of the build step, before the
stage step migrates that layout into the common stage area.
Closes #1644
## Testing
- Sphinx documentation build with `--fail-on-warning`
- `sphinx-lint`
- Vale Canonical spelling check
- Vale inclusive-terms check
- `git diff --check`
## Checklist
- [x] Have you followed the guidelines for contributing?
- [x] Have you signed the CLA?
- [ ] Have you successfully run `make lint && make test`?
- [ ] Have you added an entry to changelog (`docs/reference/changelog.rst`)?
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b |
Impact:
30
Quick Win:
22
Complexity:
10
Confidence:
80
Actionability:
80
|
needs review | 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. | |
| stealth/space-bunny-alpha |
Impact:
32
Quick Win:
12
Complexity:
38
Confidence:
87
Actionability:
58
|
needs review | Adds a 302-line explanation of organize semantics and corrects file-migration wording for issue #1644; it awaits initial review, with lint and tests still pending. | |
| qwen/qwen3.6-35b-a3b |
Impact:
35
Quick Win:
21
Complexity:
15
Confidence:
75
Actionability:
70
|
needs review | Documentation PR adding a focused explanation of organize behavior and correcting existing docs. Closes #1644. CI policy checks passing, tests pending, no reviews yet. |
Update history
| Date | Change |
|---|---|
| updated | |
| updated | |
| created |
Related work
-
Related To:
craft-parts#1644
(confidence 95%)
The PR closes this issue, which requested an explanation of how organize works.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1582 docs: correct the 'organize' description | craft-parts | merged | Merged PR #1582 corrected the "organize" command description with a three-line documentation update. | |
| #1644 Add explanation for how `organize` works | craft-parts | 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. |