mirrors/dotnet
1
0
Fork 0
mirror of https://github.com/dotnet/core synced 2025-04-29 15:47:21 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add package servicing doc (#9707)

Browse Source 
* Add package servicing doc

* Add support links

* Apply suggestions from code review

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

* Update Documentation/policies/package-servicing.md

Co-authored-by: Rich Lander <rlander@microsoft.com>

* Update Documentation/policies/package-servicing.md

Co-authored-by: Rich Lander <rlander@microsoft.com>

---------

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>
Co-authored-by: Eric StJohn <ericstj@microsoft.com>
This commit is contained in:
Rich Lander 2025-01-31 14:26:46 -08:00 committed by GitHub
parent ba8e8b6139
commit b26872ecef
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 65 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
Documentation/policies/package-servicing.md Normal file
View File

@ -0,0 +1,60 @@
# .NET Package Servicing Model
Most packages in the .NET ecosystem support only the latest version. Many packages from the .NET team operate on this same model. A subset of our packages operate on another model where multiple version bands are supported at the same time, matching in-support runtimes, offering more flexibility to users.
Users should aim to maintain their package references to be as close to the supported version as possible. Being close to a supported version means that you have most or all security fixes and likely have no latent compatibility risk that can be present when there is a big gap between your reference and the supported version.
## Latest version servicing
The default package servicing model is “latest version”. The team publishes an updated package with a security and/or functionality fix. Users can upgrade to the new latest version to get the fix.
The following libraries use this servicing model:
- [.NET Aspire](https://github.com/dotnet/aspire)
- [.NET Platform Extensions](https://github.com/dotnet/extensions)
- [ML.NET](https://github.com/dotnet/machinelearning)
- [Maintenance-packages](https://github.com/dotnet/maintenance-packages)
## Runtime-band servicing
Some packages match a library (in name and content) in the runtime. In this case, the team publishes fixes for the library in the runtime and the package at the same time. The version numbers will match. Users can upgrade to the new latest patch version to get the fix.
Users can upgrade to the latest library version (like 8.0.x) that matches a supported runtime (like 8.0). Users can also move to the latest patch of a newer major version (like 9.0.x) provided that the runtime is still in support.
The advantage of matching versions is that the runtime library will be used in place of the package, resulting in smaller deployments and servicing being provided by the runtime. The advantage of using a newer package version is getting access to newer functionality.
It common for .NET Standard libraries to have a reference to these libraries. Libraries and app projects only need a reference if they need access to newer features in a later major version (than their target framework exposes).
The following libraries use this servicing model:
- [Microsoft.Extensions.DependencyInjection](https://www.nuget.org/packages/Microsoft.Extensions.DependencyInjection)
- [System.Text.Json](https://www.nuget.org/packages/System.Text.Json)
- [System.Diagnostics.DiagnosticSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource)
- [ASP.NET Core Packages](https://github.com/dotnet/aspnetcore)
- [Entity Framework Core Packages](https://github.com/dotnet/efcore)
## Support
Users must be on the latest patch version of the package or a runtime-band to be supported.
## Compatibility
Packages retain compatibility for supported .NET versions. A package will not drop support for a .NET version that is in support. When a .NET version goes out of support, packages released after that point may drop support for that .NET version.
Mechanically, a package can support multiple target frameworks via either of two approaches:
- Multi-targeting: A project supports and is built for multiple target frameworks, resulting in assets supporting multiple .NET versions in a NuGet package.
- Branching: A project exists and is built in multiple branches, each targeting a specific target framework and resulting multiple packages that each include a single asset supporting a specific .NET version.
The differences in these approaches are user observable and require users to adopt different patterns with package references. It's the difference between the two versioning strategies defined earlier. They are also patterns that users can adopt for themselves with their own packages.
## End of Life
.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.
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.
It is important to avoid using packages that are no longer maintained. They may be missing security patches for known vulnerabilities.

17
release-policies.md
View File

@ -2,6 +2,8 @@
The .NET team uses the following policies for [.NET releases](releases.md).
The NuGet packages that the team maintains are governed by [.NET Package Servicing](./Documentation/policies/package-servicing.md)
## Release cadence
New major .NET versions are released annually in November, at [.NET Conf](https://www.dotnetconf.net/).
@ -55,22 +57,13 @@ Additionally, customers targeting an out-of-support .NET version in their projec
6 months after a .NET version goes out of support, newer in-support .NET SDK versions are updated to produce warning [NETSDK1138: The target framework is out of support](https://learn.microsoft.com/dotnet/core/tools/sdk-errors/netsdk1138) when targeting the out-of-support version.
### Packages
[.NET packages](https://www.nuget.org/profiles/dotnetframework) are no longer supported when either of the following occurs:
* A new version of the package is available. Some packages support multiple patches versions at once, one per major version matching a supported major .NET version.
* 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
* Target a supported .NET version (via the `TargetFramework` property)
* Reference supported packages
* Use a [supported SDK](https://dotnet.microsoft.com/download)
* Target a [supported .NET version](./releases.md) (via the `TargetFramework` property)
* Reference [supported packages](./Documentation/policies/package-servicing.md)
## Operating System support