Document dotnet-watch breaking change (#43214)

* Document dotnet-watch breaking change * add to toc and overview page --------- Co-authored-by: Genevieve Warren <[email protected]>
dotnet · Nov 8, 2024 · 74cc073 · 74cc073
1 parent 3eaf287
commit 74cc073
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 0 deletions.
diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md
@@ -95,6 +95,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 
 | Title                                                                         | Type of change    | Introduced version |
 |-------------------------------------------------------------------------------|-------------------|--------------------|
+| [`dotnet watch` incompatible with Hot Reload for old frameworks](sdk/9.0/dotnet-watch.md) | Behavioral change | RC 1          |
 | [`dotnet workload` commands output change](sdk/9.0/dotnet-workload-output.md) | Behavioral change | Preview 1          |
 | [`installer` repo version no longer documented](sdk/9.0/productcommits-versions.md) | Behavioral change | Preview 5    |
 | [Terminal logger is default](sdk/9.0/terminal-logger.md)                      | Behavioral change | Preview 1          |

diff --git a/docs/core/compatibility/sdk/9.0/dotnet-watch.md b/docs/core/compatibility/sdk/9.0/dotnet-watch.md
@@ -0,0 +1,38 @@
+---
+title: "Breaking change: 'dotnet watch' incompatible with Hot Reload for old frameworks"
+description: Learn about a breaking change in the .NET 9 SDK where 'dotnet watch' requires disabling Hot Reload for projects targeting .NET 5 or earlier.
+ms.date: 11/08/2024
+---
+# 'dotnet watch' incompatible with Hot Reload for old frameworks
+
+.NET 9 introduces a change that requires [`dotnet watch`](../../../tools/dotnet-watch.md) to launched with Hot Reload disabled for projects targeting .NET 5 or earlier versions.
+
+## Previous behavior
+
+Previously, [`dotnet watch`](../../../tools/dotnet-watch.md) automatically disabled Hot Reload when used with projects targeting .NET 5 or earlier.
+
+## New behavior
+
+Starting in .NET 9, an error is reported when [`dotnet watch`](../../../tools/dotnet-watch.md) is launched without `--no-hot-reload` for projects targeting .NET 5 or earlier versions. The error is similar to:
+
+> Hot Reload based watching is only supported in .NET 6.0 or newer apps.
+
+## Version introduced
+
+.NET 9 RC 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The internal architecture of the `dotnet watch` tool underwent significant improvements. Preserving behavior for out-of-support .NET versions did not warrant increasing the complexity of the new implementation.
+
+## Recommended action
+
+Pass `--no-hot-reload` to `dotnet watch` on the command line, or update your project to target `net6.0` or later (using the `TargetFramework` property).
+
+## Affected APIs
+
+N/A
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -94,6 +94,8 @@ items:
                 href: networking/9.0/query-redaction-logs.md
           - name: SDK and MSBuild
             items:
+              - name: "`dotnet watch` incompatible with Hot Reload for old frameworks"
+                href: sdk/9.0/dotnet-watch.md
               - name: "'dotnet workload' commands output change"
                 href: sdk/9.0/dotnet-workload-output.md
               - name: "'installer' repo version no longer documented"
@@ -1770,6 +1772,8 @@ items:
         items:
           - name: .NET 9
             items:
+              - name: "`dotnet watch` incompatible with Hot Reload for old frameworks"
+                href: sdk/9.0/dotnet-watch.md
               - name: "'dotnet workload' commands output change"
                 href: sdk/9.0/dotnet-workload-output.md
               - name: "'installer' repo version no longer documented"