Two SDK breaking changes (dotnet#41694)

gewarren · web-flow · commit 972c4157d8bb · 2024-07-11T07:26:15.000-07:00
diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md
@@ -45,7 +45,9 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 | Title                                                                         | Type of change    | Introduced version |
 |-------------------------------------------------------------------------------|-------------------|--------------------|
 | [`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          |
+| [Warning emitted for .NET Standard 1.x](sdk/9.0/netstandard-warning.md)       | Source incompatible | Preview 6        |
 
 ## Windows Forms
 
diff --git a/docs/core/compatibility/sdk/9.0/netstandard-warning.md b/docs/core/compatibility/sdk/9.0/netstandard-warning.md
@@ -0,0 +1,63 @@
+---
+title: "Breaking change: Warning emitted for .NET Standard 1.x targets"
+description: Learn about a breaking change in the .NET 9 SDK where the a build warning is produced if your project targets any .NET Standard version below 2.0.
+ms.date: 07/09/2024
+---
+# Warning emitted for .NET Standard 1.x targets
+
+A warning is now emitted when a project that targets `netstandard1.x` is built with the .NET 9+ SDK.
+
+## Previous behavior
+
+Previously, you could build a project that targeted .NET Standard 1.0 - .NET Standard 1.6 without any build warnings.
+
+## New behavior
+
+Starting in .NET 9, if you build a project that targets .NET Standard 1.0 - .NET Standard 1.6, the following warning is emitted:
+
+> warning NETSDK1215: Targeting .NET Standard prior to 2.0 is no longer recommended. See <https://aka.ms/dotnet/dotnet-standard-guidance> for more details.
+
+## Version introduced
+
+.NET 9 Preview 6
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+The build warning was introduced to encourage customers to target .NET Standard 2.0 or .NET 6+. If you target .NET Standard 1.x, you're limiting yourself to a subset of .NET Framework 4.5, which is over 10 years old. A lot of innovation has happened since then that you're missing out on. In addition, .NET Standard 1.x is distributed as a granular set of NuGet packages, which creates a large package dependency graph and results in a lot of packages being downloaded when the project is built.
+
+For more information, see [What is the downside of targeting .NET Standard 1.x?](https://github.com/dotnet/designs/blob/main/accepted/2024/net-standard-recommendation.md#what-is-the-downside-of-targeting-net-standard-1x).
+
+## Recommended action
+
+Update your `TargetFramework` property to `netstandard2.0` or `netstandard2.1`.
+
+If you must stay on an older .NET Standard version, you can set `<CheckNotRecommendedTargetFramework>` to `false` in your project file (for example, *.csproj* file) or *Directory.Build.props* file to skip the target framework version check:
+
+```xml
+<PropertyGroup>
+  ...
+  <CheckNotRecommendedTargetFramework>false</CheckNotRecommendedTargetFramework>
+</PropertyGroup>
+```
+
+Alternatively, you can suppress the warning using the `<NoWarn>` property in your project file:
+
+```xml
+<PropertyGroup>
+  ...
+  <!-- Disable "Targeting .NET Standard prior to 2.0 is no longer recommended." warning -->
+  <NoWarn>$(NoWarn);NETSDK1215</NoWarn>
+</PropertyGroup>
+```
+
+## Affected APIs
+
+N/A
+
+## See also
+
+- [.NET Standard Targeting Recommendations](https://github.com/dotnet/designs/blob/main/accepted/2024/net-standard-recommendation.md)
diff --git a/docs/core/compatibility/sdk/9.0/productcommits-versions.md b/docs/core/compatibility/sdk/9.0/productcommits-versions.md
@@ -0,0 +1,38 @@
+---
+title: "Breaking change: `installer` repo version no longer included in `productcommits` files"
+description: Learn about a breaking change in the .NET 9 SDK where the `installer` repo commit and version are no longer included in the `productcommits` files.
+ms.date: 07/09/2024
+---
+# `installer` repo version no longer included in `productcommits` files
+
+The version and commit of a subset of the repos that comprise .NET are available in the *productcommits-rid.txt* and *.json* files. These files can be queried from aka.ms links, for example, <https://aka.ms/dotnet/9.0.1xx/daily/productCommit-win-x64.txt>. The files enable customers to get the version and commit of the `runtime`, `aspnetcore`, `windowsdesktop`, and `sdk` repos included in a given build. Some customers have built tooling around this file to help others update their repos to new versions of .NET as builds are available.
+
+In .NET 9, the `dotnet/installer` repo has been merged into the `dotnet/sdk` repo and builds are now shipped exclusively out of the `dotnet/sdk` repo.
+
+## Previous behavior
+
+Previously, the *productcommits-rid.txt* file included the `installer` repo version.
+
+## New behavior
+
+Starting in .NET 9, the `installer` line has been removed from the *productcommits-rid.txt* file.
+
+## Version introduced
+
+.NET 9 Preview 5
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The `installer` repo was removed to reduce code-flow time and complexity of builds, and to allow the team to build a full SDK out of the `sdk` repo for testing.
+
+## Recommended action
+
+Any tooling that depends on the `productcommit` file should be updated to use the `sdk` version.
+
+## Affected APIs
+
+N/A
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -38,8 +38,12 @@ items:
       items:
       - name: "'dotnet workload' commands output change"
         href: sdk/9.0/dotnet-workload-output.md
+      - name: "'installer' repo version no longer documented"
+        href: sdk/9.0/productcommits-versions.md
       - name: Terminal logger is default
         href: sdk/9.0/terminal-logger.md
+      - name: Warning emitted for .NET Standard 1.x targets
+        href: sdk/9.0/netstandard-warning.md
     - name: Windows Forms
       items:
       - name: BindingSource.SortDescriptions doesn't return null
@@ -1626,8 +1630,12 @@ items:
       items:
       - name: "'dotnet workload' commands output change"
         href: sdk/9.0/dotnet-workload-output.md
+      - name: "'installer' repo version no longer documented"
+        href: sdk/9.0/productcommits-versions.md
       - name: Terminal logger is default
         href: sdk/9.0/terminal-logger.md
+      - name: Warning emitted for .NET Standard 1.x targets
+        href: sdk/9.0/netstandard-warning.md
     - name: .NET 8
       items:
       - name: CLI console output uses UTF-8
diff --git a/docs/standard/net-standard.md b/docs/standard/net-standard.md
@@ -1,7 +1,7 @@
 ---
 title: .NET Standard
 description: Learn about .NET Standard, its versions, and the .NET implementations that support it.
-ms.date: 11/15/2023
+ms.date: 07/09/2024
 ms.service: dotnet
 ms.subservice: standard-library
 ms.custom: "updateeachrelease"
@@ -20,7 +20,10 @@ For information about choosing between .NET 5+ and .NET Standard, see [.NET 5+ a
 
 If you're targeting .NET Standard, we recommend you target .NET Standard 2.0, unless you need to support an earlier version. Most general-purpose libraries should not need APIs outside of .NET Standard 2.0, and .NET Framework doesn't support .NET Standard 2.1. .NET Standard 2.0 is supported by all modern platforms and is the recommended way to support multiple platforms with one target.
 
-If you need to support .NET Standard 1.x, we recommend that you *also* target .NET Standard 2.0. .NET Standard 1.x is distributed as a granular set of NuGet packages, which creates a large package dependency graph and results in developers downloading a lot of packages when building. For more information, see [Cross-platform targeting](library-guidance/cross-platform-targeting.md) and [.NET 5+ and .NET Standard](#net-5-and-net-standard) later in this article.
+If you need to support .NET Standard 1.x, we recommend that you *also* target .NET Standard 2.0. .NET Standard 1.x is distributed as a granular set of NuGet packages, which creates a large package dependency graph and results in a lot of packages being downloaded when the project is built. For more information, see [Cross-platform targeting](library-guidance/cross-platform-targeting.md) and [.NET 5+ and .NET Standard](#net-5-and-net-standard) later in this article.
+
+> [!NOTE]
+> Starting in .NET 9, a build warning is emitted if your project targets .NET Standard 1.x. For more information, see [Warning emitted for .NET Standard 1.x targets](../core/compatibility/sdk/9.0/netstandard-warning.md).
 
 ### .NET Standard versioning rules
 
@@ -85,7 +88,7 @@ If you only need to consume .NET Standard 2.0 libraries in your projects, you ca
 
 ## .NET 5+ and .NET Standard
 
-.NET 5, .NET 6, .NET 7, and .NET 8 are single products with a uniform set of capabilities and APIs that can be used for Windows desktop apps and cross-platform console apps, cloud services, and websites. The .NET 8 [TFMs](frameworks.md), for example, reflect this broad range of scenarios:
+.NET 5, .NET 6, .NET 7, .NET 8, and .NET 9 are single products with a uniform set of capabilities and APIs that can be used for Windows desktop apps and cross-platform console apps, cloud services, and websites. The .NET 8 [TFMs](frameworks.md), for example, reflect this broad range of scenarios:
 
 - `net8.0`
 
@@ -95,9 +98,12 @@ If you only need to consume .NET Standard 2.0 libraries in your projects, you ca
 
   This is an example of an [OS-specific TFM](frameworks.md#net-5-os-specific-tfms) that add OS-specific functionality to everything that `net8.0` refers to.
 
-### When to target net8.0 vs. netstandard
+### When to target `net8.0` vs. `netstandard`
+
+For existing code that targets .NET Standard 2.0 or later, there's no need to change the TFM to `net8.0` or a later TFM. .NET 8 implements .NET Standard 2.1 and earlier. The only reason to retarget from .NET Standard to .NET 8+ would be to gain access to more runtime features, language features, or APIs. For example, to use C# 9, you need to target .NET 5 or a later version. You can multitarget .NET 8 and .NET Standard to get access to newer features and still have your library available to other .NET implementations.
 
-For existing code that targets `netstandard`, there's no need to change the TFM to `net8.0` or a later TFM. .NET 8 implements .NET Standard 2.1 and earlier. The only reason to retarget from .NET Standard to .NET 8+ would be to gain access to more runtime features, language features, or APIs. For example, in order to use C# 9, you need to target .NET 5 or a later version. You can multitarget .NET 8 and .NET Standard to get access to newer features and still have your library available to other .NET implementations.
+> [!NOTE]
+> If your project targets .NET Standard 1.x, we recommend you retarget it to .NET Standard 2.0 or .NET 6+. For more information, see [Warning emitted for .NET Standard 1.x targets](../core/compatibility/sdk/9.0/netstandard-warning.md).
 
 Here are some guidelines for new code for .NET 5+:
 
