Add breaking change documentation for NuGet packages excluded from deps.json files (#48137)

Author: Copilot

docs/core/compatibility/10.0.md

@@ -112,6 +112,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1 |
 | [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md) | Behavioral change | Preview 1 |
 | [NU1510 is raised for direct references pruned by NuGet](sdk/10.0/nu1510-pruned-references.md) | Source incompatible | Preview 1 |
+| [NuGet packages with no runtime assets aren't included in deps.json](sdk/10.0/deps-json-trimmed-packages.md) | Source incompatible | Preview 5 |
 | [PackageReference without a version raises an error](sdk/10.0/nu1015-packagereference-version.md) | Behavioral change | Preview 6 |
 | [PrunePackageReference marks direct prunable references with PrivateAssets=all and IncludeAssets=none](sdk/10.0/prune-packagereference-privateassets.md) | Behavioral change | Preview 7 |
 | [HTTP warnings promoted to errors in `dotnet package list` and `dotnet package search`](sdk/10.0/http-warnings-to-errors.md) | Behavioral/source incompatible change | Preview 4 |

docs/core/compatibility/sdk/10.0/deps-json-trimmed-packages.md

@@ -0,0 +1,51 @@
+---
+title: "Breaking change: NuGet packages with no runtime assets aren't included in deps.json"
+description: "Learn about the breaking change in .NET 10 where NuGet packages that don't contribute runtime assets might be excluded from deps.json files."
+ms.date: 08/27/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/48132
+---
+# NuGet packages with no runtime assets aren't included in deps.json
+
+NuGet packages or other libraries that don't contribute any runtime assets are now excluded from the deps.json file if removing them wouldn't cause dependency resolution issues.
+
+## Version introduced
+
+.NET 10 Preview 5
+
+## Previous behavior
+
+Previously, all referenced NuGet packages and projects were included in the deps.json file as library entries, even if there were no assets used from them.
+
+## New behavior
+
+NuGet packages or other libraries might be excluded from the deps.json file if:
+
+- They don't contribute any runtime assets, and
+- Removing the library from the deps.json would not cause any libraries that do contribute runtime assets to no longer have a dependency path to them.
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+The deps.json file lists runtime dependencies and is used by the loader to load those dependencies. Some other tools also process the deps.json file. Including libraries that aren't actually used is less accurate and can lead to false positives for security scanners that use the deps.json file.
+
+## Recommended action
+
+To disable the new behavior, set the `TrimDepsJsonLibrariesWithoutAssets` MSBuild property to `false`:
+
+```xml
+<PropertyGroup>
+  <TrimDepsJsonLibrariesWithoutAssets>false</TrimDepsJsonLibrariesWithoutAssets>
+</PropertyGroup>
+```
+
+## Affected APIs
+
+None.
+
+## See also
+
+- [Pruning of framework-provided package references](../../../whats-new/dotnet-10/sdk.md#pruning-of-framework-provided-package-references)

docs/core/compatibility/toc.yml

@@ -126,6 +126,8 @@ items:
                 href: sdk/10.0/msbuild-custom-culture.md
               - name: NU1510 is raised for direct references pruned by NuGet
                 href: sdk/10.0/nu1510-pruned-references.md
+              - name: NuGet packages with no runtime assets aren't included in deps.json
+                href: sdk/10.0/deps-json-trimmed-packages.md
               - name: PackageReference without a version raises error
                 href: sdk/10.0/nu1015-packagereference-version.md
               - name: PrunePackageReference marks direct prunable references with PrivateAssets=all and IncludeAssets=none
@@ -826,7 +828,7 @@ items:
                 href: core-libraries/6.0/system-drawing-common-windows-only.md
               - name: System.Security.SecurityContext is marked obsolete
                 href: core-libraries/6.0/securitycontext-obsolete.md
-              - name: Task.FromResult may return singleton
+              - name: Task.FromResult might return singleton
                 href: core-libraries/6.0/task-fromresult-returns-singleton.md
               - name: Unhandled exceptions from a BackgroundService
                 href: core-libraries/6.0/hosting-exception-handling.md