From 642afa6959737eb18f390b58772e339f1bb6ee51 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 20 Jan 2026 13:11:01 -0800 Subject: [PATCH 01/17] First set of versioning documentation --- .../ARM/versioning/01-about-versioning.md | 31 +++++ .../versioning/02-preview-after-preview.md | 64 ++++++++++ .../ARM/versioning/03-stable-after-preview.md | 117 ++++++++++++++++++ .../ARM/versioning/04-preview-after-stable.md | 44 +++++++ .../ARM/versioning/05-stable-after-stable.md | 44 +++++++ .../ARM/versioning/06-converting-specs.md | 3 + .../ARM/versioning/07-perpetual-preview.md | 0 7 files changed, 303 insertions(+) create mode 100644 website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md create mode 100644 website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md create mode 100644 website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md create mode 100644 website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md create mode 100644 website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md create mode 100644 website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md create mode 100644 website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md b/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md new file mode 100644 index 0000000000..22be66ddb3 --- /dev/null +++ b/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md @@ -0,0 +1,31 @@ +--- +title: About Versioning in the azure-rest-api-specs Repository +--- + +TypeSpec uses a versioning library that models the changes in each new version of the API, rather than having a separate api description for each api-version. +This works well when APIs evolve according to versioning guidelines, without breaking changes. For the most part, this means that this system is very good at +modeling differences between stable api-versions for Azure APIs, but can be cumbersome when describing differences between preview APIs. + +Additionally, in Azure. preview APIs have a limited lifespan and limited support in SDKs and other tooling. For this reason and others, specs should only have a _signle active preview_ at any point during the spec development process. + +At the same time, Azure ResourceManager teams may need to maintain OpenAPI files for preview versions until they are retired, some reasons for this include: + +- RPaaS live validation support +- ARM registration support + +This document describes how to evolve APIs according to this guidelines, and how to meet both the single active preview guideline and the need to maintain some preview version in Swagger in some situations, focusing on authoring of new APIs: + +- [How to add a new preview version when the last version is preview](./02-preview-after-preview.md) +- [How to add a new stable version when the last version was preview](./03-stable-after-preview.md) +- [How to add a new preview version when the last version was stable](./04-preview-after-stable.md) +- [How to add a new stable version when the last version was stable](./05-stable-after-stable.md) + +This document also describes how to move an existing multi-api typespec spec with multiple previews: + +- [How to convert a spec with multiple preview versions into a spec with a single active preview](./06-converting-specs.md) + +Additionally, there are some services that may have features that remain in preview after a stable version is released. The recommended way to handle +this scenario is to model your ResourceProvider as multiple services, so they can version independently. For some older services, this is not an option, so there +is specialized guidance on how to maintain preview features over stable api releases: + +- [How to manage a single active preview if your service always has some features in preview](./07-perpetual-preview.md) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md new file mode 100644 index 0000000000..03e82cc681 --- /dev/null +++ b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md @@ -0,0 +1,64 @@ +--- +title: Adding a Preview Version when the Last Version was a Preview +--- + +When the previous version of your TypeSpec spec is a preview, adding a new preview version is simply replacing the latest preview version with a new preview version. +This includes: + +## Making Changes to your TypeSpec spec + +- Rename the latest preview version to match the new preview version, in all instances in the spec + - In vscode, highlight the version name and select `rename symbol` from the context menu to rename the version througholut your spec + - In any editor, search and replace the latest preview version in the spec with the new preview version +- Update the version value of this version to match the new api-version string +- Update any version documentation to use the new version +- Change the name of the `examples` version folder for the latest preview to match the new preview version +- Make changes to the API description based on how the API has changed + - If any type that was introduced in the latest preview is _not_ in the new preview, simply remove the type + - If any other types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version + - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator +- Add and modify examples to match the api changes + +## Preparing a PR into the azure-rest-api-specs repo + +- Navigate to the root directory of the repo in your local fork or clone + + ```bash + C:\repos\azure-rest-api-specs\specifications\myRp > cd \repos\azure-rest-api-specs + C:\repos\azure-rest-api-specs > + ``` + +- Pull the latest version from the repo + + ```bash + C:\repos\azure-rest-api-specs > git fetch upstream main + C:\repos\azure-rest-api-specs > git pull upstream main + ``` + +- Reinstall dependencies + + ```bash + C:\repos\azure-rest-api-specs > npm install + ``` + +- Rename any examples folder for the preview api-version to match the new api-version + + ```bash + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\examples + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\examples > mv 2025-12-01-preview 2026-01-15-preview + ``` + +- Compile your spec + + ```bash + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\examples > cd .. + C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + ``` + +- If you _don't_ need the older preview version, remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. + + ```bash + C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > rm -r 2025-12-01-preview + ``` + +- If you _do_ need the older preview version, update README.md to include a new entry for the new preview version. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md new file mode 100644 index 0000000000..1ccba2ba90 --- /dev/null +++ b/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md @@ -0,0 +1,117 @@ +--- +title: Adding a Stable Version when the Last Version was a Preview +--- + +When the previous version of your TypeSpec spec is a preview, adding a new stable version means + +This includes: + +## Making Changes to your TypeSpec spec + +- Add a new entry tpo the versions enum for the new stable version +- Update any version documentation to use the new version +- Change the name of the `examples` version folder for the latest preview to match the new stable version +- Determine which type changes from the latest preview are now stable + - Update the versioning decorators for those changes to reference the new stable version + - For changes in the latest preview that are _not_ in the new stable version + - For any type with an `@added` decorator, remove the type + - For any property or parameter with a `@typeChangedFrom` decorator, replace the property type with the type in the second decorator argument, and then remove the decorator, for example + + ```tsp + @typeChangedFrom(Versions.2025-12-01-preview, string) + property: int32; + ``` + + should be changed to: + + ```tsp + property: string; + ``` + + - For any operation with an `@returnTypeChangedFrom` decorator, replace the return type with the type in the second decorator argument and then remove the decorator, for example: + + ```tsp + @returnTypeChangedFrom(Versions.2025-12-01-preview, void) + move is ArmResourceActionSync(Widget, MoveOptions, MoveResult); + ``` + + should be changed to: + + ```tsp + move is ArmResourceActionSync(Widget, MoveOptions, void); + ``` + + - For any type with an `@renamedFrom` decorator, replace the name of the type with the second argument in the decorator and remove the decorator, for example: + + ```tsp + @renamedFrom(Versions.2025-12-01-preview, "oldProperty") + newProperty: int32; + ``` + + should be changed to: + + ```tsp + oldProperty: int32; + ``` + + - For any property or parameter with a `@madeOptional` decorator, remove the decorator, and make the property required, for example: + + ```tsp + @madeOptional(Versions.2025-12-01-preview) + property?: int32; + ``` + + should be changed to: + + ```tsp + property: int32; + ``` + + - For any type with an `@removed` decorator, remove the decorator + +- Model any additional changes in the new stable version and mark with the appropriate versioning decorator, referencing the new stable version +- Add and modify examples to match the api changes in the new stable version + +## Preparing a PR into the azure-rest-api-specs repo + +- Navigate to the root directory of the repo in your local fork or clone + + ```bash + C:\repos\azure-rest-api-specs\specifications\myRp > cd \repos\azure-rest-api-specs + C:\repos\azure-rest-api-specs > + ``` + +- Pull the latest version from the repo + + ```bash + C:\repos\azure-rest-api-specs > git fetch upstream main + C:\repos\azure-rest-api-specs > git pull upstream main + ``` + +- Reinstall dependencies + + ```bash + C:\repos\azure-rest-api-specs > npm install + ``` + +- Rename any examples folder for the preview api-version to match the new api-version + + ```bash + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\examples + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\examples > mv 2025-12-01-preview 2026-01-15-preview + ``` + +- Compile your spec + + ```bash + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\examples > cd .. + C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + ``` + +- If you _don't_ need the older preview version, remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. + + ```bash + C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > rm -r 2025-12-01-preview + ``` + +- If you _do_ need the older preview version, update README.md to include a new entry for the new stable version. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md b/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md new file mode 100644 index 0000000000..c5eea0c025 --- /dev/null +++ b/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md @@ -0,0 +1,44 @@ +--- +title: Adding a Preview Version when the Last Version was a Stable Version +--- + +When the previous version of your TypeSpec spec is a stable version, adding a new preview version is simply adding any new types and operations in the new preview and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../versioning.md). + +## Making Changes to your TypeSpec spec + +- Add a new version to the `Versions` enum in your spec for the new preview. +- Make changes to the API description based on how the API has changed + - If any types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version + - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator +- Create a new examples folder for the new version `examples\` and populate it with examples. + +## Preparing a PR into the azure-rest-api-specs repo + +- Navigate to the root directory of the repo in your local fork or clone + + ```bash + C:\repos\azure-rest-api-specs\specifications\myRp > cd \repos\azure-rest-api-specs + C:\repos\azure-rest-api-specs > + ``` + +- Pull the latest version from the repo + + ```bash + C:\repos\azure-rest-api-specs > git fetch upstream main + C:\repos\azure-rest-api-specs > git pull upstream main + ``` + +- Reinstall dependencies + + ```bash + C:\repos\azure-rest-api-specs > npm install + ``` + +- Compile your spec + + ```bash + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + ``` + + - Update README.md to include a new entry for the new preview version. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md b/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md new file mode 100644 index 0000000000..f130667b50 --- /dev/null +++ b/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md @@ -0,0 +1,44 @@ +--- +title: Adding a Stable Version when the Last Version was a Stable Version +--- + +When the previous version of your TypeSpec spec is a stable version, adding a new stable version is simply adding any new types and operations in the new stable and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../versioning.md). + +## Making Changes to your TypeSpec spec + +- Add a new version to the `Versions` enum in your spec for the new stable. +- Make changes to the API description based on how the API has changed + - If any types are removed in this stable (unlikely) mark these with an `@removed` decorator referencing the new version + - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator +- Create a new examples folder for the new version `examples\` and populate it with examples. + +## Preparing a PR into the azure-rest-api-specs repo + +- Navigate to the root directory of the repo in your local fork or clone + + ```bash + C:\repos\azure-rest-api-specs\specifications\myRp > cd \repos\azure-rest-api-specs + C:\repos\azure-rest-api-specs > + ``` + +- Pull the latest version from the repo + + ```bash + C:\repos\azure-rest-api-specs > git fetch upstream main + C:\repos\azure-rest-api-specs > git pull upstream main + ``` + +- Reinstall dependencies + + ```bash + C:\repos\azure-rest-api-specs > npm install + ``` + +- Compile your spec + + ```bash + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + ``` + + - Update README.md to include a new entry for the new stable version. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md new file mode 100644 index 0000000000..466fbabde1 --- /dev/null +++ b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md @@ -0,0 +1,3 @@ +--- +title: Converting Existing Specs with Multiple Previews +--- diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md new file mode 100644 index 0000000000..e69de29bb2 From 6b03efbe1a469299010c3c235bc415a2d18118a7 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 20 Jan 2026 17:57:12 -0800 Subject: [PATCH 02/17] Updating docs --- .../ARM/versioning/06-converting-specs.md | 92 +++++++++++++++++++ .../ARM/versioning/07-perpetual-preview.md | 3 + 2 files changed, 95 insertions(+) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md index 466fbabde1..2480cde3b4 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md @@ -1,3 +1,95 @@ --- title: Converting Existing Specs with Multiple Previews --- + +Converting a spec with multiple preview versions into a spec with a single, latest preview version is complex because the changes that occur in any +preview version are carried over into the next version by default. This means that each versioning decorator referencing a preview version must be dealt with _in order_ to end with the correct decoration. + +For each type decorated with a versioning decorator that references a preview version, follow these steps. If the type is decorated with _more than one instance_ of a versioning decorator referencing different preview versions, each of these must be processed _in version order (earliest version first)_ + +A conversion consists of the following steps, outlined in the sections below + +- Normalizing version decoration (optional) +- Handling each versioning decorator application that references a preview version +- Removing the first version (if it is a preview) +- Cleaning up (optional) + +## Normalizing Version Decoration (optional) + +Normalizing version decoration consists of removing redundant decorators and follows a few rules, described below. For these rules, consider an ordered set of versions `1...n`. + +- A decorator `@@removed(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@@removed(T, a)` with `a` in `1..n` and `a < c` unless there is a decorator `@@added(T, b)` with `b` in `1..n` and `a < b < c`. +- A decorator `@@added(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@@added(T,a)` with `a` in `1..n` and `a < c` unless there is a decorator `@@removed(T,b)` with `b` in `1..n` and `a < b < c`. +- Any duplicated application of a versioning decorator to a type with the same parameters may be safely removed, that is: + - `@@added(T, a)` and `@@added(T, a)` can be simplified to `@@added(T, a)` + - `@@removed(T, a)` and `@@removed(T, a)` can be simplified to `@@removed(T, a)` + - `@@madeOptional(T, a)` and `@@madeOptional(T, a)` can be simplified to `@@madeOptional(T, a)` + - `@@renamedFrom(T, a, name)` and `@@renamedFrom(T, a, name)` can be simplified to `@@renamedFrom(T, a, name)` + - `@@typeChangedFrom(T, a, U)` and `@@typeChangedFrom(T, a, U)` can be simplified to `@@typeChangedFrom(T, a, U)` + - `@@returnTypeChangedFrom(T, a, U)` and `@@returnTypeChangedFrom(T, a, U)` can be simplified to `@@returnTypeChangedFrom(T, a, U)` +- If `@added(T, a)` and `@removed(T,a)` occur, `@added(T, a)` may be removed. +- If any versioning decorator with 3 arguments `@@dec(T, v, a)` where `T` is a type, `v` is a version and `a` is a valid arg value occurs with another application of the same decorator `@@dec(T, v, b)` and `b != a`, then the innermost of the two decorators can be removed. + +## Handling Each Versioning Decorator That References a Preview Version + +## `@@renamedFrom(T, u, name)` decorator + +- Based on the version referenced in the decorator, determine the immediate successor version `u + 1` +- If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted +- If there is one or more `@@renamedFrom(T, u + 1, anotherName)` decorators, remove them. +- Change `@@renamedFrom(T, u, name)` to `@@renamedFrom(T, u + 1, name)` + +## `@typeChangedFrom(T, u, type)` decorator + +- Based on the version referenced in the decorator, determine the immediate successor version `u + 1` +- If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted +- If there is one or more `@typeChangedFrom` decorators referencing the immediate successor version, remove them. +- Change the version argument in the decorator to match the successor version + +## `@returnTypeChangedFrom(T, u, returnType)` decorator + +- Based on the version referenced in the decorator, determine the immediate successor version `u + 1` +- If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted +- If there is one or more `@returnTypeChangedFrom` decorators referencing the immediate successor version, remove them. +- Change the version argument in the decorator to match the successor version + +## `@madeOptional(T, u)` decorator + +- Based on the version referenced in the decorator, determine the immediate successor version `u + 1` +- If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted +- If there is one or more `@madeOptional` decorators referencing the immediate successor version, remove them. +- Change the version argument in the decorator to match the successor version + +## `@added(T, u)` decorator + +- Based on the version referenced in the decorator, determine the immediate successor version `u + 1` +- If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted +- If there is one or more `@added(T, u+ 1)` decorators referencing the immediate successor version + - Remove them. + - Change the version argument in the decorator to match the successor version [ `@added(T, u) -> @added(T, u + 1)`] +- If there is an `@removed(T, u + 1)` decorator referencing the immediate successor version + - If the type does not occur in any previous version `v < u`, remove the type altogether + - If the type does occur in a previous version, remove the `@added(T, u)` decorator. + +## `@removed(T, u)` decorator + +- Based on the version referenced in the decorator, determine the immediate successor version `u + 1` +- If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted +- If there is one or more `@removed(T, u + 1)` decorators referencing the immediate successor version + - Remove them. + - Change the version argument in the decorator to match the successor version [`@removed(T, u) -> @removed(T, u + 1)`] +- if there is one or more `@added(T, u + 1)` decorators + - Remove the `@removed(T, u)` decorator + +## Removing the _First_ version in the Specification + +TypeSpec specs require no versioning decoration for the first version of a spec, and all versioning decorators except `@removed` have no impact on the type graph for subsequent versions and can be safely removed. Any `@removed` decorator referencing the first version should be treated as follows: + +- If the decorated type _does not occur_ in any subsequent versions, it can be removed +- If the decorated type _does occur_ in subsequent versions, the version referenced in the `@removed` decorator should be updated to its immediate successor + +Note that the last version of a specification should _never_ be removed in a conversion, as if the last version is a preview, it will become the active preview. + +## Cleaning Up (optional) + +After removing the preview versions, repeat the [steps to normalize version decoration](#normalizing-version-decoration-optional) to remove redundant decoration. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md index e69de29bb2..a92cd1e4c1 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md @@ -0,0 +1,3 @@ +--- +title: Immediately Replacing a Preview Version +--- From c2f078e12cabdc3ab369bd4c85ef72c0e44d7e11 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 20 Jan 2026 18:39:12 -0800 Subject: [PATCH 03/17] Add directions for perpetual preview --- .../ARM/versioning/07-perpetual-preview.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md index a92cd1e4c1..03b9991daa 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md @@ -1,3 +1,33 @@ --- title: Immediately Replacing a Preview Version --- + +For some Resource Providers, whenever a new stable version is released, a new preview version is created, because some preview features are not ready to be stable, but may become stable in a future version. To accommodate this need and account for the limitations of breaking change checks, which require a single version change for any PR into the rest-api-specs repo, the recommended solution is to introduce a stable and subsequent preview _together_ in your TypeSPed api description and then split this change into two PRs: one representing the new stable and the second representing the subsequent preview. This involves the following steps described in the sections below: + +- If the existing preview version is A, add the new stable version A + 1 and the new preview version A + 2 to the Versions enumeration. +- For all changes from preview version `A` that are part of stable version `A + 1` + - if a new type was added in `A` and is now stable (`@@added(T, A)`), add the new decorator `@@added(T, A + 1)` + - if a type was made optional in `A` and this change is now stable (`@@madeOptional(T, A)`), add the new decorator `@@madeOptional(T, A + 1)` + - if a type was renamed in `A` and this change is now stable (`@@renamedFrom(T, A, Name)`), add the new decorator `@@typeChangedFrom(T, A + 1, Name)` + - if a property or parameter had its type changed in `A` and is now stable (`@@typeChangedFrom(T, A, U)`), add the new decorator `@@typeChangedFrom(T, A + 1, U)` + - if an operation returnType was changed in `A` and this change is now stable (`@@returnTypeChangedFrom(T, A, U)`), add the new decorator `@@returnTypeChangedFrom(T, A + 1, U)` + - If a type was removed in `A` and this change is now stable (`@@removed(T, A)`), add the new decorator `@@removed(T, A + 1)` +- Change all versioning decorators `dec(T, A, args)` to `dec(T, A + 2, args)` where `T` is a type, `A` is the latest preview version, `A + 2` is the new preview version you added in the first step and `args` are any additional arguments to the decorator. Note that, after this change, some decorators will be duplicated in version `A + 1` and version `A + 2`. This is expected. +- Remove version `A` from the versions enumeration +- Create examples directories for the two new versions and populate them with appropriate examples +- If version A _is not needed_ in the specs repo + - Remove its example folder + - Remove all references to version A in `README.md` +- Create two copies of your spec + - One which will contain just the new stable version (use this to create the first PR into the specs repo). Call this Copy 1. + - The other will contain both the new stable _and_ preview versions (use this to create the final PR after the first PR is merged). Call this Copy 2. +- Do the following with Copy 1 + - Remove version `A + 2` and all decorators that reference version `A + 2` from the spec. + - Compile the spec to produce artifacts (especially the new stable version (`A + 1`) openapi ) + - Add the new stable version (`A + 1`) to the README.md file. + - Create a and merge the PR +- Do the following with Copy 2 + - Follow the instructions for normalizing decoration in the [converting specifications](./06-converting-specs.md#normalizing-version-decoration-optional) document. This will remove any redundant decoration between the new stable and preview versions (`A + 1` and `A + 2`). + - Compile the spec to produce artifacts (especially the new stable and preview version (`A + 1` and `A + 2` ) apis). + - Copy the README.md from copy 1 and add the new preview version to the file. + - Create and merge the final PR - this copy will be your specification going forward. From b593430117a3d7ba38f87caefa910ab378ea60aa Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 20 Jan 2026 18:55:46 -0800 Subject: [PATCH 04/17] Fix misspellings --- .../docs/docs/howtos/ARM/versioning/01-about-versioning.md | 2 +- .../docs/docs/howtos/ARM/versioning/02-preview-after-preview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md b/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md index 22be66ddb3..7fb52f0be0 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md @@ -6,7 +6,7 @@ TypeSpec uses a versioning library that models the changes in each new version o This works well when APIs evolve according to versioning guidelines, without breaking changes. For the most part, this means that this system is very good at modeling differences between stable api-versions for Azure APIs, but can be cumbersome when describing differences between preview APIs. -Additionally, in Azure. preview APIs have a limited lifespan and limited support in SDKs and other tooling. For this reason and others, specs should only have a _signle active preview_ at any point during the spec development process. +Additionally, in Azure. preview APIs have a limited lifespan and limited support in SDKs and other tooling. For this reason and others, specs should only have a _single active preview_ at any point during the spec development process. At the same time, Azure ResourceManager teams may need to maintain OpenAPI files for preview versions until they are retired, some reasons for this include: diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md index 03e82cc681..09ecbee9da 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md @@ -8,7 +8,7 @@ This includes: ## Making Changes to your TypeSpec spec - Rename the latest preview version to match the new preview version, in all instances in the spec - - In vscode, highlight the version name and select `rename symbol` from the context menu to rename the version througholut your spec + - In vscode, highlight the version name and select `rename symbol` from the context menu to rename the version throughout your spec - In any editor, search and replace the latest preview version in the spec with the new preview version - Update the version value of this version to match the new api-version string - Update any version documentation to use the new version From 9b7c901b69a2f839a516327af4a5a367b14159ec Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 21 Jan 2026 16:29:29 -0800 Subject: [PATCH 05/17] Fixes to final two documents --- .../ARM/versioning/06-converting-specs.md | 38 ++++++++++--------- .../ARM/versioning/07-perpetual-preview.md | 24 +++++++++--- 2 files changed, 39 insertions(+), 23 deletions(-) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md index 2480cde3b4..4c16f2b7c7 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md @@ -14,62 +14,65 @@ A conversion consists of the following steps, outlined in the sections below - Removing the first version (if it is a preview) - Cleaning up (optional) +In this document we use the notation `@(T, u, [arg])` this indicates an instance of the decorator `` decorating type `T` using version `u` in a set of monotonically increasing versions `1..n` + ## Normalizing Version Decoration (optional) Normalizing version decoration consists of removing redundant decorators and follows a few rules, described below. For these rules, consider an ordered set of versions `1...n`. -- A decorator `@@removed(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@@removed(T, a)` with `a` in `1..n` and `a < c` unless there is a decorator `@@added(T, b)` with `b` in `1..n` and `a < b < c`. -- A decorator `@@added(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@@added(T,a)` with `a` in `1..n` and `a < c` unless there is a decorator `@@removed(T,b)` with `b` in `1..n` and `a < b < c`. +- A decorator `@removed(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@removed(T, a)` with `a` in `1..n` and `a < c` unless there is a decorator `@added(T, b)` with `b` in `1..n` and `a < b < c`. +- A decorator `@added(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@added(T,a)` with `a` in `1..n` and `a < c` unless there is a decorator `@removed(T,b)` with `b` in `1..n` and `a < b < c`. - Any duplicated application of a versioning decorator to a type with the same parameters may be safely removed, that is: - - `@@added(T, a)` and `@@added(T, a)` can be simplified to `@@added(T, a)` - - `@@removed(T, a)` and `@@removed(T, a)` can be simplified to `@@removed(T, a)` - - `@@madeOptional(T, a)` and `@@madeOptional(T, a)` can be simplified to `@@madeOptional(T, a)` - - `@@renamedFrom(T, a, name)` and `@@renamedFrom(T, a, name)` can be simplified to `@@renamedFrom(T, a, name)` - - `@@typeChangedFrom(T, a, U)` and `@@typeChangedFrom(T, a, U)` can be simplified to `@@typeChangedFrom(T, a, U)` - - `@@returnTypeChangedFrom(T, a, U)` and `@@returnTypeChangedFrom(T, a, U)` can be simplified to `@@returnTypeChangedFrom(T, a, U)` + - `@added(T, a)` and `@added(T, a)` can be simplified to `@added(T, a)` + - `@removed(T, a)` and `@removed(T, a)` can be simplified to `@removed(T, a)` + - `@madeOptional(T, a)` and `@madeOptional(T, a)` can be simplified to `@madeOptional(T, a)` + - `@renamedFrom(T, a, name)` and `@renamedFrom(T, a, name)` can be simplified to `@renamedFrom(T, a, name)` + - `@typeChangedFrom(T, a, U)` and `@typeChangedFrom(T, a, U)` can be simplified to `@typeChangedFrom(T, a, U)` + - `@returnTypeChangedFrom(T, a, U)` and `@returnTypeChangedFrom(T, a, U)` can be simplified to `@returnTypeChangedFrom(T, a, U)` - If `@added(T, a)` and `@removed(T,a)` occur, `@added(T, a)` may be removed. -- If any versioning decorator with 3 arguments `@@dec(T, v, a)` where `T` is a type, `v` is a version and `a` is a valid arg value occurs with another application of the same decorator `@@dec(T, v, b)` and `b != a`, then the innermost of the two decorators can be removed. +- If any versioning decorator with 3 arguments `@dec(T, v, a)` where `T` is a type, `v` is a version and `a` is a valid arg value occurs with another application of the same decorator `@dec(T, v, b)` and `b != a`, then the innermost of the two decorators can be removed. ## Handling Each Versioning Decorator That References a Preview Version -## `@@renamedFrom(T, u, name)` decorator +## `@renamedFrom(T, u, name)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` - If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted -- If there is one or more `@@renamedFrom(T, u + 1, anotherName)` decorators, remove them. -- Change `@@renamedFrom(T, u, name)` to `@@renamedFrom(T, u + 1, name)` +- If there is one or more `@renamedFrom(T, u + 1, anotherName)` decorators, remove them. +- Change `@renamedFrom(T, u, name)` to `@renamedFrom(T, u + 1, name)` ## `@typeChangedFrom(T, u, type)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` - If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted - If there is one or more `@typeChangedFrom` decorators referencing the immediate successor version, remove them. -- Change the version argument in the decorator to match the successor version +- Change `@typeChangedFrom(T, u, type)` to `@typeChangedFrom(T, u + 1, type)` ## `@returnTypeChangedFrom(T, u, returnType)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` - If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted - If there is one or more `@returnTypeChangedFrom` decorators referencing the immediate successor version, remove them. -- Change the version argument in the decorator to match the successor version +- Change `@returnTypeChangedFrom(T, u, returnType)` to `@returnTypeChangedFrom(T, u + 1, returnType)` ## `@madeOptional(T, u)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` - If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted - If there is one or more `@madeOptional` decorators referencing the immediate successor version, remove them. -- Change the version argument in the decorator to match the successor version +- Change `@madeOption(T, u)` to `@madeOptional(T, u + 1)` ## `@added(T, u)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` - If version `u + 1` does not exist (the version argument is the last version) then this version will not be deleted -- If there is one or more `@added(T, u+ 1)` decorators referencing the immediate successor version +- If there is one or more `@added(T, u + 1)` decorators referencing the immediate successor version - Remove them. - Change the version argument in the decorator to match the successor version [ `@added(T, u) -> @added(T, u + 1)`] - If there is an `@removed(T, u + 1)` decorator referencing the immediate successor version - If the type does not occur in any previous version `v < u`, remove the type altogether - If the type does occur in a previous version, remove the `@added(T, u)` decorator. +- If there are no `@added(T, u + 1)` or `@removed(T, u + 1)` decorators referencing the immediate successor version, change the version in the decorator to the immediate successor version: [`@added(T, u)` -> `@added(T, u + 1)`] ## `@removed(T, u)` decorator @@ -78,8 +81,9 @@ Normalizing version decoration consists of removing redundant decorators and fol - If there is one or more `@removed(T, u + 1)` decorators referencing the immediate successor version - Remove them. - Change the version argument in the decorator to match the successor version [`@removed(T, u) -> @removed(T, u + 1)`] -- if there is one or more `@added(T, u + 1)` decorators +- if there is one or more `@added(T, u + 1)` decorators in the immediate successor version - Remove the `@removed(T, u)` decorator +- If there are no `@removed(T, u + 1)` or `@removed(T, u + 1)` decorators referencing the immediate successor version, change the version in the decorator to the immediate successor version: [`@removed(T, u)` -> `@removed(T, u + 1)`] ## Removing the _First_ version in the Specification diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md index 03b9991daa..be3a418fc1 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md @@ -4,20 +4,30 @@ title: Immediately Replacing a Preview Version For some Resource Providers, whenever a new stable version is released, a new preview version is created, because some preview features are not ready to be stable, but may become stable in a future version. To accommodate this need and account for the limitations of breaking change checks, which require a single version change for any PR into the rest-api-specs repo, the recommended solution is to introduce a stable and subsequent preview _together_ in your TypeSPed api description and then split this change into two PRs: one representing the new stable and the second representing the subsequent preview. This involves the following steps described in the sections below: +- Create the new preview version based on the latest preview version +- Create the stable version (which should immediately precede the new preview version) +- Fill in examples for each +- Create a copy of the spec with just the stable release changes for your first PR +- After this PR is merged, create a PR with the whole spec, effectively adding the new preview + +## Creating New Preview and Stable Versions - If the existing preview version is A, add the new stable version A + 1 and the new preview version A + 2 to the Versions enumeration. - For all changes from preview version `A` that are part of stable version `A + 1` - - if a new type was added in `A` and is now stable (`@@added(T, A)`), add the new decorator `@@added(T, A + 1)` - - if a type was made optional in `A` and this change is now stable (`@@madeOptional(T, A)`), add the new decorator `@@madeOptional(T, A + 1)` - - if a type was renamed in `A` and this change is now stable (`@@renamedFrom(T, A, Name)`), add the new decorator `@@typeChangedFrom(T, A + 1, Name)` - - if a property or parameter had its type changed in `A` and is now stable (`@@typeChangedFrom(T, A, U)`), add the new decorator `@@typeChangedFrom(T, A + 1, U)` - - if an operation returnType was changed in `A` and this change is now stable (`@@returnTypeChangedFrom(T, A, U)`), add the new decorator `@@returnTypeChangedFrom(T, A + 1, U)` - - If a type was removed in `A` and this change is now stable (`@@removed(T, A)`), add the new decorator `@@removed(T, A + 1)` + - if a new type was added in `A` and is now stable (`@added(T, A)`), add the new decorator `@added(T, A + 1)` + - if a type was made optional in `A` and this change is now stable (`@madeOptional(T, A)`), add the new decorator `@madeOptional(T, A + 1)` + - if a type was renamed in `A` and this change is now stable (`@renamedFrom(T, A, Name)`), add the new decorator `@typeChangedFrom(T, A + 1, Name)` + - if a property or parameter had its type changed in `A` and is now stable (`@typeChangedFrom(T, A, U)`), add the new decorator `@typeChangedFrom(T, A + 1, U)` + - if an operation returnType was changed in `A` and this change is now stable (`@returnTypeChangedFrom(T, A, U)`), add the new decorator `@returnTypeChangedFrom(T, A + 1, U)` + - If a type was removed in `A` and this change is now stable (`@removed(T, A)`), add the new decorator `@removed(T, A + 1)` - Change all versioning decorators `dec(T, A, args)` to `dec(T, A + 2, args)` where `T` is a type, `A` is the latest preview version, `A + 2` is the new preview version you added in the first step and `args` are any additional arguments to the decorator. Note that, after this change, some decorators will be duplicated in version `A + 1` and version `A + 2`. This is expected. - Remove version `A` from the versions enumeration - Create examples directories for the two new versions and populate them with appropriate examples - If version A _is not needed_ in the specs repo - Remove its example folder - Remove all references to version A in `README.md` + + ## Create A Copy of the Spec for the Stable Version only + - Create two copies of your spec - One which will contain just the new stable version (use this to create the first PR into the specs repo). Call this Copy 1. - The other will contain both the new stable _and_ preview versions (use this to create the final PR after the first PR is merged). Call this Copy 2. @@ -26,6 +36,8 @@ For some Resource Providers, whenever a new stable version is released, a new pr - Compile the spec to produce artifacts (especially the new stable version (`A + 1`) openapi ) - Add the new stable version (`A + 1`) to the README.md file. - Create a and merge the PR + +## Create a PR with the Combined Spec - Do the following with Copy 2 - Follow the instructions for normalizing decoration in the [converting specifications](./06-converting-specs.md#normalizing-version-decoration-optional) document. This will remove any redundant decoration between the new stable and preview versions (`A + 1` and `A + 2`). - Compile the spec to produce artifacts (especially the new stable and preview version (`A + 1` and `A + 2` ) apis). From 6d9fd9ce050c80a606141041c30c58440a6515d2 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 21 Jan 2026 17:40:02 -0800 Subject: [PATCH 06/17] Correction and normalization --- .../ARM/versioning/01-about-versioning.md | 9 +++--- .../versioning/02-preview-after-preview.md | 19 +++++------- .../ARM/versioning/03-stable-after-preview.md | 31 +++++++------------ .../ARM/versioning/04-preview-after-stable.md | 2 +- .../ARM/versioning/05-stable-after-stable.md | 4 +-- .../ARM/versioning/06-converting-specs.md | 17 ++++++++-- .../ARM/versioning/07-perpetual-preview.md | 6 ++-- 7 files changed, 44 insertions(+), 44 deletions(-) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md b/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md index 7fb52f0be0..d64005fd61 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md @@ -13,9 +13,9 @@ At the same time, Azure ResourceManager teams may need to maintain OpenAPI files - RPaaS live validation support - ARM registration support -This document describes how to evolve APIs according to this guidelines, and how to meet both the single active preview guideline and the need to maintain some preview version in Swagger in some situations, focusing on authoring of new APIs: +This document describes how to evolve APIs according to these guidelines, and how to meet both the single active preview guideline and the need to maintain some preview versions in Swagger in some situations, focusing on authoring of new APIs: -- [How to add a new preview version when the last version is preview](./02-preview-after-preview.md) +- [How to add a new preview version when the last version was preview](./02-preview-after-preview.md) - [How to add a new stable version when the last version was preview](./03-stable-after-preview.md) - [How to add a new preview version when the last version was stable](./04-preview-after-stable.md) - [How to add a new stable version when the last version was stable](./05-stable-after-stable.md) @@ -24,8 +24,7 @@ This document also describes how to move an existing multi-api typespec spec wit - [How to convert a spec with multiple preview versions into a spec with a single active preview](./06-converting-specs.md) -Additionally, there are some services that may have features that remain in preview after a stable version is released. The recommended way to handle -this scenario is to model your ResourceProvider as multiple services, so they can version independently. For some older services, this is not an option, so there -is specialized guidance on how to maintain preview features over stable api releases: +Additionally, there are some services that may always have features that remain in preview after a stable version is released. This can happen, for example, if there are multiple independent teams that own different resources in a service and operate on their own schedule. The recommended way to handle +this scenario is to model your ResourceProvider as multiple services, so each version and the corresponding SDKs can version independently. For some older services, this is not an option, so there is specialized guidance on how to maintain preview features over stable api releases: - [How to manage a single active preview if your service always has some features in preview](./07-perpetual-preview.md) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md index 09ecbee9da..56c86ffa65 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md @@ -2,7 +2,7 @@ title: Adding a Preview Version when the Last Version was a Preview --- -When the previous version of your TypeSpec spec is a preview, adding a new preview version is simply replacing the latest preview version with a new preview version. +When the last api-version in your TypeSpec spec is a preview, adding a new preview version is simply replacing the latest preview version with a new preview version. This includes: ## Making Changes to your TypeSpec spec @@ -10,7 +10,11 @@ This includes: - Rename the latest preview version to match the new preview version, in all instances in the spec - In vscode, highlight the version name and select `rename symbol` from the context menu to rename the version throughout your spec - In any editor, search and replace the latest preview version in the spec with the new preview version -- Update the version value of this version to match the new api-version string +- Update the version value of this version to match the new api-version string, for example: + + ~~v2025_12_01_preview: "2025-12-01-preview",~~ + v2026_01_01_preview: "2026-01-01-preview", + - Update any version documentation to use the new version - Change the name of the `examples` version folder for the latest preview to match the new preview version - Make changes to the API description based on how the API has changed @@ -41,24 +45,17 @@ This includes: C:\repos\azure-rest-api-specs > npm install ``` -- Rename any examples folder for the preview api-version to match the new api-version - - ```bash - C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\examples - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\examples > mv 2025-12-01-preview 2026-01-15-preview - ``` - - Compile your spec ```bash - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\examples > cd .. + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . ``` - If you _don't_ need the older preview version, remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. ```bash - C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > rm -r 2025-12-01-preview + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > rm -r 2025-12-01-preview ``` - If you _do_ need the older preview version, update README.md to include a new entry for the new preview version. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md index 1ccba2ba90..16e36a0bb2 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md @@ -2,20 +2,20 @@ title: Adding a Stable Version when the Last Version was a Preview --- -When the previous version of your TypeSpec spec is a preview, adding a new stable version means +When the last api-version in your TypeSpec spec is a preview, adding a new stable version means -This includes: +This includes the followign steps: ## Making Changes to your TypeSpec spec -- Add a new entry tpo the versions enum for the new stable version +- Add a new entry to the versions enum for the new stable version - Update any version documentation to use the new version - Change the name of the `examples` version folder for the latest preview to match the new stable version - Determine which type changes from the latest preview are now stable - Update the versioning decorators for those changes to reference the new stable version - - For changes in the latest preview that are _not_ in the new stable version - - For any type with an `@added` decorator, remove the type - - For any property or parameter with a `@typeChangedFrom` decorator, replace the property type with the type in the second decorator argument, and then remove the decorator, for example + - For changes in the latest preview (p) that are _not_ in the new stable version + - For any type with an `@added(p)` decorator, remove the type + - For any property or parameter with a `@typeChangedFrom(p, Type)` decorator, replace the property type with the `Type` argument, and then remove the decorator, for example ```tsp @typeChangedFrom(Versions.2025-12-01-preview, string) @@ -28,7 +28,7 @@ This includes: property: string; ``` - - For any operation with an `@returnTypeChangedFrom` decorator, replace the return type with the type in the second decorator argument and then remove the decorator, for example: + - For any operation with an `@returnTypeChangedFrom(p, ReturnType)` decorator, replace the return type with the `ReturnType` argument and then remove the decorator, for example: ```tsp @returnTypeChangedFrom(Versions.2025-12-01-preview, void) @@ -41,7 +41,7 @@ This includes: move is ArmResourceActionSync(Widget, MoveOptions, void); ``` - - For any type with an `@renamedFrom` decorator, replace the name of the type with the second argument in the decorator and remove the decorator, for example: + - For any type with an `@renamedFrom(p, Name)` decorator, replace the name of the type with the `Name` argument in the decorator and remove the decorator, for example: ```tsp @renamedFrom(Versions.2025-12-01-preview, "oldProperty") @@ -54,7 +54,7 @@ This includes: oldProperty: int32; ``` - - For any property or parameter with a `@madeOptional` decorator, remove the decorator, and make the property required, for example: + - For any property or parameter with a `@madeOptional(p)` decorator, remove the decorator, and make the property required, for example: ```tsp @madeOptional(Versions.2025-12-01-preview) @@ -67,7 +67,7 @@ This includes: property: int32; ``` - - For any type with an `@removed` decorator, remove the decorator + - For any type with an `@removed(p)` decorator, remove the decorator - Model any additional changes in the new stable version and mark with the appropriate versioning decorator, referencing the new stable version - Add and modify examples to match the api changes in the new stable version @@ -94,18 +94,11 @@ This includes: C:\repos\azure-rest-api-specs > npm install ``` -- Rename any examples folder for the preview api-version to match the new api-version - - ```bash - C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\examples - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\examples > mv 2025-12-01-preview 2026-01-15-preview - ``` - - Compile your spec ```bash - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\examples > cd .. - C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . ``` - If you _don't_ need the older preview version, remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md b/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md index c5eea0c025..1ba0820d4a 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md @@ -2,7 +2,7 @@ title: Adding a Preview Version when the Last Version was a Stable Version --- -When the previous version of your TypeSpec spec is a stable version, adding a new preview version is simply adding any new types and operations in the new preview and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../versioning.md). +When the latest api-version in your TypeSpec spec is a stable version, adding a new preview version is simply adding any new types and operations in the new preview and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../versioning.md). ## Making Changes to your TypeSpec spec diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md b/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md index f130667b50..f69893aa1a 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md @@ -2,11 +2,11 @@ title: Adding a Stable Version when the Last Version was a Stable Version --- -When the previous version of your TypeSpec spec is a stable version, adding a new stable version is simply adding any new types and operations in the new stable and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../versioning.md). +When the latest api-version in your TypeSpec spec is a stable version, adding a new stable version is simply adding any new types and operations in the new stable and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../versioning.md). ## Making Changes to your TypeSpec spec -- Add a new version to the `Versions` enum in your spec for the new stable. +- Add a new version to the `Versions` enum in your spec for the new stable api-version. - Make changes to the API description based on how the API has changed - If any types are removed in this stable (unlikely) mark these with an `@removed` decorator referencing the new version - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md index 4c16f2b7c7..e61d95e9b4 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md @@ -10,8 +10,10 @@ For each type decorated with a versioning decorator that references a preview ve A conversion consists of the following steps, outlined in the sections below - Normalizing version decoration (optional) -- Handling each versioning decorator application that references a preview version +- Determining which versions should be removed: this should include all preview api-versions __except__ the last version (if the last version is a preview, that version will __not__ be removed.) +- Handling each versioning decorator application that references a deleted preview version (except the __first__ version) - Removing the first version (if it is a preview) +- Removing the deleted preview versions from the Versions enum - Cleaning up (optional) In this document we use the notation `@(T, u, [arg])` this indicates an instance of the decorator `` decorating type `T` using version `u` in a set of monotonically increasing versions `1..n` @@ -20,8 +22,8 @@ In this document we use the notation `@(T, u, [arg])` this indicates Normalizing version decoration consists of removing redundant decorators and follows a few rules, described below. For these rules, consider an ordered set of versions `1...n`. -- A decorator `@removed(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@removed(T, a)` with `a` in `1..n` and `a < c` unless there is a decorator `@added(T, b)` with `b` in `1..n` and `a < b < c`. -- A decorator `@added(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@added(T,a)` with `a` in `1..n` and `a < c` unless there is a decorator `@removed(T,b)` with `b` in `1..n` and `a < b < c`. +- Trim any sequence of `@removed` decorators without an `@added` between them: A decorator `@removed(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@removed(T, a)` with `a` in `1..n` and `a < c` unless there is a decorator `@added(T, b)` with `b` in `1..n` and `a < b < c`. +- Trim any sequence of `@added` decorators without any `@removed` between them: A decorator `@added(T, c)` with type `T` and `c` in `1..n` may be safely removed if there is another decorator `@added(T,a)` with `a` in `1..n` and `a < c` unless there is a decorator `@removed(T,b)` with `b` in `1..n` and `a < b < c`. - Any duplicated application of a versioning decorator to a type with the same parameters may be safely removed, that is: - `@added(T, a)` and `@added(T, a)` can be simplified to `@added(T, a)` - `@removed(T, a)` and `@removed(T, a)` can be simplified to `@removed(T, a)` @@ -31,6 +33,15 @@ Normalizing version decoration consists of removing redundant decorators and fol - `@returnTypeChangedFrom(T, a, U)` and `@returnTypeChangedFrom(T, a, U)` can be simplified to `@returnTypeChangedFrom(T, a, U)` - If `@added(T, a)` and `@removed(T,a)` occur, `@added(T, a)` may be removed. - If any versioning decorator with 3 arguments `@dec(T, v, a)` where `T` is a type, `v` is a version and `a` is a valid arg value occurs with another application of the same decorator `@dec(T, v, b)` and `b != a`, then the innermost of the two decorators can be removed. +- If any of the following decorators reference the first version, they may be removed: + - `@added` + - `@renamedFrom` + - `@madeOptional` + - `@typeChangedFrom` + - `@returnTypeChangedFrom` +- if `@removed(T, 1)` occurs, where `T` is the decorated type and `1` is the first version: + - If `T` occurs in any subsequent version (i.e. if there is any), this decorator should remain + - Otherwise, the decorated type can simply be removed. ## Handling Each Versioning Decorator That References a Preview Version diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md index be3a418fc1..ecffa261b7 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md @@ -2,7 +2,7 @@ title: Immediately Replacing a Preview Version --- -For some Resource Providers, whenever a new stable version is released, a new preview version is created, because some preview features are not ready to be stable, but may become stable in a future version. To accommodate this need and account for the limitations of breaking change checks, which require a single version change for any PR into the rest-api-specs repo, the recommended solution is to introduce a stable and subsequent preview _together_ in your TypeSPed api description and then split this change into two PRs: one representing the new stable and the second representing the subsequent preview. This involves the following steps described in the sections below: +For some Resource Providers, whenever a new stable version is released, a new preview version is created, because some preview features are not ready to be stable, but may become stable in a future version. To accommodate this need and account for the limitations of breaking change checks, which require a single version change for any PR into the rest-api-specs repo, the recommended solution is to introduce a stable and subsequent preview _together_ in your TypeSpec api description and then split this change into two PRs: one representing the new stable and the second representing the subsequent preview. This involves the following steps described in the sections below: - Create the new preview version based on the latest preview version - Create the stable version (which should immediately precede the new preview version) @@ -11,7 +11,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr - After this PR is merged, create a PR with the whole spec, effectively adding the new preview ## Creating New Preview and Stable Versions -- If the existing preview version is A, add the new stable version A + 1 and the new preview version A + 2 to the Versions enumeration. +- If the existing preview version is `A`, add the new stable version `A + 1` and the new preview version `A + 2` to the Versions enumeration. - For all changes from preview version `A` that are part of stable version `A + 1` - if a new type was added in `A` and is now stable (`@added(T, A)`), add the new decorator `@added(T, A + 1)` - if a type was made optional in `A` and this change is now stable (`@madeOptional(T, A)`), add the new decorator `@madeOptional(T, A + 1)` @@ -35,7 +35,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr - Remove version `A + 2` and all decorators that reference version `A + 2` from the spec. - Compile the spec to produce artifacts (especially the new stable version (`A + 1`) openapi ) - Add the new stable version (`A + 1`) to the README.md file. - - Create a and merge the PR + - Create and merge the PR ## Create a PR with the Combined Spec - Do the following with Copy 2 From eae69e1695f6bd3cfe334febe4f59e647b811d6d Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 21 Jan 2026 17:47:22 -0800 Subject: [PATCH 07/17] Update formatting --- .../docs/howtos/ARM/versioning/02-preview-after-preview.md | 2 +- .../docs/docs/howtos/ARM/versioning/06-converting-specs.md | 4 ++-- .../docs/docs/howtos/ARM/versioning/07-perpetual-preview.md | 2 ++ 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md index 56c86ffa65..15fd28388e 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md @@ -14,7 +14,7 @@ This includes: ~~v2025_12_01_preview: "2025-12-01-preview",~~ v2026_01_01_preview: "2026-01-01-preview", - + - Update any version documentation to use the new version - Change the name of the `examples` version folder for the latest preview to match the new preview version - Make changes to the API description based on how the API has changed diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md index e61d95e9b4..3d8c3315df 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md @@ -10,8 +10,8 @@ For each type decorated with a versioning decorator that references a preview ve A conversion consists of the following steps, outlined in the sections below - Normalizing version decoration (optional) -- Determining which versions should be removed: this should include all preview api-versions __except__ the last version (if the last version is a preview, that version will __not__ be removed.) -- Handling each versioning decorator application that references a deleted preview version (except the __first__ version) +- Determining which versions should be removed: this should include all preview api-versions **except** the last version (if the last version is a preview, that version will **not** be removed.) +- Handling each versioning decorator application that references a deleted preview version (except the **first** version) - Removing the first version (if it is a preview) - Removing the deleted preview versions from the Versions enum - Cleaning up (optional) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md index ecffa261b7..a848228294 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md @@ -11,6 +11,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr - After this PR is merged, create a PR with the whole spec, effectively adding the new preview ## Creating New Preview and Stable Versions + - If the existing preview version is `A`, add the new stable version `A + 1` and the new preview version `A + 2` to the Versions enumeration. - For all changes from preview version `A` that are part of stable version `A + 1` - if a new type was added in `A` and is now stable (`@added(T, A)`), add the new decorator `@added(T, A + 1)` @@ -38,6 +39,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr - Create and merge the PR ## Create a PR with the Combined Spec + - Do the following with Copy 2 - Follow the instructions for normalizing decoration in the [converting specifications](./06-converting-specs.md#normalizing-version-decoration-optional) document. This will remove any redundant decoration between the new stable and preview versions (`A + 1` and `A + 2`). - Compile the spec to produce artifacts (especially the new stable and preview version (`A + 1` and `A + 2` ) apis). From 5c5bf42ca9c3d70fca55ad642875a4ba02e7314b Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 21 Jan 2026 17:50:11 -0800 Subject: [PATCH 08/17] typo --- .../docs/docs/howtos/ARM/versioning/07-perpetual-preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md index a848228294..699e915a95 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md @@ -27,7 +27,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr - Remove its example folder - Remove all references to version A in `README.md` - ## Create A Copy of the Spec for the Stable Version only +## Create A Copy of the Spec for the Stable Version only - Create two copies of your spec - One which will contain just the new stable version (use this to create the first PR into the specs repo). Call this Copy 1. From 051edff48429e0883d3a70929ce4c98eb8752550 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Thu, 22 Jan 2026 13:56:26 -0800 Subject: [PATCH 09/17] Responding to review feedback --- .../versioning/02-preview-after-preview.md | 1 + .../ARM/versioning/04-preview-after-stable.md | 1 + .../ARM/versioning/06-converting-specs.md | 1 + .../ARM/versioning/07-perpetual-preview.md | 28 +++++++++++++------ 4 files changed, 23 insertions(+), 8 deletions(-) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md index 15fd28388e..000633bf1f 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md @@ -15,6 +15,7 @@ This includes: ~~v2025_12_01_preview: "2025-12-01-preview",~~ v2026_01_01_preview: "2026-01-01-preview", +- Move the new preview version to be the _last version_ of the versions enum, and ensure it is decorated with `@previewVersion` - Update any version documentation to use the new version - Change the name of the `examples` version folder for the latest preview to match the new preview version - Make changes to the API description based on how the API has changed diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md b/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md index 1ba0820d4a..6f427d46eb 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md @@ -7,6 +7,7 @@ When the latest api-version in your TypeSpec spec is a stable version, adding a ## Making Changes to your TypeSpec spec - Add a new version to the `Versions` enum in your spec for the new preview. +- Decorate this version with the `@previewVersion` decorator from the `Azure.Core` library - Make changes to the API description based on how the API has changed - If any types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md index 3d8c3315df..37cc29a39c 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md @@ -14,6 +14,7 @@ A conversion consists of the following steps, outlined in the sections below - Handling each versioning decorator application that references a deleted preview version (except the **first** version) - Removing the first version (if it is a preview) - Removing the deleted preview versions from the Versions enum +- If there is a remaining preview version, it should be the last version in the versions enum. Ensure it is decorated with the `@previewVersion` decorator. - Cleaning up (optional) In this document we use the notation `@(T, u, [arg])` this indicates an instance of the decorator `` decorating type `T` using version `u` in a set of monotonically increasing versions `1..n` diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md index 699e915a95..f935442e75 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md @@ -12,7 +12,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr ## Creating New Preview and Stable Versions -- If the existing preview version is `A`, add the new stable version `A + 1` and the new preview version `A + 2` to the Versions enumeration. +- If the existing preview version is `A`, add the new stable version `A + 1` and the new preview version `A + 2` to the Versions enumeration, ensure that version `A + 2` is decorated with `@previewVersion` from the `Azure.Core` library (and remove that decoration from any other version). - For all changes from preview version `A` that are part of stable version `A + 1` - if a new type was added in `A` and is now stable (`@added(T, A)`), add the new decorator `@added(T, A + 1)` - if a type was made optional in `A` and this change is now stable (`@madeOptional(T, A)`), add the new decorator `@madeOptional(T, A + 1)` @@ -21,27 +21,39 @@ For some Resource Providers, whenever a new stable version is released, a new pr - if an operation returnType was changed in `A` and this change is now stable (`@returnTypeChangedFrom(T, A, U)`), add the new decorator `@returnTypeChangedFrom(T, A + 1, U)` - If a type was removed in `A` and this change is now stable (`@removed(T, A)`), add the new decorator `@removed(T, A + 1)` - Change all versioning decorators `dec(T, A, args)` to `dec(T, A + 2, args)` where `T` is a type, `A` is the latest preview version, `A + 2` is the new preview version you added in the first step and `args` are any additional arguments to the decorator. Note that, after this change, some decorators will be duplicated in version `A + 1` and version `A + 2`. This is expected. +- Add any new type changes to stable version (A + 1) and decorate appropriately, as shown in the [versioning guide](../versioning.md). Note that these changes should also appear in the new preview (A + 2) - Remove version `A` from the versions enumeration -- Create examples directories for the two new versions and populate them with appropriate examples +- Create examples directories for the new stable version (A + 1) and populate them with appropriate examples - If version A _is not needed_ in the specs repo - Remove its example folder - Remove all references to version A in `README.md` ## Create A Copy of the Spec for the Stable Version only -- Create two copies of your spec - - One which will contain just the new stable version (use this to create the first PR into the specs repo). Call this Copy 1. - - The other will contain both the new stable _and_ preview versions (use this to create the final PR after the first PR is merged). Call this Copy 2. -- Do the following with Copy 1 - - Remove version `A + 2` and all decorators that reference version `A + 2` from the spec. +- Create a complete copy of your spec + - This copy will be used to contain just the new stable version (use this to create the first PR into the specs repo). Call this Copy. + - The original version will contain both the new stable _and_ preview versions (use this to create the final PR after the first PR is merged). Call this Original. +- Do the following with the Copy + - Remove all decorators that reference version `A + 2` and use the same parameters as in `A + 1` + - For example, if these decorators exist: `@added(T, A + 2) @added(T, A + 1)`, then, after this step, only `@added(T, A + 1)` should remain in this copy of the spec. + - Undo and remove any remaining decorators referencing `A + 2` using the following guide: + - For any type `T` decorated with `@added(T, A + 2)`, remove the type `T` and all its decorators + - For any type `T` decorated with `@removed(T, A + 2)`, remove the decorator + - For any type `T` decorated with `@renamedFrom(T, A + 2, oldName)` rename the type `oldName` and remove the decorator + - For any property of parameter `T` decorated with `@typeChangedFrom(T, A + 2, oldType)` set the type of the property to `oldType` and remove the decorator + - For any operation `T` decorated with `@returnTypeChangedFrom(T, A + 2, oldType)` set the return type of the operation to `oldType` and remove the decorator + - For any property or parameter `T` decorated with `@madeOptional(T, A + 2)` make the parameter or property `T` required and remove the decorator + - Remove version `A + 2` from the version enum. - Compile the spec to produce artifacts (especially the new stable version (`A + 1`) openapi ) - Add the new stable version (`A + 1`) to the README.md file. - Create and merge the PR ## Create a PR with the Combined Spec -- Do the following with Copy 2 +- Do the following with the Original - Follow the instructions for normalizing decoration in the [converting specifications](./06-converting-specs.md#normalizing-version-decoration-optional) document. This will remove any redundant decoration between the new stable and preview versions (`A + 1` and `A + 2`). + - Add any type changes that are introduced in the new preview and decorate appropriately, following the [versioning guide](../versioning.md) + - Add a new example folder for the new preview version and populate with appropriate examples. - Compile the spec to produce artifacts (especially the new stable and preview version (`A + 1` and `A + 2` ) apis). - Copy the README.md from copy 1 and add the new preview version to the file. - Create and merge the final PR - this copy will be your specification going forward. From a743c69e234e9573bbf7c02eed3dad01523c46f3 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Thu, 22 Jan 2026 14:02:57 -0800 Subject: [PATCH 10/17] Disambiguate removing types from the removed decorator --- .../docs/howtos/ARM/versioning/02-preview-after-preview.md | 4 ++-- .../docs/howtos/ARM/versioning/03-stable-after-preview.md | 2 +- .../docs/docs/howtos/ARM/versioning/06-converting-specs.md | 2 +- .../docs/docs/howtos/ARM/versioning/07-perpetual-preview.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md index 000633bf1f..647c555732 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md @@ -15,11 +15,11 @@ This includes: ~~v2025_12_01_preview: "2025-12-01-preview",~~ v2026_01_01_preview: "2026-01-01-preview", -- Move the new preview version to be the _last version_ of the versions enum, and ensure it is decorated with `@previewVersion` +- The new preview version should already be the _last version_ of the versions enum, also ensure it is decorated with `@previewVersion` - Update any version documentation to use the new version - Change the name of the `examples` version folder for the latest preview to match the new preview version - Make changes to the API description based on how the API has changed - - If any type that was introduced in the latest preview is _not_ in the new preview, simply remove the type + - If any type that was introduced in the latest preview is _not_ in the new preview, simply delete the type - If any other types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator - Add and modify examples to match the api changes diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md index 16e36a0bb2..5f5352c516 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md @@ -14,7 +14,7 @@ This includes the followign steps: - Determine which type changes from the latest preview are now stable - Update the versioning decorators for those changes to reference the new stable version - For changes in the latest preview (p) that are _not_ in the new stable version - - For any type with an `@added(p)` decorator, remove the type + - For any type with an `@added(p)` decorator, delete the type - For any property or parameter with a `@typeChangedFrom(p, Type)` decorator, replace the property type with the `Type` argument, and then remove the decorator, for example ```tsp diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md index 37cc29a39c..e29aacef8e 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md @@ -82,7 +82,7 @@ Normalizing version decoration consists of removing redundant decorators and fol - Remove them. - Change the version argument in the decorator to match the successor version [ `@added(T, u) -> @added(T, u + 1)`] - If there is an `@removed(T, u + 1)` decorator referencing the immediate successor version - - If the type does not occur in any previous version `v < u`, remove the type altogether + - If the type does not occur in any previous version `v < u`, delete the type altogether - If the type does occur in a previous version, remove the `@added(T, u)` decorator. - If there are no `@added(T, u + 1)` or `@removed(T, u + 1)` decorators referencing the immediate successor version, change the version in the decorator to the immediate successor version: [`@added(T, u)` -> `@added(T, u + 1)`] diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md index f935442e75..154f45e795 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md @@ -37,7 +37,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr - Remove all decorators that reference version `A + 2` and use the same parameters as in `A + 1` - For example, if these decorators exist: `@added(T, A + 2) @added(T, A + 1)`, then, after this step, only `@added(T, A + 1)` should remain in this copy of the spec. - Undo and remove any remaining decorators referencing `A + 2` using the following guide: - - For any type `T` decorated with `@added(T, A + 2)`, remove the type `T` and all its decorators + - For any type `T` decorated with `@added(T, A + 2)`, delete the type `T` and all its decorators - For any type `T` decorated with `@removed(T, A + 2)`, remove the decorator - For any type `T` decorated with `@renamedFrom(T, A + 2, oldName)` rename the type `oldName` and remove the decorator - For any property of parameter `T` decorated with `@typeChangedFrom(T, A + 2, oldType)` set the type of the property to `oldType` and remove the decorator From d0c3b3baa1e116e4e954081d2947fcbacaa23926 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 27 Jan 2026 19:11:43 -0800 Subject: [PATCH 11/17] Responding to review feedback --- .../ARM}/01-about-versioning.md | 3 +- .../ARM}/02-preview-after-preview.md | 48 ++++++- .../ARM}/03-stable-after-preview.md | 85 +++++++----- .../ARM}/04-preview-after-stable.md | 38 ++++- .../ARM}/05-stable-after-stable.md | 3 +- .../ARM}/06-converting-specs.md | 76 ++++++++++ .../ARM}/07-perpetual-preview.md | 131 +++++++++++++++++- .../docs/howtos/Versioning/preview-version.md | 22 ++- 8 files changed, 353 insertions(+), 53 deletions(-) rename website/src/content/docs/docs/howtos/{ARM/versioning => Versioning/ARM}/01-about-versioning.md (96%) rename website/src/content/docs/docs/howtos/{ARM/versioning => Versioning/ARM}/02-preview-after-preview.md (66%) rename website/src/content/docs/docs/howtos/{ARM/versioning => Versioning/ARM}/03-stable-after-preview.md (66%) rename website/src/content/docs/docs/howtos/{ARM/versioning => Versioning/ARM}/04-preview-after-stable.md (70%) rename website/src/content/docs/docs/howtos/{ARM/versioning => Versioning/ARM}/05-stable-after-stable.md (95%) rename website/src/content/docs/docs/howtos/{ARM/versioning => Versioning/ARM}/06-converting-specs.md (82%) rename website/src/content/docs/docs/howtos/{ARM/versioning => Versioning/ARM}/07-perpetual-preview.md (66%) diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md similarity index 96% rename from website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md index d64005fd61..5bb86c7ccb 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md @@ -1,5 +1,6 @@ --- -title: About Versioning in the azure-rest-api-specs Repository +title: About Versioning ARM APIs in the azure-rest-api-specs Repository +llmstxt: true --- TypeSpec uses a versioning library that models the changes in each new version of the API, rather than having a separate api description for each api-version. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md similarity index 66% rename from website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md index 647c555732..d1813301cc 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md @@ -1,5 +1,6 @@ --- title: Adding a Preview Version when the Last Version was a Preview +llmstxt: true --- When the last api-version in your TypeSpec spec is a preview, adding a new preview version is simply replacing the latest preview version with a new preview version. @@ -16,12 +17,51 @@ This includes: v2026_01_01_preview: "2026-01-01-preview", - The new preview version should already be the _last version_ of the versions enum, also ensure it is decorated with `@previewVersion` -- Update any version documentation to use the new version +- Update any mention in documentation of the old api-version to use the new api-version - Change the name of the `examples` version folder for the latest preview to match the new preview version + + ```bash + > mv examples/2025-12-01-preview examples/2026-01-01-preview + ``` + - Make changes to the API description based on how the API has changed - If any type that was introduced in the latest preview is _not_ in the new preview, simply delete the type - - If any other types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version - - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator + + ```diff lang=tsp + - @added(Versions.`2026-01-01-preview`) + - model Foo {} + ``` + + - If any type was removed in the latest preview but **appears** in the new preview, remove the decorator + + ```diff lang=tsp + - @removed(Versions.`2026-01-01-preview`) + model Bar {} + ``` + + - Similarly, if there is any change from the latest preview that does not apply to the new preview version, reverse the decorator. + + ```diff lang=tsp + - @renamedFrom(Versions.`2026-01-01-preview`, "oldProp") + - newProp: string; + + oldProp: string; + ``` + + ```diff lang=tsp + - @typeChangedFrom(Versions.`2026-01-01-preview`, string) + - changedProp: int32; + + changedProp: string; + ``` + + - If any other types are removed in the new preview (unlikely) mark these with an `@removed` decorator referencing the new version + + ```diff lang=tsp + + @removed(Versions.`2026-01-01-preview`) + model Bar {} + ``` + + - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator. + - Add and modify examples to match the api changes ## Preparing a PR into the azure-rest-api-specs repo @@ -50,7 +90,7 @@ This includes: ```bash C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP - C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . ``` - If you _don't_ need the older preview version, remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md similarity index 66% rename from website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md index 5f5352c516..a98b495121 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md @@ -1,75 +1,90 @@ --- title: Adding a Stable Version when the Last Version was a Preview +llmstxt: true --- -When the last api-version in your TypeSpec spec is a preview, adding a new stable version means +When the last api-version in your TypeSpec spec is a preview, adding a new stable version means you must remove any preview types or other api-changes from the preview and only leave those type changes that are now stable. This includes the followign steps: ## Making Changes to your TypeSpec spec - Add a new entry to the versions enum for the new stable version -- Update any version documentation to use the new version +- Update any mention in documentation of the old api-version to use the new api-version - Change the name of the `examples` version folder for the latest preview to match the new stable version + + ```bash + > mv examples/2025-10-01-preview examples/2026-01-01 + ``` + - Determine which type changes from the latest preview are now stable - Update the versioning decorators for those changes to reference the new stable version + + ```diff lang=tsp + - @added(Versions.`2025-10-01-preview`) + + @added(Versions.`2026-01-01`) + remainingProperty?: string; + ``` + - For changes in the latest preview (p) that are _not_ in the new stable version - For any type with an `@added(p)` decorator, delete the type - - For any property or parameter with a `@typeChangedFrom(p, Type)` decorator, replace the property type with the `Type` argument, and then remove the decorator, for example - ```tsp - @typeChangedFrom(Versions.2025-12-01-preview, string) - property: int32; + ```diff lang=tsp + - @added(Versions.`2025-10-01-preview`) + - model Foo {} ``` - should be changed to: + - For any property or parameter with a `@typeChangedFrom(p, Type)` decorator, replace the property type with the `Type` argument, and then remove the decorator, for example - ```tsp - property: string; + ```diff lang=tsp + - @typeChangedFrom(Versions.`2025-12-01-preview`, string) + - property: int32; + + property: string; ``` - For any operation with an `@returnTypeChangedFrom(p, ReturnType)` decorator, replace the return type with the `ReturnType` argument and then remove the decorator, for example: - ```tsp - @returnTypeChangedFrom(Versions.2025-12-01-preview, void) - move is ArmResourceActionSync(Widget, MoveOptions, MoveResult); - ``` - - should be changed to: - - ```tsp - move is ArmResourceActionSync(Widget, MoveOptions, void); + ```diff lang=tsp + - @returnTypeChangedFrom(Versions.`2025-12-01-preview`, void) + - move is ArmResourceActionSync(Widget, MoveOptions, MoveResult); + + move is ArmResourceActionSync(Widget, MoveOptions, void); ``` - For any type with an `@renamedFrom(p, Name)` decorator, replace the name of the type with the `Name` argument in the decorator and remove the decorator, for example: - ```tsp - @renamedFrom(Versions.2025-12-01-preview, "oldProperty") - newProperty: int32; + ```diff lang=tsp + - @renamedFrom(Versions.`2025-12-01-preview`, "oldProperty") + - newProperty: int32; + + oldProperty: int32; ``` - should be changed to: + - For any property or parameter with a `@madeOptional(p)` decorator, remove the decorator, and make the property required, for example: - ```tsp - oldProperty: int32; + ```diff lang=tsp + - @madeOptional(Versions.`2025-12-01-preview`) + - property?: int32; + + property: int32; ``` - - For any property or parameter with a `@madeOptional(p)` decorator, remove the decorator, and make the property required, for example: + - For any type with an `@removed(p)` decorator, remove the decorator - ```tsp - @madeOptional(Versions.2025-12-01-preview) - property?: int32; - ``` + ```diff lang=tsp + - @removed( Versions.`2025-12-01-preview`) + property?: string; + ``` - should be changed to: +- Model any additional changes in the new stable version and mark with the appropriate versioning decorator, referencing the new stable version +- Remove the preview version from the version enum - ```tsp - property: int32; - ``` + ```diff lang=tsp + enum Versions { + - @Azure.Core.previewVersion + - `2025-10-01-preview`, + + `2026-01-01`, + } - - For any type with an `@removed(p)` decorator, remove the decorator + ``` -- Model any additional changes in the new stable version and mark with the appropriate versioning decorator, referencing the new stable version - Add and modify examples to match the api changes in the new stable version ## Preparing a PR into the azure-rest-api-specs repo diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md b/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md similarity index 70% rename from website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md index 6f427d46eb..e3a206a28a 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md @@ -1,16 +1,50 @@ --- title: Adding a Preview Version when the Last Version was a Stable Version +llmstxt: true --- -When the latest api-version in your TypeSpec spec is a stable version, adding a new preview version is simply adding any new types and operations in the new preview and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../versioning.md). +When the latest api-version in your TypeSpec spec is a stable version, adding a new preview version is simply adding any new types and operations in the new preview and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../../ARM/versioning.md). ## Making Changes to your TypeSpec spec - Add a new version to the `Versions` enum in your spec for the new preview. + + ```diff lang=tsp + enum Versions { + `2025-10-01`, + + `2026-01-01-preview`, + } + ``` + - Decorate this version with the `@previewVersion` decorator from the `Azure.Core` library + + ```diff lang=tsp + enum Versions { + `2025-10-01`, + + @Azure.Core.previewVersion + `2026-01-01-preview`, + } + ``` + - Make changes to the API description based on how the API has changed - - If any types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version + - If any types are removed in the new preview (unlikely) mark these with an `@removed` decorator referencing the new version + + ```diff lang=tsp + + @removed(Versions.`2026-01-01-preview`) + model Foo {} + ``` + - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator + + ```diff lang=tsp + + @added(Versions.`2026-01-01-preview`) + + model Foo {} + + + @renamedFrom(Versions.`2026-01-01-preview`, "Bar") + - model Bar {} + + model Baz {} + ``` + - Create a new examples folder for the new version `examples\` and populate it with examples. ## Preparing a PR into the azure-rest-api-specs repo diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md b/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md similarity index 95% rename from website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md index f69893aa1a..ecf397977c 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/05-stable-after-stable.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md @@ -1,8 +1,9 @@ --- title: Adding a Stable Version when the Last Version was a Stable Version +llmstxt: true --- -When the latest api-version in your TypeSpec spec is a stable version, adding a new stable version is simply adding any new types and operations in the new stable and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../versioning.md). +When the latest api-version in your TypeSpec spec is a stable version, adding a new stable version is simply adding any new types and operations in the new stable and marking them with the appropriate versioning decoration, as described in [TypeSpec Versioning for Azure ResourceManager APIs](../../ARM/versioning.md). ## Making Changes to your TypeSpec spec diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md b/website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md similarity index 82% rename from website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md index e29aacef8e..69706bfdc7 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/06-converting-specs.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md @@ -1,5 +1,6 @@ --- title: Converting Existing Specs with Multiple Previews +llmstxt: true --- Converting a spec with multiple preview versions into a spec with a single, latest preview version is complex because the changes that occur in any @@ -53,6 +54,12 @@ Normalizing version decoration consists of removing redundant decorators and fol - If there is one or more `@renamedFrom(T, u + 1, anotherName)` decorators, remove them. - Change `@renamedFrom(T, u, name)` to `@renamedFrom(T, u + 1, name)` + ```diff lang=tsp + - @renamedFrom(Versions.`2025-10-01-preview`, "oldName") + + @renamedFrom(Versions.`2025-11-01`, "oldName") + newName: string; + ``` + ## `@typeChangedFrom(T, u, type)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` @@ -60,6 +67,12 @@ Normalizing version decoration consists of removing redundant decorators and fol - If there is one or more `@typeChangedFrom` decorators referencing the immediate successor version, remove them. - Change `@typeChangedFrom(T, u, type)` to `@typeChangedFrom(T, u + 1, type)` + ```diff lang=tsp + - @typeChangedFrom(Versions.`2025-10-01-preview`, int32) + + @typeChangedFrom(Versions.`2025-11-01`, int32) + newType: string; + ``` + ## `@returnTypeChangedFrom(T, u, returnType)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` @@ -67,6 +80,12 @@ Normalizing version decoration consists of removing redundant decorators and fol - If there is one or more `@returnTypeChangedFrom` decorators referencing the immediate successor version, remove them. - Change `@returnTypeChangedFrom(T, u, returnType)` to `@returnTypeChangedFrom(T, u + 1, returnType)` + ```diff lang=tsp + - @returnTypeChangedFrom(Versions.`2025-10-01-preview`, void) + + @returnTypeChangedFrom(Versions.`2025-11-01`, void) + move is ArmResourceActionSync; + ``` + ## `@madeOptional(T, u)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` @@ -74,6 +93,12 @@ Normalizing version decoration consists of removing redundant decorators and fol - If there is one or more `@madeOptional` decorators referencing the immediate successor version, remove them. - Change `@madeOption(T, u)` to `@madeOptional(T, u + 1)` + ```diff lang=tsp + - @madeOptional(Versions.`2025-10-01-preview`) + + @madeOptional(Versions.`2025-11-01`) + nowOptional?: string; + ``` + ## `@added(T, u)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` @@ -81,11 +106,41 @@ Normalizing version decoration consists of removing redundant decorators and fol - If there is one or more `@added(T, u + 1)` decorators referencing the immediate successor version - Remove them. - Change the version argument in the decorator to match the successor version [ `@added(T, u) -> @added(T, u + 1)`] + + ```diff lang=tsp + - @added(Versions.`2025-10-01-preview`) + - @added(Versions.`2025-11-01`) + @added(Versions.`2025-11-01`) + newType: string; + ``` + - If there is an `@removed(T, u + 1)` decorator referencing the immediate successor version - If the type does not occur in any previous version `v < u`, delete the type altogether + + ```diff lang=tsp + - @added(Versions.`2025-10-01-preview`) + - @removed(Versions.`2025-11-01`) + - goneType: string; + ``` + - If the type does occur in a previous version, remove the `@added(T, u)` decorator. + + ```diff lang=tsp + @added(Versions.`2025-06-01`) + - @added(Versions.`2025-10-01-preview`) + @removed(Versions.`2025-11-01`) + remainType: string; + ``` + - If there are no `@added(T, u + 1)` or `@removed(T, u + 1)` decorators referencing the immediate successor version, change the version in the decorator to the immediate successor version: [`@added(T, u)` -> `@added(T, u + 1)`] + ```diff lang=tsp + - @added(Versions.`2025-10-01-preview`) + + @added(Versions.`2025-11-01`) + @removed(Versions.`2026-02-01`) + remainType: string; + ``` + ## `@removed(T, u)` decorator - Based on the version referenced in the decorator, determine the immediate successor version `u + 1` @@ -93,10 +148,31 @@ Normalizing version decoration consists of removing redundant decorators and fol - If there is one or more `@removed(T, u + 1)` decorators referencing the immediate successor version - Remove them. - Change the version argument in the decorator to match the successor version [`@removed(T, u) -> @removed(T, u + 1)`] + + ```diff lang=tsp + - @removed(Versions.`2025-10-01-preview`) + - @removed(Versions.`2025-11-01`) + @removed(Versions.`2025-11-01`) + remainType: string; + ``` + - if there is one or more `@added(T, u + 1)` decorators in the immediate successor version - Remove the `@removed(T, u)` decorator + + ```diff lang=tsp + - @removed(Versions.`2025-10-01-preview`) + @added(Versions.`2025-11-01`) + remainType: string; + ``` + - If there are no `@removed(T, u + 1)` or `@removed(T, u + 1)` decorators referencing the immediate successor version, change the version in the decorator to the immediate successor version: [`@removed(T, u)` -> `@removed(T, u + 1)`] + ```diff lang=tsp + - @removed(Versions.`2025-10-01-preview`) + + @removed(Versions.`2025-11-01`) + remainType: string; + ``` + ## Removing the _First_ version in the Specification TypeSpec specs require no versioning decoration for the first version of a spec, and all versioning decorators except `@removed` have no impact on the type graph for subsequent versions and can be safely removed. Any `@removed` decorator referencing the first version should be treated as follows: diff --git a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md similarity index 66% rename from website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md index 154f45e795..76cfd3cec0 100644 --- a/website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md @@ -1,5 +1,6 @@ --- -title: Immediately Replacing a Preview Version +title: How to Manage a Single Active Preview When Some Features Always Remain In Preview +llmstxt: true --- For some Resource Providers, whenever a new stable version is released, a new preview version is created, because some preview features are not ready to be stable, but may become stable in a future version. To accommodate this need and account for the limitations of breaking change checks, which require a single version change for any PR into the rest-api-specs repo, the recommended solution is to introduce a stable and subsequent preview _together_ in your TypeSpec api description and then split this change into two PRs: one representing the new stable and the second representing the subsequent preview. This involves the following steps described in the sections below: @@ -15,17 +16,83 @@ For some Resource Providers, whenever a new stable version is released, a new pr - If the existing preview version is `A`, add the new stable version `A + 1` and the new preview version `A + 2` to the Versions enumeration, ensure that version `A + 2` is decorated with `@previewVersion` from the `Azure.Core` library (and remove that decoration from any other version). - For all changes from preview version `A` that are part of stable version `A + 1` - if a new type was added in `A` and is now stable (`@added(T, A)`), add the new decorator `@added(T, A + 1)` + + ```diff lang=tsp + @added(Versions.`2025-10-01-preview`) + + @added(Versions.`2025-11-01`) + remainType: string; + ``` + - if a type was made optional in `A` and this change is now stable (`@madeOptional(T, A)`), add the new decorator `@madeOptional(T, A + 1)` - - if a type was renamed in `A` and this change is now stable (`@renamedFrom(T, A, Name)`), add the new decorator `@typeChangedFrom(T, A + 1, Name)` + + ```diff lang=tsp + @madeOptional(Versions.`2025-10-01-preview`) + + @madeOptional(Versions.`2025-11-01`) + optionalType?: string; + ``` + + - if a type was renamed in `A` and this change is now stable (`@renamedFrom(T, A, Name)`), add the new decorator `@renamedFrom(T, A + 1, Name)` + + ```diff lang=tsp + @renamedFrom(Versions.`2025-10-01-preview`, "oldName") + + @renamedFrom(Versions.`2025-11-01`, "oldName") + newName: string; + ``` + - if a property or parameter had its type changed in `A` and is now stable (`@typeChangedFrom(T, A, U)`), add the new decorator `@typeChangedFrom(T, A + 1, U)` + + ```diff lang=tsp + @typeChangedFrom(Versions.`2025-10-01-preview`, int32) + + @typeChangedFrom(Versions.`2025-11-01`, int32) + changedType: string; + ``` + - if an operation returnType was changed in `A` and this change is now stable (`@returnTypeChangedFrom(T, A, U)`), add the new decorator `@returnTypeChangedFrom(T, A + 1, U)` + + ```diff lang=tsp + @returnTypeChangedFrom(Versions.`2025-10-01-preview`, void) + + @returnTypeChangedFrom(Versions.`2025-11-01`, void) + move is ArmResourceActionSync + ``` + - If a type was removed in `A` and this change is now stable (`@removed(T, A)`), add the new decorator `@removed(T, A + 1)` + + ```diff lang=tsp + @removed(Versions.`2025-10-01-preview`) + + @removed(Versions.`2025-11-01`) + goneType: string; + ``` + - Change all versioning decorators `dec(T, A, args)` to `dec(T, A + 2, args)` where `T` is a type, `A` is the latest preview version, `A + 2` is the new preview version you added in the first step and `args` are any additional arguments to the decorator. Note that, after this change, some decorators will be duplicated in version `A + 1` and version `A + 2`. This is expected. + + ```diff lang=tsp + - @removed(Versions.`2025-10-01-preview`) + @removed(Versions.`2025-11-01`) + + @removed(Versions.`2025-12-01-preview`) + goneType: string; + ``` + - Add any new type changes to stable version (A + 1) and decorate appropriately, as shown in the [versioning guide](../versioning.md). Note that these changes should also appear in the new preview (A + 2) - Remove version `A` from the versions enumeration + + ```diff lang=tsp + enum Versions { + - @previewVersion + - `2025-10-01-preview`, + + `2025-11-01`, + + @previewVersion + + `2025-12-01-preview`, + } + ``` + - Create examples directories for the new stable version (A + 1) and populate them with appropriate examples - If version A _is not needed_ in the specs repo - Remove its example folder + + ```bash + > rm -r examples/2025-10-01-preview + ``` + - Remove all references to version A in `README.md` ## Create A Copy of the Spec for the Stable Version only @@ -36,14 +103,70 @@ For some Resource Providers, whenever a new stable version is released, a new pr - Do the following with the Copy - Remove all decorators that reference version `A + 2` and use the same parameters as in `A + 1` - For example, if these decorators exist: `@added(T, A + 2) @added(T, A + 1)`, then, after this step, only `@added(T, A + 1)` should remain in this copy of the spec. + + ```diff lang=tsp + @added(Versions.`2025-11-01`) + - @added(Versions.`2025-12-01-preview`) + addedType: string; + ``` + - Undo and remove any remaining decorators referencing `A + 2` using the following guide: - For any type `T` decorated with `@added(T, A + 2)`, delete the type `T` and all its decorators + + ```diff lang=tsp + - @added(Versions.`2025-12-01-preview`) + - goneType: string; + ``` + - For any type `T` decorated with `@removed(T, A + 2)`, remove the decorator + + ```diff lang=tsp + - @removed(Versions.`2025-12-01-preview`) + remainType: string; + ``` + - For any type `T` decorated with `@renamedFrom(T, A + 2, oldName)` rename the type `oldName` and remove the decorator - - For any property of parameter `T` decorated with `@typeChangedFrom(T, A + 2, oldType)` set the type of the property to `oldType` and remove the decorator + + ```diff lang=tsp + - @renamedFrom(Versions.`2025-12-01-preview`, "oldName") + - newName: string; + + oldName: string; + ``` + + - For any property or parameter `T` decorated with `@typeChangedFrom(T, A + 2, oldType)` set the type of the property to `oldType` and remove the decorator + + ```diff lang=tsp + - @typeChangedFrom(Versions.`2025-12-01-preview`, int32) + - changedType: string; + + changedType: int32; + ``` + - For any operation `T` decorated with `@returnTypeChangedFrom(T, A + 2, oldType)` set the return type of the operation to `oldType` and remove the decorator + + ```diff lang=tsp + - @returnTypeChangedFrom(Versions.`2025-12-01-preview`, void) + - move is ArmResourceActionSync; + + move is ArmResourceActionSync; + ``` + - For any property or parameter `T` decorated with `@madeOptional(T, A + 2)` make the parameter or property `T` required and remove the decorator + + ```diff lang=tsp + - @madeOptional(Versions.`2025-12-01-preview`) + - remainType?: string; + + remainType: string; + ``` + - Remove version `A + 2` from the version enum. + + ```diff lang=tsp + enum Versions { + `2025-11-01`, + - @previewVersion + - `2025-12-01-preview`, + } + ``` + - Compile the spec to produce artifacts (especially the new stable version (`A + 1`) openapi ) - Add the new stable version (`A + 1`) to the README.md file. - Create and merge the PR @@ -52,7 +175,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr - Do the following with the Original - Follow the instructions for normalizing decoration in the [converting specifications](./06-converting-specs.md#normalizing-version-decoration-optional) document. This will remove any redundant decoration between the new stable and preview versions (`A + 1` and `A + 2`). - - Add any type changes that are introduced in the new preview and decorate appropriately, following the [versioning guide](../versioning.md) + - Add any type changes that are introduced in the new preview and decorate appropriately, following the [versioning guide](../../ARM/versioning.md) - Add a new example folder for the new preview version and populate with appropriate examples. - Compile the spec to produce artifacts (especially the new stable and preview version (`A + 1` and `A + 2` ) apis). - Copy the README.md from copy 1 and add the new preview version to the file. diff --git a/website/src/content/docs/docs/howtos/Versioning/preview-version.md b/website/src/content/docs/docs/howtos/Versioning/preview-version.md index 25af41a40d..33a9d67e00 100644 --- a/website/src/content/docs/docs/howtos/Versioning/preview-version.md +++ b/website/src/content/docs/docs/howtos/Versioning/preview-version.md @@ -5,16 +5,26 @@ llmstxt: true See [`@typespec/versioning` documentation](https://typespec.io/docs/libraries/versioning/guide) for the general versioning concept. This guide expands on how Azure Services should define Preview versions. -## Preview Versioning Rules +See [Common ARM Versioning Scenarios](../ARM/versioning.md) for how to make specific kinds of common API changes in ARM specs. + +## Preview Versioning Rules for All Azure APIs + +- Always make the last enum value the preview and apply `@previewVersion` to it. +- Only one version may be marked with the `@previewVersion` decorator. +- Mark all changes from the latest stable with appropriate versioning decorators, using `Versions.` as the version argument (where `` is the name of the last enum value) + +## Preview Versioning Rules for ARM APIs + +ARM APIs sometimes have special requirements for retaining swagger for preview APIs that are not yet retired. For detailed information about ARM API Versioning see [Supporting a Single Active Preview in ARM APIs](./ARM/01-about-versioning.md). + +## Preview Versioning Rules for Data Plane APIs -- Always make the last enum the preview and apply `@previewVersion` to it. -- Apply `@added(Versions.PreviewVersion)` to all preview items - these items will not show up in any GA Version - For a new GA, add a new version enum **BEFORE** the preview enum value. Manually change all **preview** items that are GA'ing so that the `@added` version value matches the new GA enum value - For any items remaining in **preview**, rename the **old preview** enum value to the **new preview** enum value. -## Usage Examples +### Usage Examples -### New preview Version +#### New preview Version In the following example we introduce a new preview version called `v3Preview` which includes everything from `v2` plus adds a new property to the `Widget` resource. @@ -65,7 +75,7 @@ model Widget { } ``` -### Adding a new stable (GA) version +#### Adding a new stable (GA) version This example builds on the previous one, where `v3` is introduced which GA's the `nickname` property introduced in `v3Preview` From 4bbf9d44dac830803df75ce0efa6e137200de117 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 27 Jan 2026 19:19:13 -0800 Subject: [PATCH 12/17] Clarification in preview doc --- .../docs/howtos/Versioning/ARM/02-preview-after-preview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md index d1813301cc..c857d0de72 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md @@ -24,7 +24,7 @@ This includes: > mv examples/2025-12-01-preview examples/2026-01-01-preview ``` -- Make changes to the API description based on how the API has changed +- Make changes to the API description based on how the API has changed between the preview versions (if it has) - If any type that was introduced in the latest preview is _not_ in the new preview, simply delete the type ```diff lang=tsp @@ -39,7 +39,7 @@ This includes: model Bar {} ``` - - Similarly, if there is any change from the latest preview that does not apply to the new preview version, reverse the decorator. + - Similarly, if there is any change from the latest preview that does not apply to the new preview version, reverse the decorator (unlikely). ```diff lang=tsp - @renamedFrom(Versions.`2026-01-01-preview`, "oldProp") From 713311babfd2b20f2f47d4f49700cd87aaa4ded0 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 28 Jan 2026 12:57:29 -0800 Subject: [PATCH 13/17] Responding to feedback --- .../Versioning/ARM/01-about-versioning.md | 17 +++- .../ARM/02-preview-after-preview.md | 90 ++++++++++++++++--- .../Versioning/ARM/03-stable-after-preview.md | 18 +++- .../Versioning/ARM/07-perpetual-preview.md | 5 +- 4 files changed, 112 insertions(+), 18 deletions(-) diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md index 5bb86c7ccb..c284383121 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md @@ -7,13 +7,15 @@ TypeSpec uses a versioning library that models the changes in each new version o This works well when APIs evolve according to versioning guidelines, without breaking changes. For the most part, this means that this system is very good at modeling differences between stable api-versions for Azure APIs, but can be cumbersome when describing differences between preview APIs. -Additionally, in Azure. preview APIs have a limited lifespan and limited support in SDKs and other tooling. For this reason and others, specs should only have a _single active preview_ at any point during the spec development process. +Additionally, in Azure. preview APIs have a limited lifespan and limited support in SDKs and other tooling. For this reason and others, specs should only have a _single active preview_ in TypeSpec at any point during the spec development process. At the same time, Azure ResourceManager teams may need to maintain OpenAPI files for preview versions until they are retired, some reasons for this include: - RPaaS live validation support - ARM registration support +See [Should I Retain the OpenAPI for an Old Preview API](#should-i-retain-the-openapi-for-an-old-preview-api) for details. + This document describes how to evolve APIs according to these guidelines, and how to meet both the single active preview guideline and the need to maintain some preview versions in Swagger in some situations, focusing on authoring of new APIs: - [How to add a new preview version when the last version was preview](./02-preview-after-preview.md) @@ -25,7 +27,16 @@ This document also describes how to move an existing multi-api typespec spec wit - [How to convert a spec with multiple preview versions into a spec with a single active preview](./06-converting-specs.md) -Additionally, there are some services that may always have features that remain in preview after a stable version is released. This can happen, for example, if there are multiple independent teams that own different resources in a service and operate on their own schedule. The recommended way to handle -this scenario is to model your ResourceProvider as multiple services, so each version and the corresponding SDKs can version independently. For some older services, this is not an option, so there is specialized guidance on how to maintain preview features over stable api releases: +Additionally, there are some services that may always have features that remain in preview after a stable version is released. This can happen, for example, if there are multiple independent teams that own different resources in a service and operate on their own schedule. The recommended way to handle this scenario is to model your ResourceProvider as multiple services, so each version and the corresponding SDKs can version independently. For some older services, this is not an option, so there is specialized guidance on how to maintain preview features over stable api releases (described below). If you are thinking about splitting your service, or about creating a new preview version with every stable version, be sure to have a discussion with the [Azure API Stewardship Board](https://aka.ms/azapi/officehours) and the [Azure SDK team](https://eng.ms/docs/products/azure-developer-experience/onboard) first. - [How to manage a single active preview if your service always has some features in preview](./07-perpetual-preview.md) + +## Should I Retain the OpenAPI for an Old Preview API + +It is safe to remove the swagger for an old API version if any of the following is true: + +- The api-version is retired +- The OpenAPI document in the azure-rest-api-specs repo is not needed for RPaaS live validation +- The OpenAPI document in the azure-rest-api-specs repo is not needed for ARM registration + +It is recommended that preview api-versions are set for retirement within 90 days when a preview or stable API is introduced. See the [Azure Retirement Policy](https://aka.ms/AzureRetirementPolicy) and [Azure Retirement Process](https://aka.ms/cpexretirementsprocess) for details. diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md index c857d0de72..256e819f14 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md @@ -4,25 +4,74 @@ llmstxt: true --- When the last api-version in your TypeSpec spec is a preview, adding a new preview version is simply replacing the latest preview version with a new preview version. -This includes: -## Making Changes to your TypeSpec spec +## The Simplest Case: No Stable api-versions + +If your spec is in preview and has not ever had a stable api-version, then there is no need to have versioning decoration in your typespec at all: + +- Change the api-version to match the new api-version + ```diff lang=tsp + enum Versions { + @previewVersion + - `2025-12-01-preview` + + `2026-01-01-preview` + } + ``` +- Remove any versioning decorators +- Make any api changes for the new preview, there is no need to use versioning decoration for this. +- Update the example folder name to match the new api-version + + ```bash + > mv examples/2025-12-01-preview examples/2026-01-01-preview + ``` + +- Update the `api-version` in examples to match the new api-version (search and replace api-version in the examples folder) + + ```diff lang=json + { + "title": "Create a Widget", + "operationId": "Widgets_Create", + "parameters": { + - "api-version": "2025-12-01-preview", + + "api-version": "2026-01-01-preview", + } + } + ``` + +- If you **do not need** to retain the OpenAPI for older previews (see [Should I delete an old preview](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api) if you are not sure). + - Remove the associated OpenAPI file and examples + + ```bash + > rm -r $(2025-12-01-preview) + ``` + + - Remove any references to the old version from README.md + +- Update the README.md to include the new api-version + +## The General Case: One or more Stable Versions Exist + +If there are stable versions before the latest preview version, then you will need to adapt the latest preview version and its decoration for the new preview version. + +This includes the following steps: + +### Making Changes to your TypeSpec spec - Rename the latest preview version to match the new preview version, in all instances in the spec - In vscode, highlight the version name and select `rename symbol` from the context menu to rename the version throughout your spec - In any editor, search and replace the latest preview version in the spec with the new preview version - Update the version value of this version to match the new api-version string, for example: - ~~v2025_12_01_preview: "2025-12-01-preview",~~ - v2026_01_01_preview: "2026-01-01-preview", + ```diff lang=tsp + enum Versions { + @previewVersion + - `2025-12-01-preview`, + + `2026-01-01-preview`, + } + ``` - The new preview version should already be the _last version_ of the versions enum, also ensure it is decorated with `@previewVersion` - Update any mention in documentation of the old api-version to use the new api-version -- Change the name of the `examples` version folder for the latest preview to match the new preview version - - ```bash - > mv examples/2025-12-01-preview examples/2026-01-01-preview - ``` - Make changes to the API description based on how the API has changed between the preview versions (if it has) - If any type that was introduced in the latest preview is _not_ in the new preview, simply delete the type @@ -62,9 +111,28 @@ This includes: - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator. +- Change the name of the `examples` version folder for the latest preview to match the new preview version + + ```bash + > mv examples/2025-12-01-preview examples/2026-01-01-preview + ``` + +- Ensure that examples use the correct api-version (search and replace the api-version for all examples in the folder) + + ```diff lang=json + { + "title": "Create a Widget", + "operationId": "Widgets_Create", + "parameters": { + - "api-version": "2025-12-01-preview", + + "api-version": "2026-01-01-preview", + } + } + ``` + - Add and modify examples to match the api changes -## Preparing a PR into the azure-rest-api-specs repo +### Preparing a PR into the azure-rest-api-specs repo - Navigate to the root directory of the repo in your local fork or clone @@ -93,7 +161,7 @@ This includes: C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . ``` -- If you _don't_ need the older preview version, remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. +- If you _don't_ need the older preview version (see [Should I delete an old preview](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api) if you are not sure), remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. ```bash C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > rm -r 2025-12-01-preview diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md index a98b495121..98c8c85f84 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md @@ -11,7 +11,6 @@ This includes the followign steps: - Add a new entry to the versions enum for the new stable version - Update any mention in documentation of the old api-version to use the new api-version -- Change the name of the `examples` version folder for the latest preview to match the new stable version ```bash > mv examples/2025-10-01-preview examples/2026-01-01 @@ -85,6 +84,21 @@ This includes the followign steps: ``` +- Change the name of the `examples` version folder for the latest preview to match the new stable version + +- Ensure that examples use the correct api-version (search and replace the api-version for all examples in the folder) + + ```diff lang=json + { + "title": "Create a Widget", + "operationId": "Widgets_Create", + "parameters": { + - "api-version": "2025-12-01-preview", + + "api-version": "2026-01-01", + } + } + ``` + - Add and modify examples to match the api changes in the new stable version ## Preparing a PR into the azure-rest-api-specs repo @@ -116,7 +130,7 @@ This includes the followign steps: C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . ``` -- If you _don't_ need the older preview version, remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. +- If you _don't_ need the older preview version (see [Should I delete an old preview](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api) if you are not sure), remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. ```bash C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > rm -r 2025-12-01-preview diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md index 76cfd3cec0..a42ee292f5 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md @@ -14,7 +14,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr ## Creating New Preview and Stable Versions - If the existing preview version is `A`, add the new stable version `A + 1` and the new preview version `A + 2` to the Versions enumeration, ensure that version `A + 2` is decorated with `@previewVersion` from the `Azure.Core` library (and remove that decoration from any other version). -- For all changes from preview version `A` that are part of stable version `A + 1` +- For all changes from preview version `A` that are part of stable version `A + 1`, do the following: - if a new type was added in `A` and is now stable (`@added(T, A)`), add the new decorator `@added(T, A + 1)` ```diff lang=tsp @@ -86,13 +86,14 @@ For some Resource Providers, whenever a new stable version is released, a new pr ``` - Create examples directories for the new stable version (A + 1) and populate them with appropriate examples -- If version A _is not needed_ in the specs repo +- If version A _is not needed_ in the specs repo (see [Should I delete an old preview](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api) if you are not sure) - Remove its example folder ```bash > rm -r examples/2025-10-01-preview ``` + - Remove the OpenAPI spec for version A - Remove all references to version A in `README.md` ## Create A Copy of the Spec for the Stable Version only From 45c05ea357fa454f23cdd807901b7b1fe1f3895e Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 28 Jan 2026 13:09:46 -0800 Subject: [PATCH 14/17] Reordering and title changes --- .../Versioning/{preview-version.md => 01-preview-version.md} | 0 .../docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md | 2 +- .../docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md | 2 +- .../docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md | 2 +- .../docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md | 2 +- .../docs/docs/howtos/Versioning/ARM/06-converting-specs.md | 2 +- 6 files changed, 5 insertions(+), 5 deletions(-) rename website/src/content/docs/docs/howtos/Versioning/{preview-version.md => 01-preview-version.md} (100%) diff --git a/website/src/content/docs/docs/howtos/Versioning/preview-version.md b/website/src/content/docs/docs/howtos/Versioning/01-preview-version.md similarity index 100% rename from website/src/content/docs/docs/howtos/Versioning/preview-version.md rename to website/src/content/docs/docs/howtos/Versioning/01-preview-version.md diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md index 256e819f14..40badfb669 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md @@ -1,5 +1,5 @@ --- -title: Adding a Preview Version when the Last Version was a Preview +title: Adding a Preview Version when the Last Version was Preview llmstxt: true --- diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md index 98c8c85f84..9a49fdbcf3 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md @@ -1,5 +1,5 @@ --- -title: Adding a Stable Version when the Last Version was a Preview +title: Adding a Stable Version when the Last Version was Preview llmstxt: true --- diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md b/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md index e3a206a28a..0931b39076 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md @@ -1,5 +1,5 @@ --- -title: Adding a Preview Version when the Last Version was a Stable Version +title: Adding a Preview Version when the Last Version was Stable llmstxt: true --- diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md b/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md index ecf397977c..1f3ae411f2 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md @@ -1,5 +1,5 @@ --- -title: Adding a Stable Version when the Last Version was a Stable Version +title: Adding a Stable Version when the Last Version was Stable llmstxt: true --- diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md b/website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md index 69706bfdc7..fba888119f 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md @@ -1,5 +1,5 @@ --- -title: Converting Existing Specs with Multiple Previews +title: Converting Existing Specs to Single Active Preview llmstxt: true --- From cdbee3bc72cf5a82dea2d87096ea03ce7eda7676 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 28 Jan 2026 13:21:03 -0800 Subject: [PATCH 15/17] Adding v2 repo details --- .../docs/howtos/Versioning/ARM/01-about-versioning.md | 2 +- .../howtos/Versioning/ARM/02-preview-after-preview.md | 8 ++++---- .../docs/howtos/Versioning/ARM/03-stable-after-preview.md | 6 +++--- .../docs/howtos/Versioning/ARM/04-preview-after-stable.md | 6 +++--- .../docs/howtos/Versioning/ARM/05-stable-after-stable.md | 6 +++--- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md index c284383121..1060c8b2c5 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md @@ -1,5 +1,5 @@ --- -title: About Versioning ARM APIs in the azure-rest-api-specs Repository +title: Introduction llmstxt: true --- diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md index 40badfb669..4ee4c7cc0c 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md @@ -151,20 +151,20 @@ This includes the following steps: - Reinstall dependencies ```bash - C:\repos\azure-rest-api-specs > npm install + C:\repos\azure-rest-api-specs > npm ci ``` - Compile your spec ```bash - C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService > npx tsp compile . ``` - If you _don't_ need the older preview version (see [Should I delete an old preview](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api) if you are not sure), remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. ```bash - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > rm -r 2025-12-01-preview + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\ > rm -r 2025-12-01-preview ``` - If you _do_ need the older preview version, update README.md to include a new entry for the new preview version. diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md index 9a49fdbcf3..f1f85c5461 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/03-stable-after-preview.md @@ -120,14 +120,14 @@ This includes the followign steps: - Reinstall dependencies ```bash - C:\repos\azure-rest-api-specs > npm install + C:\repos\azure-rest-api-specs > npm ci ``` - Compile your spec ```bash - C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService > npx tsp compile . ``` - If you _don't_ need the older preview version (see [Should I delete an old preview](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api) if you are not sure), remove the OpenAPI directory for that version and update the `README.md` file to use the new version instead. diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md b/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md index 0931b39076..c0b37693ed 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/04-preview-after-stable.md @@ -66,14 +66,14 @@ When the latest api-version in your TypeSpec spec is a stable version, adding a - Reinstall dependencies ```bash - C:\repos\azure-rest-api-specs > npm install + C:\repos\azure-rest-api-specs > npm ci ``` - Compile your spec ```bash - C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService > npx tsp compile . ``` - Update README.md to include a new entry for the new preview version. diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md b/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md index 1f3ae411f2..480e04c08b 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/05-stable-after-stable.md @@ -32,14 +32,14 @@ When the latest api-version in your TypeSpec spec is a stable version, adding a - Reinstall dependencies ```bash - C:\repos\azure-rest-api-specs > npm install + C:\repos\azure-rest-api-specs > npm ci ``` - Compile your spec ```bash - C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP - C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile . + C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService + C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService > npx tsp compile . ``` - Update README.md to include a new entry for the new stable version. From 0162d3f5062e5974f72fcdb0e5053c7676bd737e Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 28 Jan 2026 16:14:54 -0800 Subject: [PATCH 16/17] Fix broken links and minor cleanup --- .../howtos/Versioning/ARM/01-about-versioning.md | 2 +- .../Versioning/ARM/02-preview-after-preview.md | 14 ++++++++++---- .../howtos/Versioning/ARM/07-perpetual-preview.md | 6 +++++- 3 files changed, 16 insertions(+), 6 deletions(-) diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md index 1060c8b2c5..ba0bb7dea0 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md @@ -23,7 +23,7 @@ This document describes how to evolve APIs according to these guidelines, and ho - [How to add a new preview version when the last version was stable](./04-preview-after-stable.md) - [How to add a new stable version when the last version was stable](./05-stable-after-stable.md) -This document also describes how to move an existing multi-api typespec spec with multiple previews: +This document also describes how to convert an existing multi-api typespec spec with multiple previews into a spec with a single active preview. Note that this is not required, but it may significantly simplify the versioning decoration in your spec: - [How to convert a spec with multiple preview versions into a spec with a single active preview](./06-converting-specs.md) diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md index 4ee4c7cc0c..c60f119c67 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/02-preview-after-preview.md @@ -42,7 +42,7 @@ If your spec is in preview and has not ever had a stable api-version, then there - Remove the associated OpenAPI file and examples ```bash - > rm -r $(2025-12-01-preview) + > rm -r 2025-12-01-preview ``` - Remove any references to the old version from README.md @@ -73,7 +73,7 @@ This includes the following steps: - The new preview version should already be the _last version_ of the versions enum, also ensure it is decorated with `@previewVersion` - Update any mention in documentation of the old api-version to use the new api-version -- Make changes to the API description based on how the API has changed between the preview versions (if it has) +- Make changes to the API description based on how the API has changed from the last preview version to the new preview version (if it has changed) - If any type that was introduced in the latest preview is _not_ in the new preview, simply delete the type ```diff lang=tsp @@ -88,7 +88,7 @@ This includes the following steps: model Bar {} ``` - - Similarly, if there is any change from the latest preview that does not apply to the new preview version, reverse the decorator (unlikely). + - Similarly, if there is any change from the latest preview that does not apply to the new preview version, reverse the decorator. ```diff lang=tsp - @renamedFrom(Versions.`2026-01-01-preview`, "oldProp") @@ -102,7 +102,13 @@ This includes the following steps: + changedProp: string; ``` - - If any other types are removed in the new preview (unlikely) mark these with an `@removed` decorator referencing the new version + ```diff lang=tsp + - @madeOptional(Versions.`2026-01-01-preview`) + - requiredProp?: string; + + requiredProp: string; + ``` + + - If any other types are removed in the new preview (unlikely, because these would be breaking changes from the previous stable and require a breaking change review) mark these with an `@removed` decorator referencing the new version ```diff lang=tsp + @removed(Versions.`2026-01-01-preview`) diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md index a42ee292f5..c41e63763b 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md @@ -70,9 +70,13 @@ For some Resource Providers, whenever a new stable version is released, a new pr @removed(Versions.`2025-11-01`) + @removed(Versions.`2025-12-01-preview`) goneType: string; + + - @renamedFrom(Versions.`2025-10-01-preview`, "oldName") + + @renamedFrom(Versions.`2025-12-01-preview`, "oldName") + newName: int32; ``` -- Add any new type changes to stable version (A + 1) and decorate appropriately, as shown in the [versioning guide](../versioning.md). Note that these changes should also appear in the new preview (A + 2) +- Add any new type changes to stable version (A + 1) and decorate appropriately, as shown in the [versioning guide](../../ARM/versioning.md). Note that these changes should also appear in the new preview (A + 2) - Remove version `A` from the versions enumeration ```diff lang=tsp From 469075e1c9a6a6d6ff9005169da1b99588be7cb8 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Thu, 29 Jan 2026 16:11:16 -0800 Subject: [PATCH 17/17] Responding to last round of feedback --- .../docs/howtos/Versioning/ARM/01-about-versioning.md | 4 ++-- .../01-converting-specs.md} | 0 .../02-perpetual-preview.md} | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) rename website/src/content/docs/docs/howtos/Versioning/ARM/{06-converting-specs.md => uncommon-scenarios/01-converting-specs.md} (100%) rename website/src/content/docs/docs/howtos/Versioning/ARM/{07-perpetual-preview.md => uncommon-scenarios/02-perpetual-preview.md} (95%) diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md index ba0bb7dea0..6096780508 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/01-about-versioning.md @@ -25,11 +25,11 @@ This document describes how to evolve APIs according to these guidelines, and ho This document also describes how to convert an existing multi-api typespec spec with multiple previews into a spec with a single active preview. Note that this is not required, but it may significantly simplify the versioning decoration in your spec: -- [How to convert a spec with multiple preview versions into a spec with a single active preview](./06-converting-specs.md) +- [How to convert a spec with multiple preview versions into a spec with a single active preview](./uncommon-scenarios/01-converting-specs.md) Additionally, there are some services that may always have features that remain in preview after a stable version is released. This can happen, for example, if there are multiple independent teams that own different resources in a service and operate on their own schedule. The recommended way to handle this scenario is to model your ResourceProvider as multiple services, so each version and the corresponding SDKs can version independently. For some older services, this is not an option, so there is specialized guidance on how to maintain preview features over stable api releases (described below). If you are thinking about splitting your service, or about creating a new preview version with every stable version, be sure to have a discussion with the [Azure API Stewardship Board](https://aka.ms/azapi/officehours) and the [Azure SDK team](https://eng.ms/docs/products/azure-developer-experience/onboard) first. -- [How to manage a single active preview if your service always has some features in preview](./07-perpetual-preview.md) +- [How to manage a single active preview if your service always has some features in preview](./uncommon-scenarios/02-perpetual-preview.md) ## Should I Retain the OpenAPI for an Old Preview API diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md b/website/src/content/docs/docs/howtos/Versioning/ARM/uncommon-scenarios/01-converting-specs.md similarity index 100% rename from website/src/content/docs/docs/howtos/Versioning/ARM/06-converting-specs.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/uncommon-scenarios/01-converting-specs.md diff --git a/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md b/website/src/content/docs/docs/howtos/Versioning/ARM/uncommon-scenarios/02-perpetual-preview.md similarity index 95% rename from website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md rename to website/src/content/docs/docs/howtos/Versioning/ARM/uncommon-scenarios/02-perpetual-preview.md index c41e63763b..432eed1d67 100644 --- a/website/src/content/docs/docs/howtos/Versioning/ARM/07-perpetual-preview.md +++ b/website/src/content/docs/docs/howtos/Versioning/ARM/uncommon-scenarios/02-perpetual-preview.md @@ -76,7 +76,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr newName: int32; ``` -- Add any new type changes to stable version (A + 1) and decorate appropriately, as shown in the [versioning guide](../../ARM/versioning.md). Note that these changes should also appear in the new preview (A + 2) +- Add any new type changes to stable version (A + 1) and decorate appropriately, as shown in the [versioning guide](../../../ARM/versioning.md). Note that these changes should also appear in the new preview (A + 2) - Remove version `A` from the versions enumeration ```diff lang=tsp @@ -90,7 +90,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr ``` - Create examples directories for the new stable version (A + 1) and populate them with appropriate examples -- If version A _is not needed_ in the specs repo (see [Should I delete an old preview](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api) if you are not sure) +- If version A _is not needed_ in the specs repo (see [Should I delete an old preview](../01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api) if you are not sure) - Remove its example folder ```bash @@ -179,8 +179,8 @@ For some Resource Providers, whenever a new stable version is released, a new pr ## Create a PR with the Combined Spec - Do the following with the Original - - Follow the instructions for normalizing decoration in the [converting specifications](./06-converting-specs.md#normalizing-version-decoration-optional) document. This will remove any redundant decoration between the new stable and preview versions (`A + 1` and `A + 2`). - - Add any type changes that are introduced in the new preview and decorate appropriately, following the [versioning guide](../../ARM/versioning.md) + - Follow the instructions for normalizing decoration in the [converting specifications](./01-converting-specs.md#normalizing-version-decoration-optional) document. This will remove any redundant decoration between the new stable and preview versions (`A + 1` and `A + 2`). + - Add any type changes that are introduced in the new preview and decorate appropriately, following the [versioning guide](../../../ARM/versioning.md) - Add a new example folder for the new preview version and populate with appropriate examples. - Compile the spec to produce artifacts (especially the new stable and preview version (`A + 1` and `A + 2` ) apis). - Copy the README.md from copy 1 and add the new preview version to the file.