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..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 @@ -112,6 +112,65 @@ This includes the following steps: + 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 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 { + - @removed(Versions.`2026-01-01-preview`) + - @renamedFrom(Versions.`2026-01-01-preview`, "level") + - oldLevel: int32; + - + - @added(Versions.`2026-01-01-preview`) + - 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..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 @@ -65,12 +65,75 @@ 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 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 { + - @removed(Versions.`2025-12-01-preview`) + - @renamedFrom(Versions.`2025-12-01-preview`, "level") + - oldLevel: int32; + - + - @added(Versions.`2025-12-01-preview`) + - 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