Need better versioning support for transitions between preview and stable
- Dominant language
- TypeScript
- Stars
- 27
- Forks
- 90
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 156
Description
For large RPs and expecially those using the 'workgroup' model, it is common to have frequent stable releases that do not include all the changes in the previous preview release, but for subsequent preview releases to have them. This results in frequent use of `@removed` and `@added` decorators for preview features not ready for GA at the time of a stable release.
For example, imagine an api that introduces resources in a pattern like this:
2023-01-01-preview: [A, B]
2023-02-01-preview: [A, B, C]
2023-03-01: [A, B]
2023-04-01-preview: [A, B, C, D]
In this scenario, resource C will need to add a `@removed` tag for `2023-03-01` and immediately fllow with another `@added` tag in `2023-04-01-preview`. This could happen multiple times and both adds significantly to the number of decorators and increases the chances of accidentally adding a resource that is not GA-ready to a stable api-version.
Some options for resolving this:
- introduce a mode that treats preview and stable releases somewhat separately - a versioned entity introuduced in a preview release has to be declared `stable` or explicitly added to a stable release in order to be included in a stable release.
- Introduce a new versioning mode in which versioned entities can be versioned separately, and each api-version is explicitly composed of maps of individual resources (or other versioned entities).
- Allow separate specifications to represent some versions of APIs, for example, a stable track specification and a preview track specification.
A more thorough discussion of this is here: https://teams.microsoft.com/l/message/19:906c1efbbec54dc8949ac736633e6bdf@thread.skype/1694563288523?tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&parentMessageId=1694563288523&teamName=Azure%20SDK&channelName=TypeSpec%20(Cadl)%20Discussion%20%F0%9F%90%AE&createdTime=1694563288523
Contributor guide
Assessment
This issue has not been assessed yet.