[Design] Design for preview api-version and stable api-version
- 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
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