Package lock docs should mention pinning the SDK version as a recommendation

[Frulfump]

Type of issue

Missing information

Description

This section should also mention pinning the SDK as was done in #53347 for the global.json docs

(Are there more pages where either lock files or global.json version selection is mentioned? If so they would also be good candidates to get the same notice)

Rationale from the linked issue above:

see comment from Microsoft(Chet) here dotnet/sdk#48795 (comment)

Our current recommendation for users that use lock files is to also lock their SDK versions via global.json with no rollforward, >so they(sic) their entire toolchain stays in lockstep.

Linking to an issue to track for when that recommendation changes would be preferable or at least the specific issues which >most users run into which require pinning the SDK in relation to lock-files
dotnet/aspnetcore#65061
dotnet/sdk#48795

It will aid in discovery of this fact

Ideally the blog post https://devblogs.microsoft.com/dotnet/enable-repeatable-package-restores-using-a-lock-file/ is also updated

Page URL

https://learn.microsoft.com/en-us/dotnet/core/install/upgrade#package-lock-files

Content source URL

https://github.com/dotnet/docs/blob/main/docs/core/install/upgrade.md

Document Version Independent Id

a20fa96c-6d92-d941-f6d0-bf0369028e7f

Platform Id

16950b17-b581-c2c6-3825-a45465ac0617

Article author

@adegeo

Metadata

• ID: 327f5330-9be0-25fe-1e75-3673f7809d0d
• PlatformId: 16950b17-b581-c2c6-3825-a45465ac0617
• Service: dotnet-fundamentals
• Sub-service: install

Related Issues

---

Associated WorkItem - 598917

[Frulfump]

(Are there more pages where either lock files or global.json version selection is mentioned? If so they would also be good candidates to get the same notice)

I did a quick search with GPT 5.5

Best candidates in dotnet/docs:

docs/core/tools/dotnet-restore.md
This page lists --use-lock-file, --locked-mode, --lock-file-path, and --force-evaluate. It is the strongest additional dotnet/docs candidate because users reading restore options may never see the upgrade article.

docs/core/versions/selection.md
This page explains SDK selection through global.json. It does not mention lock files. A short cross-link from its SDK selection section to the global.json rollForward guidance would make sense.

Already covered:

docs/core/tools/global-json.md
Issue #53347 appears handled here already. The rollForward: disable row now has a footnote saying to use disable with package lock files so the SDK version and dependency graph stay in lockstep.
Strong candidates outside dotnet/docs:

NuGet PackageReference in project files
Source: NuGet/docs.microsoft.com-nuget. This is probably the primary lock-file documentation and already has detailed sections on packages.lock.json, locked mode, and committing lock files.

Already created GitHub Issue

.NET Blog: Enable repeatable package restores using a lock file
The issue already calls this out, and it is directly about repeatable restores.
Lower-confidence candidates:

Azure Pipelines: Cache NuGet packages
It tells users to create and commit packages.lock.json for NuGet cache keys. It is CI-specific, so the SDK-pinning note could be useful, but it is outside .NET docs ownership.

Should I create an issue for each individually or is it possible to handle in bulk?
(Opened this PR for the Azure Pipelines: Cache docs MicrosoftDocs/azure-devops-docs#14369)