Add package servicing doc #9707

richlander · 2025-01-31T00:11:27Z

No description provided.

artl93 · 2025-01-31T01:37:47Z

release-policies.md

-* The package exclusively includes implementations for out-of-support .NET versions.
-
-Nuget.org includes [version](https://www.nuget.org/packages/System.Text.Json/#versions-body-tab) and [supported framework](https://www.nuget.org/packages/System.Text.Json/#supportedframeworks-body-tab) information that can be used to determine support status for packages.
-
 ## Support requirements

 To remain supported, you must do the following:

 * Use a supported SDK


Suggest linking to the .NET landing page so that customers can see which versions are currently in support.

artl93

left a thought, but LTGM otherwise.

maddymontaquila

just the one comment and otherwise lgtm!

Documentation/policies/package-servicing.md

eerhardt · 2025-01-31T19:54:00Z

Documentation/policies/package-servicing.md

+
+Apps only ever need a package reference to one of these libraries to use a newer major version. It is more common for libraries to have a reference, particularly .NET Standard libraries.
+
+The following libraries use this servicing model:


Should we add EF Core here?

cc @AndriySvyryd @SamMonoRT

The lists are not intended to be exhaustive. However, 3-6 examples would be great. Feel free to add in more via suggestion. It seems like an exhaustive list should be provided via a different approach. Same applies to your other comments.

I wonder if instead we could have a plan to represent this state somehow in the nuget gallery?

For instance -- through the support metadata -- or by observing the release cadence. Feels like it will be hard to make an exhaustive list here.

One idea we had last week in a meeting in this area was:

Mark old package versions as "deprecated" on nuget.org. (for example, all System.Text.Json 7.0.x versions would be marked as deprecated today.)

Add tooling to let you know when you are using something is not supported any longer.

This way, you could see that the 8.x and 9.x versions were still in support. But the 7.x version isn't.

For "Latest version servicing" like .NET Aspire all 8.x versions would be marked as "deprecated".

exhaustive list

I'm not suggesting this list be exhaustive of all packages. What I am suggesting is to document the groups of packages that follow the same model. All Runtime, ASP.NET Core, EF Core follow this model. All Extensions, Aspire, ML.NET follow latest version model.

Feel free to write a doc for EF (in the EF repo) and we can link to it.

I would love for support level to be exposed via the NuGet gallery and the NuGet API/client. That's clearly the best model. That's a good idea to follow merging this PR.

@OliaG @aortiz-msft

@richlander Long thread here. Would you please summarize the ask for us and open an issue in NuGet/Home?

cc @OliaG

Ask: There should be an E2E for deprecated/unsupported packages from producer marking existing packages as such and consumers getting warnings via the gallery, VS, and the NuGet/dotnet CLI. A team like ours isn't going to use the gallery to mark our packages as deprecated. We need an API for that (we're talking to @joelverhagen about that part). I can open an issue if there isn't one on that.

NuGet/Home#13598 ?

Yes. That appears to be a match and I remember it now. Good find.

FYI: @JonDouglas

eerhardt · 2025-01-31T19:57:31Z

Documentation/policies/package-servicing.md

+
+Apps only ever need a package reference to one of these libraries to use a newer major version. It is more common for libraries to have a reference, particularly .NET Standard libraries.
+
+The following libraries use this servicing model:


Would it help to add dotnet/aspnetcore packages here as well? For example, Microsoft.AspNetCore.SignalR.Client and Microsoft.Extensions.Diagnostics.HealthChecks

Idk about HealthChecks, but SignalR.Client is not part of the shared framework, so it always requires a package reference.

(some) Asp.NET packages are a special case of per-version servicing. I think in that case you must use the version that matches the .NET Version. They don't support other frameworks (like NetStandard, NETFramework, or the oldest LTS).
Then there's the old 2.x packages which do and follow "latest" servicing.

eerhardt · 2025-01-31T19:59:08Z

Documentation/policies/package-servicing.md

