.NET Support Policy

The support policy for Google .NET libraries is based on published NuGet packages, using Semantic Versioning for the NuGet package versions.

Not all Google .NET projects have adopted this policy. Consult the documentation of each project to find out what their policies are.

Supported .NET runtimes

Unless otherwise stated, Google .NET libraries do not support mobile platforms (MAUI, Xamarin, Blazor, Unity). They may work in those environments, but they aren't tested there and breakages which only occur in these environments will not be regarded as breaking changes.

Runtime support is described programmatically in terms of the Target Framework Monikers that the NuGet packages target. Note that later runtimes typically support libraries targeted at older runtimes. For example, a library which targets .NET 6.0 is also supported on .NET 7.0. Libraries which target .NET Standard are supported on any Microsoft-supported runtime which supports that version of .NET Standard. Google .NET libraries only target long-term support (LTS) versions of .NET.

Microsoft documents its support policies for .NET and .NET Framework separately; please refer to those pages for details as to what is supported at any given time.

When releasing a new version of a package:

• We support all runtime versions supported by Microsoft at the time of release.
• When releasing a new patch version, the package will support the same set of runtimes as the other patch versions in the same major/minor version.
• When releasing a new minor version, the new version may support fewer runtimes than previous minor versions in the same major version, dropping support for runtimes that have been out of support by Microsoft for a year or more.
• When releasing a new major version, runtimes that were supported in earlier versions of the same package may be dropped if they are no longer supported by Microsoft, even if that support has only recently been dropped.

Customer support and issue investigation

We will always investigate issues reported against the latest published version of a package.

When an issue is reported against an old minor version of the current major version, we will request that you first update to the latest version and reproduce the issue.

When an issue is reported against an old major version:

• If more than a year has elapsed since the first stable release of the next major version, we will request that you first update to the latest version and reproduce the issue.
• If the next major version is less than a year old, we may still suggest that you upgrade to the latest version, but will investigate issues against the older major version.

If an issue is reported against an unsupported major version (i.e. more than a year has elapsed since a later major version was released) and you are unable to update to use a supported major version, we do not guarantee to investigate the issue.

Dependency policy

Updating an existing dependency to a new patch version of the dependency (with the existing major/minor version) only requires a new patch version of the dependent package, unless we are aware that the dependency has actually violated Semantic Versioning by introducing new features (in which case a new minor version of the dependent package is required).

Updating an existing dependency to a new minor version of the dependency (with the existing major version) requires a new minor version of the dependent package. (Again, if the dependency has violated Semantic Versioning by introducing breaking changes, a new major version of the dependent package is required.)

Updating an existing dependency to a new major version of the dependency will usually require a new major version of the dependent package, unless we determine that either there are no breaking changes, or that they are so unlikely to cause customer issues that the benefits outweigh the customer cost of adopting a new major version of the dependent package.

Adding a new dependency requires a new minor version of the dependent package.

Removing a dependency requires a new minor version of the dependent package, and will always be highlighted clearly in release notes. This can break customers relying on the dependency transitively, but should normally be very easy to fix customer-side, simply by adding a direct dependency.

Semantic Versioning violations

Google .NET libraries comply with Semantic Versioning as far as is reasonably pragmatic, maintaining both source and binary compatibility within a major version.

Very occasionally, a breaking change may be included within a minor version, violating strict Semantic Versioning. We reserve the right to make breaking changes within a week of a release, where that is the most pragmatic approach and we don't expect any customers to actually be broken by the change¹.

Any breaking change like this will be called out very clearly within the release notes of the package, and we encourage any customers who are inconvenienced by the change to file issues which will be promptly investigated.