Discussion Request: Beta APIs discussion

[JonathanGiles]

This discussion is a free-form discussion on the topic of beta APIs and the wider issue of breaking changes. For the sake of this discussion, a beta API is an API that has shipped in a GA release but is annotated in some language appropriate manner to indicate it is not a final API. This discussion therefore involves the following:

• Consideration as to whether the concept of beta APIs is appropriate for the Azure SDK in general, or for each language individually. Generally in Java the concept of having beta API intermingled in a GA library feels foreign, and there is no generally-accepted tooling or marker annotations used to help developers know that they are using beta API.
• If beta APIs are considered acceptable:
  • Consideration about messaging of this concept - how to inform users what a beta API is, and their expectations around that in terms of availability or frequency with which they can be changed.
  • What tooling may prove beneficial for users to better assess their use of beta APIs (e.g. I could imagine a Maven build plugin that developers could opt in to using that would list in the build process all beta APIs being used by scanning for @Beta-annotated method calls).
  • How to reconcile our 'no breaking changes' policy against a new beta API policy.
• If beta APIs are considered to NOT be acceptable:
  • Consideration of how to enable customers, whose policies prevent them from using preview releases, to make use of APIs before they are made available in a GA release (beta or otherwise).

[lilyjma]

scheduled for 3/24

[lmazuel]

@JonathanGiles @johanste Python has the concept of "provisional API" in the stdlib that we could use FYI:
https://www.python.org/dev/peps/pep-0411/

[johanste]

Yep. Or rather, provisional packages. Which may be sufficient for our needs, but may not be quite granular enough.

[FabianMeiswinkel]

For our .Net (Cosmos DB) SDK where we ship preview feature in preview nuget-packages we have received feedback loud and clear even from internal customers like Microsoft Teams that for them it is unacceptable to consume a preview-package - because of the uncertain support story. Using a Beta/Evolving/Experimental annotation on new APIs like we currently do in our Java SDK has a much lower entry barrier for customers because it is clear that any non-annotated API is fully supported.
We are even shipping server-side features as preview (Serverless, client-side encryption, patch support) having a way to make these features accessible to customers to proactively collect their feedback is a hard business requirement for us.

[lilyjma]

Recording[MS INTERNAL ONLY]

[kushagraThapar]

Real world use cases for Beta APIs in Cosmos world:

Service-side preview features.

• Client Encryption APIs
• AAD APIs
• Change Feed Full Fidelity
• Dedicated Gateway APIs

Client-side preview features.

• Change Feed Push Model Estimator APIs.
• Distributed Throughput Controller APIs.
• CosmosPagedFlux / CosmosPagedIterable readMany APIs
• FeedRanges APIs.

[KrzysztofCwalina]

@kushagraThapar, would it be possible for you to provide some prototype APIs these features would add? The list as-is is a bit too abstract. If we had examples of APIs you'd like to add, we could have a more concrete discussion about how this APIs could be added in an out-of-band fashion, e.g. as extension methods/libraries.

[simplynaveen20]

@KrzysztofCwalina @kushagraThapar - Here is an example of breaking beta change which java have to do for encryption
Encryption .NET crew added the new variable type in the EncryptionKeyWrapMetadata constructor , which will take name of EncryptionKeyStoreProvider Azure/azure-cosmos-dotnet-v3#2283
In java we are incorporating this change in PR Azure/azure-sdk-for-java#21407

[KrzysztofCwalina]

@simplynaveen20, the .NET change could be done the following way:

1. In your OOB/beta package, add a factory method Beta.CreateEncryptionKeyWrapMetadata
2. The method calls into stable package and using internals visible to calls an internal ctor.

[simplynaveen20]

2. The method calls into stable package

We have different package directory for encryption in Java so internal ctor of Cosmos wont be visible.

[KrzysztofCwalina]

We have different package directory for encryption so internal ctor of Cosmos wont be visible.

That's why I say "using internals visible", i.e. https://docs.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.internalsvisibletoattribute?view=net-5.0

[simplynaveen20]

We have different package directory for encryption so internal ctor of Cosmos wont be visible.

That's why I say "using internals visible", i.e. https://docs.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.internalsvisibletoattribute?view=net-5.0

I think this wont be supported in Java

[KrzysztofCwalina]

I think this wont be supported in Java

Yeah, I commented on .NET solution, i.e. "the .NET change could be done the following way:"

[tg-msft]

Challenges that we're trying to address with Beta APIs:

• Maintaining two copies of the code base in our repo
• Some customers want a single version of the dependency to manage across hundreds of microservices
• Some customers don't trust anything called Preview/Beta
• Some customers have regulatory requirements to not use Preview/Beta

Things the Azure SDK should investigate (across all languages):

• Support for preprocessors across languages so it's easy to build/test multiple versions of a code base
• EngSys support for releasing GA/Preview versions of the same code base with different options for the preprocessor flag
• Work with CELA to create a Go Live/RC license for any customers who want to rely on beta APIs in production
• Add some sort of naming indicator like -rc or -golive for these packages that we can use across languages to imply something isn't -preview
• Make it easy to collect telemetry on the usage of individual Beta APIs
• Ways to mark APIs as Beta across languages to help customers understand what might be subject to change in an RC/GoLive release

The plan for existing Beta APIs in Java in the meantime:

• If an API needs a breaking change, we'll use @deprecated to tell customers to switch to the new API
• We'll keep the deprecated API for at least 1 minor release, ideally use telemetry to decide when to pull it, and talk with the larger group if we need to make a more nuanced decision
• (See also the last slide presented in the meeting)

[tg-msft]

Recording[MS INTERNAL ONLY]

[kurtzeborn]

Regarding the GA/Preview version support request, there is a .NET-specific solution that the dotnet team uses which we could adopt (details here). The Azure SDK engineering system does not require changes to support this today. However, this only solves for .NET. I'm not sure there are similar patterns available for Java, Python, or JS. I heard @JonathanGiles was researching Java-specific options in the meeting.

[johanste]

@kurtzeborn, doesn't this violate what our requirements are? Or are you just linking to the details to show how it can be implemented, not to define the support agreement around the preview features?

[kirankumarkolli]

Are preview features supported?

doesn't this violate what our requirements are?

Unsure what requirements are violated (is it go-live license) @johanste?

For cosmos: go-live license is targeted (closely collaborated) for few selected CX only. For all others all features in preview package doesn't have any guarantees. The impact radius of these feature are very limited to those CX only and they are well aware of them.

[mitchdenny]

@kirankumarkolli from a customers perspective, what can they expect from a pre-GA library which is released with a go-live license (what does it guarantee?). for example:

• No breaking API changes.
• No behavioral changes that could impact workloads that depend on the API?

The reason I ask is that I'm curious about the rationale behind releasing 1.1.0-rc.1 vs. just shipping the 1.1.0 version with the new features. If the two bullet points are true, then releasing the 1.1.0 of the client library should be fine and if a minor issue is found (which is all we should be finding post go-live/RC) then releasing a 1.1.1 hotfix should be sufficient.

If we can't guarantee no breaking API changes, or breaking behavioral changes then I would think that we've got no business marking it as an RC/go-live because it probably don't meet the customers expectations of a stable API which when the GA is released can just be used by recompiling/redeploying their solution.

[github-actions]

Hi @JonathanGiles, we deeply appreciate your input into this project. Regrettably, this issue has remained inactive for over 2 years, leading us to the decision to close it. We've implemented this policy to maintain the relevance of our issue queue and facilitate easier navigation for new contributors. If you still believe this topic requires attention, please feel free to create a new issue, referencing this one. Thank you for your understanding and ongoing support.