From 29afa81f97f4cf48cfd13643191e93db1349a2c0 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 20 Jan 2026 13:11:01 -0800 Subject: [PATCH 01/10] 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 085ac76aa5b71c3f610d7332c410ea751a777d58 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 20 Jan 2026 17:57:12 -0800 Subject: [PATCH 02/10] 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 2aee9d140aad488dc7155d9663271eb1647112b9 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 20 Jan 2026 18:39:12 -0800 Subject: [PATCH 03/10] 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 8ffab2058d33ce39855100b64bb5bd08b6edcda7 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Tue, 20 Jan 2026 18:55:46 -0800 Subject: [PATCH 04/10] 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 ddddea1c60ceecdbc8eb6de62c5eef6ea0ee7ccd Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 21 Jan 2026 16:29:29 -0800 Subject: [PATCH 05/10] 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 d91270d684161404fa9d96c3b5ef5e11aa01dc56 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 21 Jan 2026 17:40:02 -0800 Subject: [PATCH 06/10] 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 55603ddec9a07e611118f79cded61851eb3b62dd Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 21 Jan 2026 17:47:22 -0800 Subject: [PATCH 07/10] 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 081cfc9232d4b73d6fbff8da06051e94286f472d Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Wed, 21 Jan 2026 17:50:11 -0800 Subject: [PATCH 08/10] 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 d31195dab24442c7ceab662de59fc527e9b55e89 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Thu, 22 Jan 2026 13:56:26 -0800 Subject: [PATCH 09/10] 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 78ab8ff9d8421494bb0c1c2ca68012bf5e4836f7 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Thu, 22 Jan 2026 14:02:57 -0800 Subject: [PATCH 10/10] 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