Skip to content

Add NuGet package compatibility rules documentation#52775

Open
ericstj wants to merge 6 commits intodotnet:mainfrom
ericstj:nuget-package-compatibility-rules
Open

Add NuGet package compatibility rules documentation#52775
ericstj wants to merge 6 commits intodotnet:mainfrom
ericstj:nuget-package-compatibility-rules

Conversation

@ericstj
Copy link
Copy Markdown
Member

@ericstj ericstj commented Mar 31, 2026 •
edited by github-actions bot
Loading

Summary

Adds a new article under the library guidance section documenting the compatibility rules that NuGet packages must follow. This captures institutional knowledge from internal discussions, GitHub issues, and existing scattered documentation into a single authoritative reference.

Topics covered

  • Framework compatibility: Assemblies for compatible TFMs must be API-consistent within a package
  • Assembly compatibility: Assembly versions must never decrease; binary breaking changes have ecosystem-wide impact
  • Dependency compatibility: Avoid dropping dependencies in compatible versions; polyfill (Microsoft.BCL.*) dependency patterns
  • Assembly versioning on .NET Framework: GAC preference, binding redirects, servicing implications
  • Shared framework package versioning: Assembly version held at Major.Minor.0.0 for packages overlapping with .NET shared frameworks; conflict resolution at build time (ResolvePackageFileConflicts) and at run time (the .NET host); NuGet package pruning (.NET 9 opt-in, .NET 10 default)

Related resources

This article links to and complements existing docs:

Internal previews

📄 File 🔗 Preview link
docs/standard/library-guidance/nuget-package-compatibility-rules.md docs/standard/library-guidance/nuget-package-compatibility-rules
docs/standard/library-guidance/toc.yml docs/standard/library-guidance/toc

@ericstj
Add NuGet package compatibility rules documentation
a4078ce 
Add a new article under library guidance that documents the compatibility
rules NuGet packages must follow, covering:

- Framework compatibility and assembly consistency across TFMs
- Assembly version rules (never decrease, binary breaking changes)
- Dependency compatibility (avoiding dropped dependencies, polyfill patterns)
- Assembly versioning on .NET Framework (GAC, binding redirects)
- Special versioning policy for packages overlapping with shared frameworks
- Conflict resolution (SDK and runtime) and NuGet package pruning

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings March 31, 2026 19:34
@ericstj ericstj requested review from a team and JamesNK as code owners March 31, 2026 19:34
@dotnetrepoman dotnetrepoman bot added this to the March 2026 milestone Mar 31, 2026
Copilot AI reviewed Mar 31, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new Library Guidance article that consolidates NuGet package compatibility/versioning rules into a single reference, and wires it into the Library guidance > NuGet TOC.

Changes:

  • Add a new documentation page: nuget-package-compatibility-rules.md.
  • Add the new page to docs/standard/library-guidance/toc.yml under the NuGet section.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File Description
docs/standard/library-guidance/toc.yml Adds the new article to the NuGet subsection so it shows up in navigation.
docs/standard/library-guidance/nuget-package-compatibility-rules.md New article documenting framework, assembly, and dependency compatibility expectations for NuGet packages, plus shared-framework overlap guidance.

@ericstj
Address PR review feedback
9d080a1 
- Add ai-usage: ai-assisted to frontmatter
- Fix Microsoft.BCL.* casing to Microsoft.Bcl.* to match actual package IDs
- Replace first-person 'We recommend' with imperative voice
- Fix broken prune packages link to point to NU1510 docs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ericstj ericstj requested a review from Copilot March 31, 2026 20:01
@ericstj ericstj requested review from aortiz-msft and gewarren March 31, 2026 20:05
Copilot AI reviewed Mar 31, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

ericstj and others added 2 commits March 31, 2026 13:11
@ericstj
Link to NuGet target frameworks docs, clarify cross-TFM compatibility
d3988d7 
Explain why compatible TFM builds must present compatible API surface
at both compile time and run time, with link to NuGet target framework
selection docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ericstj
Address second round of review feedback
a521506 
- Standardize 'run time' to 'runtime' throughout
- Use 'might' instead of 'may' for possibility per docs style
- Convert full learn.microsoft.com URLs to docset-root-relative links
- Use auto-numbering (1. for all items) in ordered lists

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
gewarren
gewarren approved these changes Mar 31, 2026
View reviewed changes
@aortiz-msft aortiz-msft requested a review from nkolev92 March 31, 2026 21:38
nkolev92
nkolev92 reviewed Mar 31, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@nkolev92 nkolev92 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lots of great content here. 👏

ericstj and others added 2 commits March 31, 2026 16:59
@ericstj @gewarren @nkolev92
Apply suggestions from code review
d1691c9 
Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Co-authored-by: Nikolche Kolev <nikolev@microsoft.com>
@ericstj
Address reviewer feedback: clarify dependency dropping scope, fix str…
2816002 
…ay artifacts

- Clarify 'compatible versions' to 'compatible package versions or frameworks'
- Broaden text to explain both cross-version and cross-TFM dependency rules
- Fix 'run-time' to 'runtime'
- Remove stray list marker from package pruning section
- Trim trailing whitespace

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@gewarren gewarren mentioned this pull request Apr 1, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@nkolev92 nkolev92 nkolev92 approved these changes

@gewarren gewarren gewarren approved these changes

@JamesNK JamesNK Awaiting requested review from JamesNK JamesNK is a code owner

@aortiz-msft aortiz-msft Awaiting requested review from aortiz-msft

Assignees

@gewarren gewarren

Labels

dotnet-fundamentals/svc

Projects

None yet

Milestone

March 2026

Development

Successfully merging this pull request may close these issues.

4 participants

@ericstj @nkolev92 @gewarren