← 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

Current docs explain install-to-stage-to-prime migration and fileset filtering, but omitted stage/prime defaults remain implicit; #921 still requests fuller key-reference coverage.

Suggested action: needs triage

Reason: The lifecycle and file-migration pages now describe install-to-stage-to-prime migration and filtering, improved by PR #1307 (commit b75ee85b), while PartSpec defaults both keys to ["*"]. The prose still does not clearly explain omitted-key behavior, and open #921 targets the same reference gap; the sole comment is an automated Jira notice, so maintainer triage is still needed.

Evaluated by: mr-cal-bot

Impact: 27 Quick Win: 18 Complexity: 19 Confidence: 89 Actionability: 84

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
stealth/space-bunny-alpha
Impact: 27
Quick Win: 18
Complexity: 19
Confidence: 89
Actionability: 84
needs triage Current docs explain install-to-stage-to-prime migration and fileset filtering, but omitted stage/prime defaults remain implicit; #921 still requests fuller key-reference coverage.
qwen/qwen3.6-35b-a3b
Impact: 30
Quick Win: 19
Complexity: 10
Confidence: 80
Actionability: 70
needs triage Documentation request to explicitly explain the behavior and defaults of the `stage` and `prime` directives in craft-parts.
qwen/qwen3.8-27b
Impact: 30
Quick Win: 24
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.

Update history

No update history recorded yet.

Related work

  • Related To: canonical/craft-parts#921 (confidence 98%)

    This newer open issue explicitly requests fuller stage and prime key-reference coverage, including path examples.

  • Likely Fixed By: canonical/craft-parts#1307 (confidence 88%)

    Commit b75ee85b added substantial file-migration documentation covering stage, prime, and filtering.

Related issues

Issue Project State Summary Similarity
#921 `prime` and `stage` key reference should be fleshed out craft-parts open Documentation request to flesh out the stage and prime part-property references with path include/exclude examples. Current main contains those examples and dedicated fileset guidance, but the issue remains open.
80%