Azure / Azure/azure-rest-api-specs
[breaking-changes] Support "vN" version numbers
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 5.9k
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 424
Description
Going forward, a small number of specs may use the "v1/v2/..." versioning scheme (in parallel with date-based versions). If a PR changes a version like `vN`, breaking-changes should process it as follows:
1. `Swagger Breaking Changes` - Compare the old and new copies of `vN`, **as if** the new copy were a new API version (so non-breaking changes are allowed).
2. `Breaking Changes (Cross-Version)` - Compare `vN` to the latest date-based version. Should only be non-breaking changes.
## Example specs
### New
* https://github.com/Azure/azure-rest-api-specs/tree/main/specification/ai/data-plane/Azure.AI.Agents/stable
* `v1` allows non-breaking changes without a new API version
* `2025-05-01` follows normal date-based breaking changes rules
### Legacy
* https://github.com/Azure/azure-rest-api-specs/tree/main/specification/keyvault/data-plane/Microsoft.KeyVault/stable
* `7.0` - `7.6` are legacy, no more versions of this format should be added
* `2025-07-01` supercedes all number-based versions, and all future versions should use dates
Contributor guide
Assessment
This issue has not been assessed yet.