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.

[ded-furby]

I implemented the remaining follow-up on the scoped override example semantics in commit so the example explicitly inherits ’s direct dependency spec: , with one line clarifying the intent. Please re-review when convenient.

[ded-furby]

I implemented the remaining scoped-override follow-up in commit a22e68c so the example keeps the intent explicit: "@npm/bar" now inherits the direct dependency spec from "@npm/foo" using "$@npm/foo" and includes a clarifying sentence in that section. Please re-review when convenient.

[ded-furby]

I made one follow-up clarity tweak in commit on branch to explicitly state why this scoped override keeps the spec for inherited from the direct dependency while is overridden. Could you please take another look when convenient?

[ded-furby]

I made one follow-up clarity tweak in commit 5d606d8 on branch docs/overrides-parent-key-clarity to explicitly state the scoped override intent (bar inherits from @npm/foo while overriding @npm/bar). Please re-review when convenient.

[ded-furby]

I pushed follow-up commit 8ba5c3a with a wording cleanup that explicitly shows using to inherit a different direct dependency spec while still being overridden. Please re-review when convenient.

[ded-furby]

I pushed follow-up commit 8ba5c3a. It explicitly clarifies @npm/bar resolves against $@npm/foo, so the override target can differ from the inherited direct dependency in this example.