+
+- [.NET Aspire](https://github.com/dotnet/aspire)
+- [ML.NET](https://github.com/dotnet/machinelearning)
+- [Maintenance-packages](https://github.com/dotnet/maintenance-packages)


It would be nice to add dotnet/extensions here as well.

See https://dotnet.microsoft.com/en-us/platform/support/policy/extensions

One recurring point of confusion is that we have Microsoft.Extensions.* packages with different support models based on the repo it comes from. For MS.Ext libraries coming from runtime and aspnetcore, it uses Runtime-band servicing. For MS.Ext libraries in dotnet/extensions, it uses "Latest version servicing".

Documentation/policies/package-servicing.md

BrennanConroy · 2025-01-31T20:08:56Z

Documentation/policies/package-servicing.md

+
+Apps only ever need a package reference to one of these libraries to use a newer major version. It is more common for libraries to have a reference, particularly .NET Standard libraries.
+
+The following libraries use this servicing model:


Idk about HealthChecks, but SignalR.Client is not part of the shared framework, so it always requires a package reference.

Documentation/policies/package-servicing.md

Co-authored-by: Eric Erhardt <[email protected]>

AndriySvyryd · 2025-01-31T21:40:14Z

Documentation/policies/package-servicing.md

+.NET packages are no longer supported when either of the following occurs:
+
+- A new patch version of the package is available.
+- The package exclusively includes implementations for out-of-support .NET versions.


Is a package still supported if one of its (transitive) dependencies is not?

@GrabYourPitchforks

I think that would be a problem for that package to fix - more like an SDL issue for that package. Not something the customer is supposed to worry about.

Co-authored-by: Rich Lander <[email protected]>

ericstj

It's a difficult topic that will always have more we can say. I think this does a good job of giving an outline without trying to explain the world.

Add package servicing doc

0554213

artl93 reviewed Jan 31, 2025

View reviewed changes

artl93 approved these changes Jan 31, 2025

View reviewed changes

Add support links

ebd73b5

maddymontaquila approved these changes Jan 31, 2025

View reviewed changes

Documentation/policies/package-servicing.md Show resolved Hide resolved

eerhardt reviewed Jan 31, 2025

View reviewed changes

BrennanConroy reviewed Jan 31, 2025

View reviewed changes

eerhardt reviewed Jan 31, 2025

View reviewed changes

Documentation/policies/package-servicing.md Outdated Show resolved Hide resolved

eerhardt reviewed Jan 31, 2025

View reviewed changes

Documentation/policies/package-servicing.md Show resolved Hide resolved

Apply suggestions from code review

74054f6

Co-authored-by: Eric Erhardt <[email protected]>

AndriySvyryd reviewed Jan 31, 2025

View reviewed changes

ericstj and others added 2 commits January 31, 2025 14:09

Update Documentation/policies/package-servicing.md

7677bb0

Co-authored-by: Rich Lander <[email protected]>

Update Documentation/policies/package-servicing.md

86271e9

Co-authored-by: Rich Lander <[email protected]>

ericstj approved these changes Jan 31, 2025

View reviewed changes

richlander merged commit b26872e into main Jan 31, 2025
2 of 4 checks passed

richlander deleted the policy branch January 31, 2025 22:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add package servicing doc #9707

Add package servicing doc #9707

richlander commented Jan 31, 2025

artl93 Jan 31, 2025

artl93 left a comment

maddymontaquila left a comment

eerhardt Jan 31, 2025

richlander Jan 31, 2025 •

edited

Loading

ericstj Jan 31, 2025

eerhardt Jan 31, 2025

eerhardt Jan 31, 2025

richlander Jan 31, 2025

aortiz-msft Feb 5, 2025

richlander Feb 5, 2025

AndriySvyryd Feb 5, 2025

richlander Feb 5, 2025

eerhardt Jan 31, 2025

BrennanConroy Jan 31, 2025

ericstj Jan 31, 2025 •

edited

Loading

eerhardt Jan 31, 2025 •

edited

Loading

BrennanConroy Jan 31, 2025

AndriySvyryd Jan 31, 2025

ericstj Jan 31, 2025

ericstj left a comment


		Apps only ever need a package reference to one of these libraries to use a newer major version. It is more common for libraries to have a reference, particularly .NET Standard libraries.

		The following libraries use this servicing model:

Add package servicing doc #9707

Add package servicing doc #9707

Conversation

richlander commented Jan 31, 2025

Choose a reason for hiding this comment

artl93 left a comment

Choose a reason for hiding this comment

maddymontaquila left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander Jan 31, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericstj Jan 31, 2025 • edited Loading

Choose a reason for hiding this comment

eerhardt Jan 31, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericstj left a comment

Choose a reason for hiding this comment

richlander Jan 31, 2025 •

edited

Loading

ericstj Jan 31, 2025 •

edited

Loading

eerhardt Jan 31, 2025 •

edited

Loading