Simplify and extend breaking changes guidance (#35960)

guardrex · web-flow · commit 47a119a9410d · 2025-08-19T13:29:43.000-04:00
diff --git a/aspnetcore/fundamentals/index.md b/aspnetcore/fundamentals/index.md
@@ -290,7 +290,7 @@ For more information, see [Contribute to the ASP.NET documentation: Code snippet
 
 ## Additional resources
 
-* <xref:blazor/fundamentals/index>
+<xref:blazor/fundamentals/index>
 
 :::moniker-end
 
diff --git a/aspnetcore/migration/20_21.md b/aspnetcore/migration/20_21.md
@@ -245,6 +245,8 @@ For more information, see <xref:security/enforcing-ssl>.
 
 ## Breaking changes
 
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
 ### FileResult Range header
 
 <xref:Microsoft.AspNetCore.Mvc.FileResult> no longer processes the [Accept-Ranges](https://developer.mozilla.org/docs/Web/HTTP/Headers/Accept-Ranges) header by default. To enable the `Accept-Ranges` header, set <xref:Microsoft.AspNetCore.Mvc.FileResult.EnableRangeProcessing> to `true`.
diff --git a/aspnetcore/migration/21-to-22.md b/aspnetcore/migration/21-to-22.md
@@ -29,6 +29,10 @@ This article explains how to update an existing ASP.NET Core 2.1 project to ASP.
 
 ---
 
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
 ## Update Target Framework Moniker (TFM)
 
 Projects targeting .NET Core should use the [TFM](/dotnet/standard/frameworks) of a version greater than or equal to .NET Core 2.2. In the project file, update the `<TargetFramework>` node's inner text with `netcoreapp2.2`:
diff --git a/aspnetcore/migration/22-to-30.md b/aspnetcore/migration/22-to-30.md
@@ -1159,7 +1159,7 @@ For more information on Razor file compilation, see <xref:mvc/views/view-compila
 
 Libraries often need to support multiple versions of ASP.NET Core. Most libraries that were compiled against previous versions of ASP.NET Core should continue working without issues. The following conditions require the app to be cross-compiled:
 
-* The library relies on a feature that has a binary [breaking change](#breaking-api-changes).
+* The library relies on a feature that has a binary [breaking change](#breaking-changes).
 * The library wants to take advantage of new features in ASP.NET Core 3.0. 
 
 For example:
@@ -1228,13 +1228,14 @@ public async Task GenericCreateAndStartHost_GetTestServer()
 
 <a name="break"></a>
 
-## Breaking API changes
+## Breaking changes
 
-Review breaking changes:
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
+For more information, see the following resources:
 
 * [Complete list of breaking changes in the ASP.NET Core 3.0 release](https://github.com/aspnet/Announcements/issues?page=1&q=is%3Aissue+is%3Aopen+label%3A%22Breaking+change%22+label%3A3.0.0)
 * [Breaking API changes in Antiforgery, CORS, Diagnostics, MVC, and Routing](https://github.com/aspnet/Announcements/issues/387). This list includes breaking changes for compatibility switches.
-* For a summary of 2.2-to-3.0 breaking changes across .NET Core, ASP.NET Core, and Entity Framework Core, see [Breaking changes for migration from version 2.2 to 3.0](/dotnet/core/compatibility/2.2-3.0).
 
 ## Endpoint routing with catch-all parameter
 
diff --git a/aspnetcore/migration/30-to-31.md b/aspnetcore/migration/30-to-31.md
@@ -95,9 +95,9 @@ In the `.pubxml` file update the `TargetFramework` to 3.1:
 + <TargetFramework>netcoreapp3.1</TargetFramework>
 ```
 
-## Review breaking changes
+## Breaking changes
 
-Review 3.0-to-3.1 breaking changes across .NET Core, ASP.NET Core, and Entity Framework Core at [Breaking changes for migration from version 3.0 to 3.1](/dotnet/core/compatibility/3.0-3.1).
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
 
 ## Optional changes
 
diff --git a/aspnetcore/migration/31-to-50.md b/aspnetcore/migration/31-to-50.md
@@ -777,6 +777,6 @@ The following tutorials also explain the migration:
 * [An ASP.NET Core Web app signing-in users with the Microsoft identity platform in your organization](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-1-MyOrg#option-2-create-the-sample-from-the-command-line). See **Option 2: Create the sample from the command line**.
 * [Sign-in a user with the Microsoft identity platform in a WPF Desktop application and call an ASP.NET Core Web API](https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2/tree/master/1.%20Desktop%20app%20calls%20Web%20API#how-was-the-code-created). See **How was the code created**.
 
-## Review breaking changes
+## Breaking changes
 
-For breaking changes from .NET Core 3.1 to .NET 5, see [Breaking changes for migration from version 3.1 to 5.0](/dotnet/core/compatibility/3.1-5.0). ASP.NET Core and Entity Framework Core are also included in the list.
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/migration/31-to-60.md b/aspnetcore/migration/31-to-60.md
@@ -205,12 +205,11 @@ For more information, see [Obsoleting DatabaseErrorPage middleware (dotnet/aspne
 
 [!INCLUDE[](~/includes/appname6.md)]
 
-## Review breaking changes
+## Breaking changes
 
-See the following resources:
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
 
-* [Identity: Default Bootstrap version of UI changed](/dotnet/core/compatibility/aspnet-core/6.0/identity-bootstrap4-to-5)
-* [Breaking changes for migration from version 3.1 to 5.0](/dotnet/core/compatibility/3.1-5.0). ASP.NET Core and Entity Framework Core are also included in the list.
-* [Breaking changes for migration from .NET 5 to .NET 6](/dotnet/core/compatibility/6.0): Includes ASP.NET Core and Entity Framework Core.
-* [Announcements GitHub repository (aspnet/Announcements, `6.0.0` label)](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+label%3A6.0.0+is%3Aopen): Includes breaking and non-breaking information.
-* [Announcements GitHub repository (aspnet/Announcements, `5.0.0` label)](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+label%3A5.0.0+is%3Aopen): Includes breaking and non-breaking information.
+For more information, see the following resources:
+
+* [Announcements GitHub repository (`aspnet/Announcements`, `6.0.0` label)](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+label%3A6.0.0+is%3Aopen): Includes breaking and non-breaking information.
+* [Announcements GitHub repository (`aspnet/Announcements`, `5.0.0` label)](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+label%3A5.0.0+is%3Aopen): Includes breaking and non-breaking information.
diff --git a/aspnetcore/migration/50-to-60-samples.md b/aspnetcore/migration/50-to-60-samples.md
@@ -7,7 +7,6 @@ ms.author: wpickett
 ms.date: 10/22/2021
 uid: migration/50-to-60-samples
 ---
-
 # Code samples migrated to the new minimal hosting model in ASP.NET Core in .NET 6
 
 <!-- 
diff --git a/aspnetcore/migration/50-to-60.md b/aspnetcore/migration/50-to-60.md
@@ -330,13 +330,11 @@ public DbSet<Key> Keys { get; set; }
 
 <xref:migration/50-to-60-samples>
 
-## Review breaking changes
+## Breaking changes
 
-See the following resources:
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
 
-* [Identity: Default Bootstrap version of UI changed](/dotnet/core/compatibility/aspnet-core/6.0/identity-bootstrap4-to-5)
-* [Breaking changes for migration from version .NET 5 to .NET 6](/dotnet/core/compatibility/6.0): Includes ASP.NET Core and Entity Framework Core.
-* [Announcements GitHub repository (aspnet/Announcements, `6.0.0` label)](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+label%3A6.0.0+is%3Aopen): Includes breaking and non-breaking information.
+For more information, see [Announcements GitHub repository (`aspnet/Announcements`, `6.0.0` label)](https://github.com/aspnet/Announcements/issues?q=is%3Aissue+label%3A6.0.0+is%3Aopen): Includes breaking and non-breaking information.
 
 ## Nullable reference types (NRTs) and .NET compiler null-state static analysis
 
diff --git a/aspnetcore/migration/60-70.md b/aspnetcore/migration/60-70.md
@@ -209,6 +209,6 @@ For apps using Docker, update your *Dockerfile* `FROM` statements and scripts. U
 + docker pull mcr.microsoft.com/dotnet/aspnet:7.0
 ```
 
-## Review breaking changes
+## Breaking changes
 
-For breaking changes from .NET 6 to .NET 7, see [Breaking changes in .NET 7](/dotnet/core/compatibility/7.0). ASP.NET Core and Entity Framework Core are included in the list.
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md
@@ -638,6 +638,6 @@ For more information, see:
 * [Default ASP.NET Core port changed from 80 to 8080](/dotnet/core/compatibility/containers/8.0/aspnet-port).
 * [Specify ports only with `ASPNETCORE_HTTP_PORTS`](/aspnet/core/fundamentals/servers/kestrel/endpoints#specify-ports-only)
 
-## Review breaking changes
+## Breaking changes
 
-For breaking changes from .NET 7 to .NET 8, see [Breaking changes in .NET 8](/dotnet/core/compatibility/8.0), which includes [ASP.NET Core](/dotnet/core/compatibility/8.0#aspnet-core) and [Entity Framework Core](/dotnet/core/compatibility/8.0#entity-framework-core) sections.
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/migration/80-90.md b/aspnetcore/migration/80-90.md
@@ -114,4 +114,6 @@ For more information, see the following resources:
 
 [!INCLUDE[](~/migration/80-to-90/includes/blazor.md)]
 
-## Additional resources
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/release-notes/aspnetcore-1.1.md b/aspnetcore/release-notes/aspnetcore-1.1.md
@@ -26,7 +26,11 @@ ASP.NET Core 1.1 includes the following new features:
 
 ASP.NET Core 1.1 has more features than ASP.NET Core 1.0. In general, we recommend you use the latest version.
 
-## Additional Information
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
+## Additional resources
 
 * [ASP.NET Core 1.1.0 Release Notes](https://github.com/dotnet/aspnetcore/releases/tag/1.1.0)
 * To connect with the ASP.NET Core development team's progress and plans, tune in to the [ASP.NET Community Standup](https://live.asp.net/).
diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md
@@ -130,6 +130,6 @@ if (RedirectHttpResult.IsLocalUrl(url))
 
 Thank you [@martincostello](https://github.com/martincostello) for this contribution!
 
-## Related content
+## Breaking changes
 
-<xref:fundamentals/servers/httpsys>
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/release-notes/aspnetcore-2.0.md b/aspnetcore/release-notes/aspnetcore-2.0.md
@@ -149,7 +149,11 @@ For guidance on how to migrate ASP.NET Core 1.x applications to ASP.NET Core 2.0
 * [Migrate from ASP.NET Core 1.x to ASP.NET Core 2.0](xref:migration/1x-to-2x/index)
 * [Migrate Authentication and Identity to ASP.NET Core 2.0](xref:migration/1x-to-2x/identity-2x)
 
-## Additional Information
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
+## Additional resources
 
 For the complete list of changes, see the [ASP.NET Core 2.0 Release Notes](https://github.com/dotnet/aspnetcore/releases/tag/2.0.0).
 
diff --git a/aspnetcore/release-notes/aspnetcore-2.1.md b/aspnetcore/release-notes/aspnetcore-2.1.md
@@ -168,6 +168,10 @@ For more information, see <xref:mvc/compatibility-version>.
 
 See [Migrate from ASP.NET Core 2.0 to 2.1](xref:migration/20_21).
 
-## Additional information
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
+## Additional resources
 
 For the complete list of changes, see the [ASP.NET Core 2.1 Release Notes](https://github.com/dotnet/aspnetcore/releases/tag/2.1.0).
diff --git a/aspnetcore/release-notes/aspnetcore-2.2.md b/aspnetcore/release-notes/aspnetcore-2.2.md
@@ -109,6 +109,10 @@ In ASP.NET Core 2.2, the performance of `SocketsHttpHandler` was improved by red
 
 For more information, see [the pull request that made this improvement](https://github.com/dotnet/corefx/pull/32568).
 
-## Additional information
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
+## Additional resources
 
 For the complete list of changes, see the [ASP.NET Core 2.2 Release Notes](https://github.com/dotnet/aspnetcore/releases/tag/2.2.0).
diff --git a/aspnetcore/release-notes/aspnetcore-3.0.md b/aspnetcore/release-notes/aspnetcore-3.0.md
@@ -529,7 +529,6 @@ The most notable assemblies removed from the ASP.NET Core 3.0 shared framework a
 
 For a complete list of assemblies removed from the shared framework, see [Assemblies being removed from Microsoft.AspNetCore.App 3.0](https://github.com/dotnet/AspNetCore/issues/3755). For more information on the motivation for this change, see [Breaking changes to Microsoft.AspNetCore.App in 3.0](https://github.com/aspnet/Announcements/issues/325) and [A first look at changes coming in ASP.NET Core 3.0](https://devblogs.microsoft.com/aspnet/a-first-look-at-changes-coming-in-asp-net-core-3-0/).
 
-<!-- 
-## Additional information
-For the complete list of changes, see the [ASP.NET Core 3.0 Release Notes](WHERE IS THIS????).
--->
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/release-notes/aspnetcore-3.1.md b/aspnetcore/release-notes/aspnetcore-3.1.md
@@ -84,3 +84,7 @@ When a Blazor app isn't functioning properly during development, receiving detai
 * In production, the gold bar notifies the user that an error has occurred and recommends refreshing the browser.
 
 For more information, see <xref:blazor/fundamentals/handle-errors>.
+
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/release-notes/aspnetcore-5.0.md b/aspnetcore/release-notes/aspnetcore-5.0.md
@@ -462,3 +462,7 @@ Log messages emitted to the console are JSON formatted:
   }
 }
 ```
+
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/release-notes/aspnetcore-6.0.md b/aspnetcore/release-notes/aspnetcore-6.0.md
@@ -702,6 +702,10 @@ In such scenarios, enable shadow copying by customizing the ASP.NET Core module
 
 Shadow copying in IIS is an experimental feature that is not guaranteed to be part of ASP.NET Core. Please leave feedback on IIS Shadow copying in [this GitHub issue](https://github.com/dotnet/AspNetCore.Docs/issues/23733).
 
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
 ## Additional resources
 
 * <xref:migration/50-to-60-samples>
diff --git a/aspnetcore/release-notes/aspnetcore-7.0.md b/aspnetcore/release-notes/aspnetcore-7.0.md
@@ -700,3 +700,7 @@ The new [Request decompression middleware](xref:fundamentals/middleware/request-
 * Eliminates the need to write code to handle compressed requests.
 
 For more information, see [Request decompression middleware](xref:fundamentals/middleware/request-decompression?view=aspnetcore-7.0&preserve-view=true).
+
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
diff --git a/aspnetcore/release-notes/aspnetcore-8.0.md b/aspnetcore/release-notes/aspnetcore-8.0.md
@@ -1070,6 +1070,10 @@ For more information, see [IProblemDetailsService fallback](xref:fundamentals/mi
 ## gRPC
 -->
 
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
+
 ## Additional resources
 
 * [Announcing ASP.NET Core in .NET 8 (blog post)](https://devblogs.microsoft.com/dotnet/announcing-asp-net-core-in-dotnet-8/)
diff --git a/aspnetcore/release-notes/aspnetcore-9.0.md b/aspnetcore/release-notes/aspnetcore-9.0.md
@@ -90,3 +90,7 @@ The following sections describe miscellaneous new features.
 [!INCLUDE[](~/release-notes/aspnetcore-9/includes/trust_dev_cert_linux.md)]
 
 [!INCLUDE[](~/release-notes/aspnetcore-9/includes/updated-versions.md)]
+
+## Breaking changes
+
+Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.
