Major-version roll-forward options for Core 3.0

[Thraka]

Major-verison roll-forward has been added as an opt-in feature in Core 3.0. This should be documented in the version roll-foward article: dotnet/core/versions/selection.md

Here is info from the design spec at https://github.com/dotnet/designs/blob/main/accepted/2019/runtime-binding.md

RollForward

RollForward specifies the roll-forward policy for an application, either as a fallback to accommodate missing a specific runtime version or as a directive to use a later version.

RollForward can have the following values:

• LatestPatch -- Roll forward to the highest patch version. This disables minor version roll forward.
• Minor -- Roll forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the LatestPatch policy is used.
• Major -- Roll forward to lowest higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the Minor policy is used.
• LatestMinor -- Roll forward to highest minor version, even if requested minor version is present.
• LatestMajor -- Roll forward to highest major and highest minor version, even if requested major is present.
• Disable -- Do not roll forward. Only bind to specified version. This policy is not recommended for general use since it disable the ability to roll-forward to the latest patches. It is only recommended for testing.

Minor is the default setting. See Configuration Precedence for more information.

In all cases except Disable the highest available patch version is selected.

Note: LatestMinor and LatestMajor are intended for component hosting scenarios, for both managed and native hosts (for example, managed COM components).

RollForward can be set in the following ways:

• Project file property: RollForward
• Runtime configuration file property: rollForward
• Environment variable: DOTNET_ROLL_FORWARD
• Command line argument: --roll-forward

edit by @mairaw: added topic details

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: ab345482-5752-6845-feee-52f0f06c620c
• Version Independent ID: 3613d4c0-be8e-c5a4-42f4-bec78ab99c75
• Content: Select which .NET version to use - .NET
• Content Source: docs/core/versions/selection.md
• Product: dotnet-core
• GitHub Login: @Thraka
• Microsoft Alias: adegeo

[sdmaclea]

This section is affected https://docs.microsoft.com/en-us/dotnet/core/versions/selection

[mairaw]

This also impacts this article https://docs.microsoft.com/en-us/dotnet/core/deploying/runtime-patch-selection, no? /cc @nguerrera

Might need to file a separate issue to break down the work if so.

[mairaw]

It would be good to prioritize this update. I'm updating the .NET Core support policy page (https://github.com/dotnet/website/pull/1782/) and I'm going to link to this article since the behavior changed over time.

[sdmaclea]

/cc @vitek-karas @richlander

[vitek-karas]

https://docs.microsoft.com/en-us/dotnet/core/versions/selection is still correct - none of the info there is wrong. The question is how much detail should it have. Note that even on 2.* there was a way to influence the roll forward behavior (RollForwardOnNoCadidateFx and similar settings) and it did support roll forward over Major versions as well. The new RollForward as described in https://github.com/dotnet/designs/blob/master/accepted/2019/runtime-binding.md adds some new functionality and improves the overall behavior to fit more scenarios. But the behavior described in the existing docs doesn't change.

We could leave it as is - basically not adding any description of how to change the default behavior. Just like it was in 2.* with no description of RollForwardOnNoCandidateFx.

Or we could write a new page which would be basically a docs rewrite of the spec in https://github.com/dotnet/designs/blob/master/accepted/2019/runtime-binding.md. And then link to that with "here are all the details including how to change the default behavior".

I don't see how https://docs.microsoft.com/en-us/dotnet/core/deploying/runtime-patch-selection is affected. It does use the same terminology (roll forward), but it is describing a different part of the system (SDK) which AFAIK didn't change behavior in 3.0.

[vitek-karas]

I think there's also a confusion. There are several parts to "roll forward":

• The SDK version selection - specifically this section: https://docs.microsoft.com/en-us/dotnet/core/versions/selection#the-sdk-uses-the-latest-installed-version. This also got changed in 3.0 and it introduced roll forward capabilities. The new design is described here: https://github.com/dotnet/designs/blob/master/accepted/2020/global-json-updates.md and the actual implementation is here: Implement roll-forward policies for .NET Core SDK resolution. core-setup#6953.
• The runtime framework version selection - specifically this section: https://docs.microsoft.com/en-us/dotnet/core/versions/selection#framework-dependent-apps-roll-forward. This is what the comment in the issue above seems to talk about. This is also what my previous comment discusses. As mentioned, it's not factually wrong - it's just omitting any info on how to change the default behavior.
• The version selection during dotnet publish when publishing self-contained apps - specifically this section: https://docs.microsoft.com/en-us/dotnet/core/versions/selection#framework-dependent-apps-roll-forward. This is discussed in detail in https://docs.microsoft.com/en-us/dotnet/core/deploying/runtime-patch-selection. As mentioned in my previous comment - this didn't change in 3.0 AFAIK.

[richlander]

I agree with Vitek, that the document on self-contained shouldn't be using roll-forward in the title.

[mairaw]

What would be the appropriate terminology for that @richlander?

Should I point to https://github.com/dotnet/designs/blob/master/accepted/2019/runtime-binding.md from the support policy page while these changes are not done?

[dotnet-bot]

This issue has been closed as part of the issue backlog grooming process outlined in #22351.

That automated process may have closed some issues that should be addressed. If you think this is one of them, reopen it with a comment explaining why. Tag the @dotnet/docs team for visibility.

[agocke]

This still seems like a significant issue -- I can't find the list of RollForward options anywhere else.