Incorrect documentation on the default rollForward policy (when a version is specified)

[asmichi]

Type of issue

Typo

Description

https://learn.microsoft.com/en-us/dotnet/core/tools/global-json#rollforward

patch

This value is the legacy behavior from the earlier versions of the SDK.

https://learn.microsoft.com/en-us/dotnet/core/tools/global-json#matching-rules

• If a global.json file is found and it specifies an SDK version:

  • If no rollForward value is set, it uses latestPatch as the default rollForward policy.

Contrary to the above documentation, the actual default rollForward policy seems to be patch.

Please see dotnet/core-setup#6953 and the demonstration below.

dotnet/core-setup#6953 (comment)

For backwards compatibility, the policy when a version is not specified in
global.json will be latestMajor. The default policy when a version is
specified but rollForward is not specified will be patch.

demo

With SDK 8.0.406 and 8.0.405 installed, a global.json specifying version 8.0.405 resolves to 8.0.405, which is not the latestPatch behavior.

C:\Temp\newdir>dotnet new global.json --sdk-version 8.0.405

C:\Temp\newdir>type global.json
{
  "sdk": {
    "version": "8.0.405"
  }
}

C:\Temp\newdir>dotnet --info
.NET SDK:
 Version:           8.0.405
 Commit:            fb1830d421
 Workload version:  8.0.400-manifests.ada3c140
 MSBuild version:   17.11.9+a69bbaaf5

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.26100
 OS Platform: Windows
 RID:         win-x64
 Base Path:   C:\Program Files\dotnet\sdk\8.0.405\

(snip)

Host:
  Version:      9.0.2
  Architecture: x64
  Commit:       80aa709f5d

.NET SDKs installed:
(snip)
  8.0.405 [C:\Program Files\dotnet\sdk]
  8.0.406 [C:\Program Files\dotnet\sdk]
(snip)

Tracing logs also say that the resolver is operating with rollForward = 'patch':

set COREHOST_TRACE=1
set COREHOST_TRACE_VERBOSITY=4
dotnet --info

--- Resolving .NET SDK with working dir [C:\Temp\newdir]
Probing path [C:\Temp\newdir\global.json] for global.json
Found global.json [C:\Temp\newdir\global.json]
--- Resolving SDK information from global.json [C:\Temp\newdir\global.json]
Value 'sdk/rollForward' is missing or null in [C:\Temp\newdir\global.json]
Value 'sdk/allowPrerelease' is missing or null in [C:\Temp\newdir\global.json]
Resolving SDKs with version = '8.0.405', rollForward = 'patch', allowPrerelease = true

Page URL

https://learn.microsoft.com/en-us/dotnet/core/tools/global-json?source=docs#rollforward

Content source URL

https://github.com/dotnet/docs/blob/main/docs/core/tools/global-json.md

Document Version Independent Id

6d80613f-42dc-35d7-aeff-3187a36dbbca

Article author

@tdykstra

Metadata

• ID: a94c335b-0b65-96cc-1c25-65777fbe4bb5
• PlatformId: 8e1f5348-e2c6-2d5e-9531-202d840f33ca
• Service: dotnet-fundamentals

Related Issues