search

Azure / typespec-azure

About TypeSpec Azure Libraries
https://azure.github.io/typespec-azure/
MIT License
8 stars 29 forks source link

[tcgc] provide an API to list all supported api-versions for a SDK #965

Open chunyu3 opened 1 month ago

chunyu3 commented 1 month ago

Now when we support versioning, .NET and Java need to generate ServiceVersion in client. It may not be same as the list of api-versions in main.tsp, in released SDK, the ServiceVersion only contains stable api-versions.

The supported api-versions should follow below rules:

  1. A stable version of client library(SDK) will target the latest GA api-version by default, and only contains GA api-versions in ServiceVersion enum
  2. A public beta version(preview version) of client library will target the latest public preview API version by default. It contains all api-versions in ServiceVersion enum.

Those rules are for all languages, so it is better for TCGC to provide an API to list out all the supported Api-version for a SDK.

iscai-msft commented 4 weeks ago

We could start with a helper function that is called isStable(apiVersion: string) in tcgc, that initially only checks azure sdks based off of naming conventions. Once the typespec versioning library adds additional metadata about the stability of a defined api version, we can add those checks to the isStable function as well.

If we keep the ServiceVersion enum that tcgc returns as keeping all of the api versions, you can then use the isStable filtering function on these api version enums to determine which ones you want to generate

iscai-msft commented 4 weeks ago

@johanste for a stable release of an SDK, do we want to include preview api versions in documentation for clients?

srnagar commented 4 weeks ago

Versions in main.tsp

2020-01-01-Preview
2021-01-01
2022-01-01-Preview
2023-01-01
2024-01-01-Preview

Introduce a new API in TCGC listFilteredVersions().

Case 1

tspconfig.yaml

api-version: 2022-01-01-Preview

listFilteredVersions -> returns 

2020-01-01-Preview
2021-01-01
2022-01-01-Preview

Case 2

tspconfig.yaml

api-version: 2023-01-01

listFilteredVersions -> returns 

2021-01-01
2023-01-01

Case 3

No API version in tspconfig

listFilteredVersions -> returns 

2020-01-01-Preview
2021-01-01
2022-01-01-Preview
2023-01-01
2024-01-01-Preview