NuGet should report lifting from runtime-band to latest servicing for .NET packages

[richlander]

We've been releasing libraries under two different models for many years. We recently documented our practices. The differences between the two models is user-observable and can (and will) affect key performance and compliance metrics that users (and we) care about. We need to provide users with diagnostic information so that they understand the impact of their actions (when they add/update a PackageRef). In many cases, it is difficult and impractical for the user to determine the impact on their own. It's logically similar in difficulty to getting a user to realize that there is a CVE in a package w/o the E2E audit experience we recently provided.

We also need to write new guidance. What should a library provider (for example, OpenTelemetry) do if they update/add a PackageRef and see this diagnostic? Let's assume they have a net8.0 library and the new PackageRef lifts them to 9.0-era libraries.

Options:

1. Back out the change
2. Keep that (singular) 9.0 reference since the functionality is needed (AKA, ignore the warning)
3. Adopt the runtime-band policy
4. Go all in and update all libraries to 9.0

At present, we don't have any guidance on this. We don't need to wait for the diagnostic to write the guidance. It's not entirely obvious what the guidance (in terms of offering a preferred option) should be. However, we know that the last option should be generally avoided since it is likely to have unintended negative consequences on users. Each lifted reference will result in apps growing in size, CVE exposure, and (as a result) additional servicing responsibility for both the library and app owners.

The primary issue with being able to define good guidance is that we need to decide what our own behavior will be, since some of our own packages lift references. I'm assuming we'll choose option 2 above. We'll see.

Related:

• [bug] targets other than net9.0 shouldn't be forced to use 9.0 dependencies open-telemetry/opentelemetry-dotnet#5973

[eerhardt]

Examples of packages that lift shared framework dependencies out of the LTS runtime:

• https://www.nuget.org/packages/Microsoft.Extensions.AI/ (depends on System.Text.Json >= 9.0.1 on net8)
  • This requires a new feature in System.Text.Json 9 - AllowMultipleValues
• https://www.nuget.org/packages/Microsoft.Extensions.Caching.Hybrid (depends on Microsoft.Extensions.Caching.Abstractions >= 9.0.1)
  • This requires the new abstract HybridCache class in 9.0.
• https://www.nuget.org/packages/OpenTelemetry.Api/ (depends on System.Diagnostics.DiagnosticSource >= 9.0.0 on net8)
  • This requires Activity should have AddExceptionMethod (dotnet/runtime#53641), a new API in 9.0.
  • See [bug] targets other than net9.0 shouldn't be forced to use 9.0 dependencies (open-telemetry/opentelemetry-dotnet#5973) for lots more info

[richlander]

Thanks @eerhardt. That's great context. I see those as examples of option 2 above. The next step is to start to write some guidance based on our practices.

[eerhardt]

One thing I'd like the guidance to say is that for library authors to only depend on new version of packages that have new features that you need. For example, consider a library that targets net8.0 and it needs System.Text.Json v9.0.0 because of a new feature in 9. It also references Microsoft.Extensions.Logging.Abstractions. It shouldn't lift Microsoft.Extensions.Logging.Abstractions to 9.0.0 just because it needed System.Text.Json 9.0.0. Keep using the matching "runtime-band" version for the TFM you target, if possible.

This will lesson the impact of lifting assemblies out of the shared framework, because there will be less assemblies lifted.

cc @DamianEdwards

[richlander]

Yes. That's my plan. That's what I meant by option 2 above. It's a bit poorly worded. Where do you think we should put this guidance?

[eerhardt]

Where do you think we should put this guidance?

My thinking was on

https://learn.microsoft.com/dotnet/standard/library-guidance/

[jeffkl]

Team Triage: We'll need a design spec for this feature.