Adding a Stable Version when the Last Version was Preview

When the last api-version in your TypeSpec spec is a preview, adding a new stable version means you must remove any preview types or other API changes from the preview and only leave those type changes that are now stable.

This includes the following steps:

Making Changes to your TypeSpec spec

Add a new entry to the versions enum for the new stable version
Update any mention in documentation of the old api-version to use the new api-version
Terminal window
```
> mv examples/2025-10-01-preview examples/2026-01-01
```
Determine which type changes from the latest preview are now stable
- Update the versioning decorators for those changes to reference the new stable version
```
@added(Versions.`2025-10-01-preview`)
@added(Versions.`2026-01-01`)
remainingProperty?: string;
```
- For changes in the latest preview (p) that are not in the new stable version
  - For any type with an @added(p) decorator, delete the type
    @added(Versions.`2025-10-01-preview`) model Foo {}
  - 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
    @typeChangedFrom(Versions.`2025-12-01-preview`, string) property: int32; property: string;
  - For any operation with an @returnTypeChangedFrom(p, ReturnType) decorator, replace the return type with the ReturnType argument and then remove the decorator, for example:
    @returnTypeChangedFrom(Versions.`2025-12-01-preview`, void) move is ArmResourceActionSync(Widget, MoveOptions, MoveResult); move is ArmResourceActionSync(Widget, MoveOptions, void);
  - For any type with an @renamedFrom(p, Name) decorator, replace the name of the type with the Name argument in the decorator and remove the decorator, for example:
    @renamedFrom(Versions.`2025-12-01-preview`, "oldProperty") newProperty: int32; oldProperty: int32;
  - For any property or parameter with a @madeOptional(p) decorator, remove the decorator, and make the property required, for example:
    @madeOptional(Versions.`2025-12-01-preview`) property?: int32; property: int32;
  - For any type with an @removed(p) decorator, remove the decorator
```
@removed( Versions.`2025-12-01-preview`)
property?: string;
```
Model any additional changes in the new stable version and mark with the appropriate versioning decorator, referencing the new stable version

Remove the preview version from the version enum

enum Versions {
 @Azure.Core.previewVersion
 `2025-10-01-preview`,
 `2026-01-01`,
}

Change the name of the examples version folder for the latest preview to match the new stable version

Ensure that examples use the correct api-version (search and replace the api-version for all examples in the folder)

{
  "title": "Create a Widget",
  "operationId": "Widgets_Create",
  "parameters": {
   "api-version": "2025-12-01-preview",
   "api-version": "2026-01-01",
  }
}

Add and modify examples to match the API changes in the new stable version

Preparing a PR into the azure-rest-api-specs repo

Navigate to the root directory of the repo in your local fork or clone

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

C:\repos\azure-rest-api-specs > git fetch upstream main
C:\repos\azure-rest-api-specs > git pull upstream main

Reinstall dependencies
Terminal window
```
C:\repos\azure-rest-api-specs > npm ci
```

Compile your spec

C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService
C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP\MyService > npx tsp compile .

If you don’t need the older preview version (see Should I Retain the OpenAPI for an Old Preview API if you are not sure), remove the OpenAPI directory for that version and update the README.md file to use the new version instead.
Terminal window
```
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 (see Should I Retain the OpenAPI for an Old Preview API if you are not sure):

remove the x-typespec-generated extension from the info section of the OpenAPI file for the preview version:

 "info": {
  "title": "Microsoft.Contoso management service",
  "version": "2021-10-01-preview",
  "description": "Microsoft.Contoso Resource Provider management API.",
  "x-typespec-generated": [
    {
      "emitter": "@azure-tools/typespec-autorest"
    }
  ]
  "description": "Microsoft.Contoso Resource Provider management API."
},

Note that if you do not remove the x-typespec-generated comment, TypeSpec Validation will fail with an error like:

Rule Compile failed

Output folder '..\resource-manager\Microsoft.Contoso' appears to contain TypeSpec-generated swagger files, not generated from the current TypeSpec sources. Perhaps you deleted a version from your TypeSpec, but didn't delete the associated swaggers?

..\resource-manager\Microsoft.Contoso\preview\2021-10-01-preview\contoso.json

update README.md to include a new entry for the new preview version.