Azure / Azure/typespec-azure

[Design] Design for preview api-version and stable api-version

Open
#865 4 comments 0 reactions 0 assignees View on GitHub
design:needed needs-area
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

Service may have multiple preview api-versions and stable api-versions, and according to the Azure SDK Guideline, GAed/released SDK only contains stable api-versions https://azure.github.io/azure-sdk/general_design.html#service-api-versions

Now when we support versioning, .NET and Java need to generate [ServiceVersion in client](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-versioning-select-api-version). It may not be same as the list of api-versions in main.tsp, in released SDK, the `ServiceVersion` only contains stable api-versions.

we need to design preview api-version and stable api-version

1. How can we specify an api-version is preview version or GA version?
option1: we may need to define a decorator (such as @stable) to indicate the api-version is stable one, otherwise, it is preview version

2. Shall we separate preview versions and stable versions to different tsp files?
Option 1: mix preview and stable api-versions in one tsp files
we may need handle some complex scenarios which may make tsp complex.
e.g. when there are api-versions (2023-01-01-preview, 2023-03-01, 2024-01-01-preview, 2024-03-01, 2024-05-01-preview) (ordered list). There is a parameter which is add in 2024-01-01-preview (@added("2024-01-01-preview")), but in 2024-03-01 api-version it should not add this parameter, it will remove it (@removed("2024-03-01")), but the coming preview version 2024-05-01-preview is based on previous preview version, it still need this parameter, then we may need to add it back (@added("2024-05-01-preview "))
Option 2: sperate preview versions and stable versions
Define preview and stable versions in sperate tsp files, it is more clear, but it may need extra effort to migrate preview version to a stable version

Contributor guide

Open the contributing guide

Research direction

Start with the Azure SDK General Design API-version guidance and the versioning behavior described for .NET and Java ServiceVersion. Compare the mixed-version examples in main.tsp with the proposed separate TypeSpec files, then document a decided way to distinguish preview and stable versions and how released SDKs should expose only stable versions.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.