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.
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.
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 change1.
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.
We acknowledge that even in this situation it's still possible for such a change to break customer code - but we consider that in some cases, a new minor version with a breaking change is a more pragmatic alternative than a new major version. New major versions cause additional customer work, as customers should always check release notes more carefully to check for breaking changes in them. If a new major version is released when we don't expect any customers to genuinely be broken by the change, that does a disservice to all customers. ↩