Document breaking change: dotnet CLI commands log non-command-relevant data to stderr

docs/core/compatibility/10.0.md

@@ -105,6 +105,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | Title | Type of change    | Introduced version |
 |-------|-------------------|--------------------|
 | [.NET CLI `--interactive` defaults to `true` in user scenarios](sdk/10.0/dotnet-cli-interactive.md) | Behavioral change | Preview 3 |
+| [`dotnet` CLI commands log non-command-relevant data to stderr](sdk/10.0/dotnet-cli-stderr-output.md) | Behavioral change | RC 2 |
 | [.NET tool packaging creates RuntimeIdentifier-specific tool packages](sdk/10.0/dotnet-tool-pack-publish.md) | Behavioral change | Preview 6 |
 | [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change | Preview 2 |
 | [`dotnet new sln` defaults to SLNX file format](sdk/10.0/dotnet-new-sln-slnx-default.md) | Behavioral change | RC 1 |

docs/core/compatibility/sdk/10.0/dotnet-cli-stderr-output.md

@@ -0,0 +1,65 @@
+---
+title: "Breaking change - dotnet CLI commands log non-command-relevant data to stderr"
+description: "Learn about the breaking change in .NET 10 RC 2 where some dotnet CLI commands log verbose and non-command-relevant data to stderr instead of stdout."
+ms.date: 01/24/2025
+ai-usage: ai-assisted
+ms.custom: https://dev.azure.com/msft-skilling/Content/_workitems/edit/494515
+---
+
+# dotnet CLI commands log non-command-relevant data to stderr
+
+Starting in .NET 10 RC 2, some `dotnet` CLI command output that isn't core to the command being invoked emits to `stderr` instead of `stdout`. At the time of this writing, the only change is the first-run message output, but this set will grow over time.
+
+## Version introduced
+
+.NET 10 RC 2
+
+## Previous behavior
+
+First-run messages for the `dotnet` CLI emitted to `stdout`.
+
+```bash
+dotnet build > output.txt
+# First-run messages were included in output.txt
+```
+
+## New behavior
+
+First-run messages for the `dotnet` CLI emit to `stderr`.
+
+```bash
+dotnet build > output.txt
+# First-run messages are not included in output.txt
+# They appear on the console instead
+```
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+Writing information to `stdout` that isn't directly related to the command being invoked inhibits the use of commands in scripting or noninteractive circumstances. Moving to `stderr` emission for non-primary outputs like diagnostics, verbose messages, or incidental notifications means that `stdout` remains clean for parsing or other interpretation.
+
+## Recommended action
+
+For most non-PowerShell users, this change shouldn't require any action. For PowerShell users, we recommend:
+
+- Using at least PowerShell version 7.2, where redirecting to `stderr` doesn't set PowerShell's `$Error` variable and cause PowerShell to think the previous command failed execution.
+
+If you need to capture or suppress first-run messages, you can:
+
+- Set the `DOTNET_NOLOGO` environment variable to `true` to disable the first-run message entirely.
+- Redirect `stderr` separately from `stdout` in your scripts.
+
+```bash
+# Example: Redirect stderr to a separate file
+dotnet build > output.txt 2> errors.txt
+
+# Example: Discard stderr
+dotnet build > output.txt 2>/dev/null
+```
+
+## Affected APIs
+
+None.

docs/core/compatibility/toc.yml

@@ -114,6 +114,8 @@ items:
             items:
               - name: .NET CLI `--interactive` defaults to `true` in user scenarios
                 href: sdk/10.0/dotnet-cli-interactive.md
+              - name: "`dotnet` CLI commands log non-command-relevant data to stderr"
+                href: sdk/10.0/dotnet-cli-stderr-output.md
               - name: .NET tool packaging creates RuntimeIdentifier-specific tool packages
                 href: sdk/10.0/dotnet-tool-pack-publish.md
               - name: "`dotnet restore` audits transitive packages"

docs/core/tools/telemetry.md

@@ -45,6 +45,9 @@ Read more about .NET CLI Tools telemetry: https://aka.ms/dotnet-cli-telemetry
 
 To disable this message and the .NET welcome message, set the `DOTNET_NOLOGO` environment variable to `true`. Note that this variable has no effect on telemetry opt out.
 
+> [!NOTE]
+> Starting in .NET 10 RC 2, the first-run message emits to `stderr` instead of `stdout`. This change ensures that `stdout` remains clean for parsing and interpretation when using CLI commands in scripts or noninteractive scenarios. For more information, see [dotnet CLI commands log non-command-relevant data to stderr](../compatibility/sdk/10.0/dotnet-cli-stderr-output.md).
+
 ## Data points
 
 The telemetry feature doesn't collect personal data, such as usernames or email addresses. It doesn't scan your code and doesn't extract project-level data, such as name, repository, or author. It doesn't extract the contents of any data files accessed or created by your apps, dumps of any memory occupied by your apps' objects, or the contents of the clipboard. The data is sent securely to Microsoft servers using [Azure Monitor](https://azure.microsoft.com/services/monitor/) technology, held under restricted access, and published under strict security controls from secure [Azure Storage](https://azure.microsoft.com/services/storage/) systems.