Major Version Plan
Google Cloud client libraries released earlier than February 17th 2020 are incompatible with Grpc.Core.Api 2.x - which means they're incompatible with anyone trying to use the Microsoft gRPC libraries in .NET Core 3.0.
This is effectively a forcing factor for us to make a series of breaking changes, and bump the major version of all libraries. While we are making forced breaking changes, we'll take the opportunity to make a few other improvements at the same time.
The bulk of the changes will be within GAX as that's where a lot of our common code for interacting with gRPC resides, but there will be some API-specific changes too.
We plan on making the following changes:
- Upgrade the Grpc.Core dependency to the latest 2.x release.
- Remove the System.Interactive.Async dependency, replacing it with Microsoft.Bcl.AsyncInterfaces.
- Change our target platforms to .NET 4.6.1 and .NET Standard 2.0
- Revisit our retry configuration to bring it in line with gRPC "native" retry configuration.
- Remove all obsolete members from all libraries.
- Remove all retry-related members that are not generated by the new microgenerator.
- Remove method signatures in generated API classes with nullable primitive types representing optional parameters. The new overloads just use the non-nullable primitive types.
- Where individual APIs have their own copies of common resource names (such as LocationName), update them to use the common resource names instead.
Considerations around dropping .NET 4.5 support
While dropping support for .NET Standard 1.x is reasonably uncontroversial, dropping support for .NET 4.5 may have a greater impact on our customers.
The Microsoft.Bcl.AsyncInterfaces NuGet package does not support .NET 4.5, which makes it hard for us to do so. We intend to release the new libraries without .NET 4.5 support as that will be the technically-simplest approach, but we have a backup plan to reintroduce .NET 4.5 compatiblity if we absolutely have to in order to meet customer demands. If this happens, it's very likely that we'd only release individual API libraries where there's significant demand, to improve the likelihood of being able to drop .NET 4.5 in future major versions.
Timing (updated 2020-02-19)
Our tentative plan is as follows:
- Release final GAX packages for the 2.x line (2.10.0)
- Change "master" branch in GAX to be the next-major-version
- Update GAX target frameworks
- Update GAX dependencies, rewriting code where necessary
- Remove obsolete members in GAX
- Change retry representation in GAX
- Create next-major-version branch in google-cloud-dotnet
- Create next-major-version branch in the generator
- Update all dependencies to GAX 3.0 (fetched locally for build)
- Migrate API libraries to GAX 3.0
- Create "expected final for this major version" releases for all APIs. (We still expect to release a few more as we go, but on a case-by-case basis.)
- Migrate all APIs to the microgenerator
- Check any remaining obsolete members and resource names, e.g. where LocationName doesn't use GAX.
- Release GAX 3.0.0-beta01 and beta libraries for all APIs targeting it
- (Waiting for feedback)
- Release further betas based on feedback, although further GAX breaking changes are "expensive" (in terms of releasing all new libraries targeting those changes)
- Release GAX 3.0.0 and new API betas targeting it
- Hoping for early to mid March 2020, depending on feedback
- Release API stable packages (for stable APIs) late March, depending on feedback
We welcome feedback on this plan. Please raise an issue to let us know how this plan will affect you.