← Back to issue list

Explain how `stage` and `prime` work in the docs

View original Github issue

Metadata

Project
craft-parts
Number
#456
Type
issue
State
open
Author
ca-scribner
Labels
—
Created
Updated
Closed
—

Current evaluation

Docs request to explain stage/prime fileset semantics and defaults. Open 1201 days with only a bot Jira-sync comment; related issue #921 on the same topic is still open, so the gap persists.

Suggested action: keep open

Reason: The only comment is an automated Jira-sync (CRAFT-2929), so no maintainer has triaged or labelled it, but the request remains valid: docs/common/craft-parts/explanation/filesets.rst exists and #921 (flesh out prime/stage reference) is still open, confirming the gap was never addressed. Closing as stale would be wrong since the underlying docs gap persists; it needs a maintainer to scope/assign the doc update.

Impact: 30 Quick Win: 24.0 Staleness: 70 Complexity: 20 Confidence: 75 Support Request: 10

Issue body

My understanding of the `stage` and `prime` directives are that they let you specify: * stage: what files go from `$CRAFT_PART_INSTALL` to `$CRAFT_STAGE` * prime: what files go from `$CRAFT_STAGE` to `$CRAFT_PRIME` and that, if omitted, the default behaviour is to copy everything in each of those locations. It would be great to have this explained more in the docs. There's a few hints at this, but I don't see anything that explicitly describes the behaviour (especially the default behaviour). I found it awkward to learn how to use these when I'd see some `rockcraft.yaml` files using `stage` and `prime`, and others omitting them entirely.

Evaluation history

Date Model Scores Action Summary
qwen/qwen3.8-27b
Impact: 30
Quick Win: 24.0
Staleness: 70
Complexity: 20
Confidence: 75
Support Request: 10
keep open Docs request to explain stage/prime fileset semantics and defaults. Open 1201 days with only a bot Jira-sync comment; related issue #921 on the same topic is still open, so the gap persists.
qwen/qwen3.6-35b-a3b
Staleness: 95
Complexity: 15
Confidence: 85
Support Request: 10
close stale Request to document stage and prime directive behavior and defaults in Craft. Currently unlabelled, inactive for over a year, with only an automated Jira sync comment.
qwen3.6-35b-a3b-mtp-q6
Staleness: 85
Complexity: 15
Confidence: 90
Support Request: 10
needs triage Documentation request clarifying stage and prime directive behavior and defaults. Unlabelled and unassessed, with only an automated Jira sync comment from over a year ago.
qwen3.6-35b-a3b-mtp-q6
Staleness: 88
Complexity: 12
Confidence: 75
Support Request: 25
needs triage Requests clearer documentation for the stage and prime directives, detailing their purpose and default behavior of copying all files when omitted. Internal Jira ticket CRAFT-2929 created. Open and pending documentation updates.

Update history

No update history recorded yet.

Related work

  • Related To: craft-parts#921 (confidence 85%)

    Both request documentation of stage/prime key semantics; #921 covers the reference page, this covers the explanation of default copy behaviour.

Related issues

Issue Project State Summary Similarity
#921 `prime` and `stage` key reference should be fleshed out craft-parts open Docs gap: the `prime` and `stage` part-property reference pages lack examples and value semantics (e.g. `-` for exclusions). Filed by a maintainer, acknowledged by a second maintainer, but no labels/assignee and no doc update since.
76%