Add guidance for .NET library dependency versions

[ericstj]

This is first draft. I might be assuming too much familiarity with the problem space. Please provide feedback 🤝

---

Internal previews

📄 File	🔗 Preview link
docs/standard/library-guidance/dependencies-net.md	docs/standard/library-guidance/dependencies-net

[Copilot]

Pull Request Overview

This PR introduces comprehensive guidance for .NET library authors on selecting dependency versions when targeting multiple .NET framework versions. The document outlines three primary strategies (latest supported versions, TFM-specific versions, and branching), their tradeoffs, and provides concrete recommendations with code examples.

Key changes:

• New guidance document explaining dependency version selection strategies for .NET libraries.
• Decision matrix comparing engineering, servicing, and update friction costs across strategies.
• Code examples demonstrating each approach using System.Text.Json references.

[eerhardt]

Suggested change

	| Branching | Low | Low | High |
	| Branching | Low | High | High |

[ericstj]

No, the engineering cost of the branching solution is low. Here I use "engineering" to mean steady-state engineering cost in main and I contrast that with "servicing cost". Let me know if you can think of a better term to use.

[eerhardt]

I'm wondering if we should even give this option. What is an example of a library that would follow this? Where they basically only add new functionality to the latest TFM support? Are there any examples outside of the .NET Team?

[ericstj]

This is the option for any product that leverages branches to control risk. I do think it's important to call this out, since it does relate to plenty of folks asking these questions, and shows customers how we solve this problem. It's also a fine compromise, since it can be done after the fact for an on-demand release (eg: a security bug, for instance).

I can run a scan of nuget to see which packages use branching like this.

[ericstj]

In the top 100 non-microsoft packages, the following use branches to manage risk, determined by observing lower major versions published after higher major versions.

AWSSDK.Core
Castle.Core
Moq
AutoMapper
FluentValidation
Npgsql
FluentAssertions
NUnit
NLog
AWSSDK.S3
RabbitMQ.Client
FluentValidation.DependencyInjectionExtensions
Npgsql.EntityFrameworkCore.PostgreSQL
Elasticsearch.Net
AWSSDK.SecurityToken
FluentValidation.AspNetCore
NodaTime
jQuery
MessagePack
AWSSDK.SQS

[eerhardt]

That query seems inconsistent with the definition of "Option 3: Branching"

but branch your library in sync with target frameworks. This is the same as Option 1, but each time a new framework is added, a new major version / branch is created to allow for updating the major version of dependencies and adding the new target framework.

The only packages in your list that I know does that are the 2 Npgsql ones.

[ericstj]

Right, but folks can be familiar with branching a general strategy, just because they don't use it precisely the way described doesn't mean it's a foreign idea.

It's also important to understand that it's how all the .NET libraries deal with this problem, and what characteristics that creates.

Maybe I can add a note under branching that some .NET packages do this and drop support for past frameworks (to further reduce engineering cost in the current codebase) but how we DON'T recommend that folks do this in general for libraries since it requires consumers to multi-target their dependencies, while normal branching strategies just give folks the option to multi-target dependencies.

[eerhardt]

Maybe I can add a note under branching

That sounds good to me. Thanks

[stephentoub]

This list of decision impacts is only focusing on the negatives. It doesn't touch on the benefits of utilizing newer features and APIs, bug fixes, performance improvements, etc., nor on what folks need to do to work around the lack of such things, like polyfills, which can be both hard to get right (if possible to get 100% right) and require substantial amounts of code.

[ericstj]

I do cover that below, I see most of that as rolling up in "engineering cost". Let me know if you can think of another column to add here to focus on "quality" of the dependencies.