Azure / Azure/azure-rest-api-specs
The semantics of 'preview'
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 5.9k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 444
Description
Reading the fifth point in https://github.com/Azure/azure-rest-api-specs/blob/master/README.md#directory-structure ('preview' and 'stable' Folders), it's not clear what is the semantics of 'preview' considering preview directory and (version)-preview API directory.
This is amplified by the fact that (version)-preview APIs might reside under stable directory and non (version)-preview APIs might reside under preview directory with the hint of possible 'breaking changes' if not used properly.
Can you please elaborate around the semantics of 'preview' in each context with clarification around (a) stability (b) regional availability (c) breaking changes?
Contributor guide
Research direction
Start with README.md, especially the fifth point in the directory-structure section about preview and stable folders. Compare the meanings of preview directories and (version)-preview API directories, then clarify stability, regional availability, and breaking-change expectations for each context. Done means the README explains these distinctions without ambiguity.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100