Address review: use Trait templates, add @pollingOperation, add @madeRequired section, apply suggestions, remove data-plane examples

Copilot · markcowl · web-flow · commit 2e94dc2fe7ed · 2026-04-14T02:22:25.000Z
Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/56c71242-0384-4237-b485-c9d866377d88 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>
diff --git a/website/src/content/docs/docs/getstarted/versioning.md b/website/src/content/docs/docs/getstarted/versioning.md
@@ -109,16 +109,14 @@ interface Employees {
 interface Widgets {
   getWidget is Operations.ResourceRead<
     Widget,
-    Traits = {
-      parameters: {
-        @query
-        name: string;
-
-        @added(Versions.v2)
-        @query
-        department?: string;
-      };
-    }
+    QueryParametersTrait<{
+      @query
+      name: string;
+
+      @added(Versions.v2)
+      @query
+      department?: string;
+    }>
   >;
 }
 ```
diff --git a/website/src/content/docs/docs/howtos/Versioning/02-preview-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/02-preview-after-preview.md
@@ -174,54 +174,3 @@ This includes the following steps:
   ```
 
 - If you _do_ need the older preview version (see [Should I Retain the OpenAPI for an Old Preview API](./01-about-versioning.md#should-i-retain-the-openapi-for-an-old-preview-api-arm-only) if you are not sure), update README.md to include a new entry for the new preview version.
-
-## Data-Plane Example
-
-In the following example, we introduce a new preview version called `v3Preview` which includes everything from `v2` plus adds a new property to the `Widget` resource.
-
-```diff lang=tsp
-import "@typespec/http";
-import "@typespec/rest";
-import "@typespec/versioning";
-import "@azure-tools/typespec-azure-core";
-
-using Http;
-using Rest;
-using Versioning;
-using Azure.Core;
-
-
-@versioned(Versions)
-@service(#{ title: "Widget Service" })
-namespace DemoService;
-
-enum Versions {
-  v1,
-  v2,
-+  @previewVersion
-+  v3Preview
-}
-
-/**
- * Model defining the Widget resource
- */
-model Widget {
-  /**
-   * Identifier of the Widget Resource
-   */
-  @visibility(Lifecycle.Read)
-  @key id: string;
-  /**
-   * Weight of the widget
-   */
-  weight: int32;
-  /**
-   * Color of the widget;
-   */
-  color: "red" | "blue";
-  /**
-   * Nickname of the Widget resource
-   */
-+  @added(Versions.v3Preview) nickname: string;
-}
-```
diff --git a/website/src/content/docs/docs/howtos/Versioning/03-stable-after-preview.md b/website/src/content/docs/docs/howtos/Versioning/03-stable-after-preview.md
@@ -164,56 +164,3 @@ This includes the following steps:
     ```
 
   - update README.md to include a new entry for the new preview version.
-
-## Data-Plane Example
-
-This example builds on the data-plane preview version example in [Adding a Preview Version when the Last Version was Preview](./02-preview-after-preview.md#data-plane-example), where `v3` is introduced which GA's the `nickname` property introduced in `v3Preview`.
-
-```diff lang=tsp
-import "@typespec/http";
-import "@typespec/rest";
-import "@typespec/versioning";
-import "@azure-tools/typespec-azure-core";
-
-using Http;
-using Rest;
-using Versioning;
-using Azure.Core;
-
-
-@versioned(Versions)
-@service(#{ title: "Widget Service" })
-namespace DemoService;
-
-enum Versions {
-  v1,
-  v2,
--  @previewVersion
--  v3Preview
-+  v3
-}
-
-/**
- * Model defining the Widget resource
- */
-model Widget {
-  /**
-   * Identifier of the Widget Resource
-   */
-  @visibility(Lifecycle.Read)
-  @key id: string;
-  /**
-   * Weight of the widget
-   */
-  weight: int32;
-  /**
-   * Color of the widget;
-   */
-  color: "red" | "blue";
-  /**
-   * Nickname of the Widget resource
-   */
--  @added(Versions.v3Preview) nickname: string;
-+  @added(Versions.v3) nickname: string;
-}
-```
diff --git a/website/src/content/docs/docs/howtos/Versioning/06-evolving-apis.md b/website/src/content/docs/docs/howtos/Versioning/06-evolving-apis.md
@@ -129,16 +129,14 @@ interface Employees {
 interface Widgets {
   getWidget is Operations.ResourceRead<
     Widget,
-    Traits = {
-      parameters: {
-        @query
-        name: string;
+    QueryParametersTrait<{
+      @query
+      name: string;
 
-        @added(Versions.v2)
-        @query
-        department?: string;
-      };
-    }
+      @added(Versions.v2)
+      @query
+      department?: string;
+    }>
   >;
 }
 ```
@@ -229,12 +227,10 @@ interface Employees {
 interface Widgets {
   listWidgets is Operations.ResourceList<
     Widget,
-    Traits = {
-      parameters: {
-        @header
-        location: string;
-      };
-    }
+    RequestHeadersTrait<{
+      @header
+      location: string;
+    }>
   >;
 }
 ```
@@ -272,17 +268,16 @@ interface Employees {
 interface Widgets {
   listWidgets is Operations.ResourceList<
     Widget,
-    Traits = {
-      parameters: {
-        @madeOptional(Versions.v2)
-        @header
-        location?: string;
-
+    RequestHeadersTrait<{
+      @madeOptional(Versions.v2)
+      @header
+      location?: string;
+    }> &
+      QueryParametersTrait<{
         @added(Versions.v2)
         @query("order-by")
         orderBy?: string;
-      };
-    }
+      }>
   >;
 }
 ```
@@ -342,8 +337,12 @@ interface Widgets {
   @sharedRoute
   createOrReplaceWidgetV1 is Operations.ResourceCreateOrReplace<Widget>;
 
+  @added(Versions.v2)
+  getWidgetOperationStatus is Operations.GetResourceOperationStatus<Widget, never>;
+
   @added(Versions.v2)
   @sharedRoute
+  @pollingOperation(Widgets.getWidgetOperationStatus)
   createOrReplaceWidget is Operations.LongRunningResourceCreateOrReplace<Widget>;
 }
 ```
@@ -354,6 +353,7 @@ interface Widgets {
 - `@renamedFrom(Versions.v2, "createOrUpdate")` keeps the original name for v1.
 - `@added(Versions.v2)` adds the new asynchronous operation in v2 and later.
 - `@sharedRoute` ensures both operations can use the same route.
+- `@pollingOperation` links the long-running operation to its status monitor endpoint (data-plane only).
 
 ## Versioning Decorators
 
diff --git a/website/src/content/docs/docs/howtos/Versioning/uncommon-scenarios/01-converting-specs.md b/website/src/content/docs/docs/howtos/Versioning/uncommon-scenarios/01-converting-specs.md
@@ -99,6 +99,19 @@ Normalizing version decoration consists of removing redundant decorators and fol
     nowOptional?: string;
   ```
 
+## `@madeRequired(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 `@madeRequired` decorators referencing the immediate successor version, remove them.
+- Change `@madeRequired(T, u)` to `@madeRequired(T, u + 1)`
+
+  ```diff lang=tsp
+  - @madeRequired(Versions.`2025-10-01-preview`)
+  + @madeRequired(Versions.`2025-11-01`)
+    nowRequired: string;
+  ```
+
 ## `@added(T, u)` decorator
 
 - Based on the version referenced in the decorator, determine the immediate successor version `u + 1`
diff --git a/website/src/content/docs/docs/howtos/Versioning/uncommon-scenarios/02-perpetual-preview.md b/website/src/content/docs/docs/howtos/Versioning/uncommon-scenarios/02-perpetual-preview.md
@@ -1,10 +1,10 @@
 ---
-title: "ARM: Managing a Single Active Preview with Perpetual Preview Features"
+title: "ARM: Managing a Single Active Preview When Some Features Always Remain in Preview"
 llmstxt: true
 ---
 
 :::note
-This document applies specifically to **Azure Resource Manager (ARM) APIs**. Data plane services should follow the [general versioning guidance](../01-about-versioning.md).
+This document applies specifically to **Azure Resource Manager (ARM) APIs**. Data plane services should not allow versions to remain in preview across stable releases.
 :::
 
 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:
@@ -80,7 +80,7 @@ For some Resource Providers, whenever a new stable version is released, a new pr
     newName: int32;
   ```
 
-- Add any new type changes to stable version (A + 1) and decorate appropriately, as shown in the [versioning guide](../06-evolving-apis.md). Note that these changes should also appear in the new preview (A + 2)
+- Add any new type changes to stable version (A + 1) and decorate appropriately, as shown in the [versioning guide](../06-evolving-apis.md). Note that these changes will also appear in the new preview (A + 2)
 - Remove version `A` from the versions enumeration
 
   ```diff lang=tsp
