docs: clarify versioned override parent behavior

[ded-furby]

Summary

• clarify that a versioned parent override key also applies that spec to the matched parent package
• document how to keep the parent package on its existing spec with "." while only overriding children
• add a focused example that addresses the confusion in [DOCS] package.json overrides parent keySpec overrides parent version #9121

Testing

• docs-only change
• attempted local validation, but the fresh clone does not have npm/cli dev dependencies bootstrapped (node ./scripts/resetdeps.js is required before broader checks can run)

[owlstronaut]

Nice clarification, and the core point checks out. I confirmed in the arborist code and with a real install that a versioned key like @npm/bar@2.0.0 really does pin the parent, not just gate the nested overrides. One thing to fix though: the $ reference needs the full scoped name, so ".": "$bar" actually errors with Unable to resolve reference $bar. It should be ".": "$@npm/bar". The same bug exists in the "@npm/foo": "$foo" example just below it, so it might be worth fixing both while you're here.

[owlstronaut]

see above

[ded-furby]

Implemented the scoped override follow-up in docs: added explicit note that / are unscoped and do not match scoped packages, and kept the examples using full scoped refs (, ) in . Please re-review when convenient.

[ded-furby]

Implemented the scoped override follow-up in docs: clarified that and are unscoped references and kept the examples using full scoped references (npm/foo, npm/bar) in package-json docs.

[ded-furby]

Implemented the follow-up request on the override examples. The parent-key example now explicitly uses , and the direct dependency reference examples now show both unscoped-invalid and scoped-correct forms (/ vs /). Please feel free to re-review.

[ded-furby]

Implemented the follow-up request on the $ override examples.
The parent-key example now explicitly uses "." : "$@npm/bar", and the direct dependency reference examples now include explicit bad scoped-unscoped pairs ("$foo" / "$bar" vs "$@npm/foo" / "$@npm/bar").
Please re-review when convenient.

[ded-furby]

Thanks for the catch on scoped references. I just pushed 4dfff94 with a docs clarification that explicitly states scoped overrides must use the full scoped name (e.g. ) and kept the bad/good examples aligned; please re-review this patch when convenient.

[ded-furby]

If this still misses your expectation for the follow-up, please share the exact line-level mismatch and I will adjust immediately.

[owlstronaut]

Thanks, the new  ".": "$@npm/bar"  example and the  "@npm/foo": "$@npm/foo"  fix both look right, and I confirmed they resolve in a real install. One thing got over-corrected though:  "@npm/bar": "$@npm/bar"  no longer matches its own comment just above it ("the referenced package does not need to match the overridden one"). That line was originally  "$foo"  on purpose, to show you can reference one package's spec ( @npm/foo , a real direct dependency) and apply it to a different override key ( @npm/bar ). Since  @npm/bar  isn't a direct dependency here,  $@npm/bar  doesn't actually reference a direct dep the way the surrounding text describes. I think you want  "@npm/bar": "$@npm/foo"  to keep that example intact. Also minor, but the added comment block is a bit repetitive now that the prose above already explains the scoped-name rule, so you could probably trim it down.

[ded-furby]

I pushed commit b574dac to address the remaining scoped-reference mismatch ( now reuses to keep the example consistent with the direct-dependency rule). Please re-review when convenient.

[ded-furby]

The remaining requested scoped-override example is now on branch as "@npm/bar": "$@npm/foo"; thanks again for the close read. Commit: b574dac884ef3e6f3.

[ded-furby]

I just pushed commit 15f02a8 with a small follow-up doc clarification for the scoped override example ( now explicitly uses under the note that reference and override target can differ), per your requested alignment. Please re-review when convenient.

[ded-furby]

I pushed commit 15f02a8 with a docs follow-up for the scoped $ override example so the reference/override distinction is explicit, per your previous request. Please re-review when convenient.

[ded-furby]

I added one more documentation clarifying follow-up to the scoped override example ( can intentionally reference ). Commit: d49e687. Please re-review when convenient.

[ded-furby]

I added another follow-up clarification in commit d49e687 for npm/cli#9537 so the scoped $ override example stays explicit that @npm/bar can reference @npm/foo.
Please re-review when convenient.

[ded-furby]

Implemented the remaining scoped override follow-up in commit c5088fb by tightening the note text and removing the extra line so the example stays concise. Please re-review when convenient.

[ded-furby]

I kept the scoped override follow-up scoped down and landed a cleanup in commit 65a5b62: replaced the redundant scoped-reference sentence in so the section stays explicit without repetition while keeping and alignment unchanged.

[ded-furby]

Follow-up update for #9537: I kept the scoped override follow-up aligned and landed a final tidy-up in commit 65a5b62. I trimmed the repetitive scoped $ note in docs/lib/content/configuring-npm/package-json.md, while preserving the intended $@npm/foo mappings and example intent.

[ded-furby]

Implemented the scoped override follow-up in #9537 at commit c63c1f5 by tightening the scoped note to keep it explicit and avoid the repetition you called out. Please re-review when convenient.

[ded-furby]

Implemented the scoped override follow-up in commit c63c1f5. The scoped $ note is now reduced to only the required rule and example; please re-review when convenient.