Azure / Azure/azure-rest-api-specs

[breaking-changes] Support "vN" version numbers

Open
#38,151 0 comments 0 reactions 1 assignee Claimed by @mikeharder View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.