Add detailed versioning docs for single preview

website/src/content/docs/docs/howtos/ARM/versioning/01-about-versioning.md

@@ -0,0 +1,30 @@
+---
+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 _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:
+
+- RPaaS live validation support
+- ARM registration support
+
+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)
+- [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 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)

website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md

@@ -0,0 +1,62 @@
+---
+title: Adding a Preview Version when the Last Version was a Preview
+---
+
+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
+
+- 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",
+
+- 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 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
+
+## 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-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-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.

website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md

@@ -0,0 +1,110 @@
+---
+title: Adding a Stable Version when the Last Version was a Preview
+---
+
+When the last api-version in your TypeSpec spec is a preview, adding a new stable version means
+
+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
+- 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 (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;
+      ```
+
+      should be changed to:
+
+      ```tsp
+      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);
+      ```
+
+    - 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;
+      ```
+
+      should be changed to:
+
+      ```tsp
+      oldProperty: int32;
+      ```
+
+    - 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)
+      property?: int32;
+      ```
+
+      should be changed to:
+
+      ```tsp
+      property: int32;
+      ```
+
+    - 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
+
+- 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 .
+  ```
+
+- 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.

website/src/content/docs/docs/howtos/ARM/versioning/04-preview-after-stable.md

@@ -0,0 +1,45 @@
+---
+title: Adding a Preview Version when the Last Version was a Stable Version
+---
+
+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
+
+- 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
+- Create a new examples folder for the new version `examples\<version>` 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.

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 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 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
+- Create a new examples folder for the new version `examples\<version>` 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.