Breaking Change

Author: Cam Soper

docs/core/compatibility/10.0.md

@@ -48,9 +48,10 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 
 ## SDK
 
-| Title                                                                                         | Type of change    | Introduced version |
-|-----------------------------------------------------------------------------------------------|-------------------|--------------------|
-| [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1          |
+| Title                                                                                                                | Type of change    | Introduced version |
+|----------------------------------------------------------------------------------------------------------------------|-------------------|--------------------|
+| [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change | Preview 2          |
+| [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md)                        | Behavioral change | Preview 1          |
 
 ## Windows Forms
 

docs/core/compatibility/sdk/10.0/default-workload-config.md

@@ -0,0 +1,48 @@
+---
+title: "Breaking change - Change default workload configuration from 'loose manifests' to 'workload sets' mode"
+description: "Learn about the breaking change in .NET 10 Preview 2 where the default workload update mode changed."
+ms.date: 3/11/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/45000
+---
+
+# Change default workload configuration from 'loose manifests' to 'workload sets' mode
+
+In .NET 10 Preview 2, the default workload update mode changed from "manifests" to "workload-set". This change ensures users use a single, coherent set of workload versions that do not individually float, making it easier to maintain consistency and manage workloads.
+
+## Version introduced
+
+.NET 10 Preview 2
+
+## Previous behavior
+
+Previously, workloads operated in 'loose manifest' mode by default. Errant `dotnet workload update` commands could install new versions that might not work well together, making it difficult for users to keep a consistent set of workload versions aligned.
+
+## New behavior
+
+Workloads will never float unless the user:
+
+* Updates their SDK
+* Performs an explicit update command
+
+When a user performs an update, all workloads will use known-matching versions from the workload set that is used.
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+Users requested more control and predictability in workload management. This new system allows for pinning and coherent updates, ensuring a consistent set of workload versions.
+
+## Recommended action
+
+No corrective action is necessary. If users experience issues, they can revert to loose manifest mode by running the following command:
+
+```dotnetcli
+dotnet workload config --update-mode manifests
+```
+
+## Affected APIs
+
+None.

docs/core/compatibility/toc.yml

@@ -40,6 +40,8 @@ items:
                 href: globalization/10.0/version-override.md
           - name: SDK and MSBuild
             items:
+              - name: Default workload configuration from 'loose manifests' to 'workload sets' mode
+                href: sdk/10.0/default-workload-config.md
               - name: MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed
                 href: sdk/10.0/custom-build-event-warning.md
           - name: Windows Forms
@@ -1894,6 +1896,8 @@ items:
         items:
           - name: .NET 10
             items:
+              - name: Default workload configuration from 'loose manifests' to 'workload sets' mode
+                href: sdk/10.0/default-workload-config.md
               - name: MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed
                 href: sdk/10.0/custom-build-event-warning.md
           - name: .NET 9