From 1e95e40f4cc1ede9bbec4986f76def0d0c907704 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 May 2026 19:02:57 +0000 Subject: [PATCH 1/4] Initial plan From e442edc885c92c1fdedb244c1cee2f882cbf0f07 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 May 2026 19:07:00 +0000 Subject: [PATCH 2/4] Add explicit instructions for reversing complex versioning patterns Add examples for reversing: - @madeRequired decorator in stable-after-preview and preview-after-preview - @returnTypeChangedFrom in preview-after-preview - Property default value changes using @removed/@added/@renamedFrom pattern - Sync-to-async operation template conversions using @removed/@added/@renamedFrom pattern Each reversal includes both ARM and data-plane examples where applicable. Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../Versioning/02-preview-after-preview.md | 66 +++++++++++++++++ .../Versioning/03-stable-after-preview.md | 72 +++++++++++++++++-- 2 files changed, 134 insertions(+), 4 deletions(-) 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 index 9a402ff599..9b91c2394e 100644 --- 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 @@ -106,12 +106,78 @@ This includes the following steps: + changedProp: string; ``` + ```diff lang=tsp + - @returnTypeChangedFrom(Versions.`2026-01-01-preview`, void) + - move is ArmResourceActionSync; + + move is ArmResourceActionSync; + ``` + ```diff lang=tsp - @madeOptional(Versions.`2026-01-01-preview`) - requiredProp?: string; + requiredProp: string; ``` + ```diff lang=tsp + - @madeRequired(Versions.`2026-01-01-preview`) + - requiredProp: string; + + requiredProp?: string; + ``` + + - If a property uses the `@removed`/`@added`/`@renamedFrom` pattern to change a decorator or default value in the latest preview, reverse the pattern by removing both the old and new properties and restoring the original property. For example, if a property added a default value in preview: + + ```diff lang=tsp + model Employee { + - @removed(Versions.`2026-01-01-preview`) + - @renamedFrom(Versions.`2026-01-01-preview`, "level") + - oldLevel: int32; + - + - @added(Versions.`2026-01-01-preview`) + - @encodedName("application/json", "level") + - level: int32 = 1; + + level: int32; + } + ``` + + Here, `level` had a default value of `1` added in the preview. To reverse this, remove both properties (the renamed "old" version and the "new" version with the default) and restore the original property without the default. + + - If an operation uses the `@removed`/`@added`/`@renamedFrom` pattern to convert from synchronous to asynchronous in the latest preview, reverse the pattern by removing both operations and restoring the original synchronous operation. For example (ARM): + + ```diff lang=tsp + @armResourceOperations + interface Employees { + - @removed(Versions.`2026-01-01-preview`) + - @renamedFrom(Versions.`2026-01-01-preview`, "createOrUpdate") + - @sharedRoute + - createOrUpdateV1 is ArmResourceCreateOrReplaceSync; + - + - @added(Versions.`2026-01-01-preview`) + - @sharedRoute + - createOrUpdate is ArmResourceCreateOrReplaceAsync; + + createOrUpdate is ArmResourceCreateOrReplaceSync; + } + ``` + + Similarly for data-plane: + + ```diff lang=tsp + interface Widgets { + - @removed(Versions.`2026-01-01-preview`) + - @renamedFrom(Versions.`2026-01-01-preview`, "createOrReplaceWidget") + - @sharedRoute + - createOrReplaceWidgetV1 is Operations.ResourceCreateOrReplace; + - + - @added(Versions.`2026-01-01-preview`) + - getWidgetOperationStatus is Operations.GetResourceOperationStatus; + - + - @added(Versions.`2026-01-01-preview`) + - @sharedRoute + - @pollingOperation(Widgets.getWidgetOperationStatus) + - createOrReplaceWidget is Operations.LongRunningResourceCreateOrReplace; + + createOrReplaceWidget is Operations.ResourceCreateOrReplace; + } + ``` + - If any other types are removed in the new preview (unlikely, because these would be breaking changes from the previous stable and require a breaking change review) mark these with an `@removed` decorator referencing the new version ```diff lang=tsp 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 index 2e06ba522c..d29c3d8201 100644 --- 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 @@ -65,12 +65,76 @@ This includes the following steps: + property: int32; ``` + - For any property or parameter with a `@madeRequired(p)` decorator, remove the decorator, and make the property optional, for example: + + ```diff lang=tsp + - @madeRequired(Versions.`2025-12-01-preview`) + - property: int32; + + property?: int32; + ``` + - For any type with an `@removed(p)` decorator, remove the decorator - ```diff lang=tsp - - @removed( Versions.`2025-12-01-preview`) - property?: string; - ``` + ```diff lang=tsp + - @removed(Versions.`2025-12-01-preview`) + property?: string; + ``` + + - For any property that uses the `@removed`/`@added`/`@renamedFrom` pattern to change a decorator or default value in the preview, reverse the pattern by removing both the old and new properties and restoring the original property. For example, if a property added a default value in preview: + + ```diff lang=tsp + model Employee { + - @removed(Versions.`2025-12-01-preview`) + - @renamedFrom(Versions.`2025-12-01-preview`, "level") + - oldLevel: int32; + - + - @added(Versions.`2025-12-01-preview`) + - @encodedName("application/json", "level") + - level: int32 = 1; + + level: int32; + } + ``` + + Here, `level` had a default value of `1` added in the preview. To reverse this, remove both properties (the renamed "old" version and the "new" version with the default) and restore the original property without the default. + + - For any operation that uses the `@removed`/`@added`/`@renamedFrom` pattern to convert from synchronous to asynchronous in preview, reverse the pattern by removing both operations and restoring the original synchronous operation. For example (ARM): + + ```diff lang=tsp + @armResourceOperations + interface Employees { + - @removed(Versions.`2025-12-01-preview`) + - @renamedFrom(Versions.`2025-12-01-preview`, "createOrUpdate") + - @sharedRoute + - createOrUpdateV1 is ArmResourceCreateOrReplaceSync; + - + - @added(Versions.`2025-12-01-preview`) + - @sharedRoute + - createOrUpdate is ArmResourceCreateOrReplaceAsync; + + createOrUpdate is ArmResourceCreateOrReplaceSync; + } + ``` + + Here the operation was converted from `ArmResourceCreateOrReplaceSync` to `ArmResourceCreateOrReplaceAsync` in preview. To reverse this, remove both the old renamed operation and the new async operation, and restore the original synchronous operation. + + Similarly for data-plane: + + ```diff lang=tsp + interface Widgets { + - @removed(Versions.`2025-12-01-preview`) + - @renamedFrom(Versions.`2025-12-01-preview`, "createOrReplaceWidget") + - @sharedRoute + - createOrReplaceWidgetV1 is Operations.ResourceCreateOrReplace; + - + - @added(Versions.`2025-12-01-preview`) + - getWidgetOperationStatus is Operations.GetResourceOperationStatus; + - + - @added(Versions.`2025-12-01-preview`) + - @sharedRoute + - @pollingOperation(Widgets.getWidgetOperationStatus) + - createOrReplaceWidget is Operations.LongRunningResourceCreateOrReplace; + + createOrReplaceWidget is Operations.ResourceCreateOrReplace; + } + ``` - 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 From 6037b55916e86b4ce4ad027c06ee8fc52caef110 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 May 2026 19:07:42 +0000 Subject: [PATCH 3/4] Clarify decorator/default value reversal instructions with cross-reference Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../docs/docs/howtos/Versioning/02-preview-after-preview.md | 2 +- .../docs/docs/howtos/Versioning/03-stable-after-preview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 index 9b91c2394e..c6b50767b6 100644 --- 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 @@ -124,7 +124,7 @@ This includes the following steps: + requiredProp?: string; ``` - - If a property uses the `@removed`/`@added`/`@renamedFrom` pattern to change a decorator or default value in the latest preview, reverse the pattern by removing both the old and new properties and restoring the original property. For example, if a property added a default value in preview: + - If a property uses the `@removed`/`@added`/`@renamedFrom` pattern to change decoration or a default value in the latest preview (see [Adding Decoration to an Existing Type](./06-evolving-apis.md#adding-decoration-to-an-existing-type)), reverse the pattern by removing both the old and new properties and restoring the original property. For example, if a property added a default value in preview: ```diff lang=tsp model Employee { 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 index d29c3d8201..f39da3c814 100644 --- 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 @@ -80,7 +80,7 @@ This includes the following steps: property?: string; ``` - - For any property that uses the `@removed`/`@added`/`@renamedFrom` pattern to change a decorator or default value in the preview, reverse the pattern by removing both the old and new properties and restoring the original property. For example, if a property added a default value in preview: + - For any property that uses the `@removed`/`@added`/`@renamedFrom` pattern to change decoration or a default value in the preview (see [Adding Decoration to an Existing Type](./06-evolving-apis.md#adding-decoration-to-an-existing-type)), reverse the pattern by removing both the old and new properties and restoring the original property. For example, if a property added a default value in preview: ```diff lang=tsp model Employee { From 2bccf4d30cff54d0708be7b45daffa1683744658 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 27 May 2026 20:24:41 +0000 Subject: [PATCH 4/4] Remove @returnTypeChangedFrom example and @encodedName from examples per review - Remove @returnTypeChangedFrom reversal example (only usable for simple operations) - Remove @encodedName decorator from default value reversal examples Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../docs/howtos/Versioning/02-preview-after-preview.md | 7 ------- .../docs/docs/howtos/Versioning/03-stable-after-preview.md | 1 - 2 files changed, 8 deletions(-) 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 index c6b50767b6..61ea75f639 100644 --- 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 @@ -106,12 +106,6 @@ This includes the following steps: + changedProp: string; ``` - ```diff lang=tsp - - @returnTypeChangedFrom(Versions.`2026-01-01-preview`, void) - - move is ArmResourceActionSync; - + move is ArmResourceActionSync; - ``` - ```diff lang=tsp - @madeOptional(Versions.`2026-01-01-preview`) - requiredProp?: string; @@ -133,7 +127,6 @@ This includes the following steps: - oldLevel: int32; - - @added(Versions.`2026-01-01-preview`) - - @encodedName("application/json", "level") - level: int32 = 1; + level: int32; } 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 index f39da3c814..dc5b954e2e 100644 --- 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 @@ -89,7 +89,6 @@ This includes the following steps: - oldLevel: int32; - - @added(Versions.`2025-12-01-preview`) - - @encodedName("application/json", "level") - level: int32 = 1; + level: int32; }