Deprecate Versioning APIs previous_* response fields (#669)

ShahabT · web-flow · commit a22489c7e89f · 2025-11-25T09:52:06.000-08:00
_**READ BEFORE MERGING:** All PRs require approval by both Server AND
SDK teams before merging! This is why the number of required approvals
is "2" and not "1"--two reviewers from the same team is NOT sufficient.
If your PR is not approved by someone in BOTH teams, it may be summarily
reverted._

&lt;!-- Describe what has changed in this PR --&gt;
Deprecating the following fields in favor of API idempotency.
-
`SetWorkerDeploymentCurrentVersionResponse.previous_deployment_version`
-
`SetWorkerDeploymentRampingVersionResponse.previous_deployment_version`
- `SetWorkerDeploymentRampingVersionResponse.previous_percentage`
- `SetWorkerDeploymentManagerResponse.previous_manager_identity`

&lt;!-- Tell your future self why have you made these changes --&gt;
The fields do not fit well with these idempotent APIs. They will return
invalid results when the API is retried by server or client.

Users who need this info can use `DescribeWorkerDeployment` before
calling this the `Set*` APIs. By passing the `conflict_token` got from
the `DescribeWorkerDeployment` call to the Set API they can ensure there
is no interfering changes between the two calls.

&lt;!-- Are there any breaking changes on binary or code level? --&gt;
**Breaking changes**
These fields are deprecated and will stop being populated sometime after
Versioning GA.

&lt;!-- If this breaks the Server, please provide the Server PR to merge
right after this PR was merged. --&gt;
**Server PR**
No server change.
diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json
@@ -14753,7 +14753,7 @@
         },
         "previousDeploymentVersion": {
           "$ref": "#/definitions/v1WorkerDeploymentVersion",
-          "description": "The version that was current before executing this operation."
+          "description": "The version that was current before executing this operation.\nDeprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the\nCurrent version info before calling this API. By passing the `conflict_token` got from the\n`DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes\nbetween the two calls."
         }
       }
     },
@@ -14767,7 +14767,7 @@
         },
         "previousManagerIdentity": {
           "type": "string",
-          "description": "What the `manager_identity` field was before this change."
+          "description": "What the `manager_identity` field was before this change.\nDeprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the\nmanager identity before calling this API. By passing the `conflict_token` got from the\n`DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes\nbetween the two calls."
         }
       }
     },
@@ -14785,12 +14785,12 @@
         },
         "previousDeploymentVersion": {
           "$ref": "#/definitions/v1WorkerDeploymentVersion",
-          "description": "The version that was ramping before executing this operation."
+          "description": "The version that was ramping before executing this operation.\nDeprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the\nRamping version info before calling this API. By passing the `conflict_token` got from the\n`DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes\nbetween the two calls."
         },
         "previousPercentage": {
           "type": "number",
           "format": "float",
-          "description": "The ramping version percentage before executing this operation."
+          "description": "The ramping version percentage before executing this operation.\nDeprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the\nRamping version info before calling this API. By passing the `conflict_token` got from the\n`DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes\nbetween the two calls."
         }
       }
     },
diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml
@@ -11673,7 +11673,12 @@ components:
         previousDeploymentVersion:
           allOf:
             - $ref: '#/components/schemas/WorkerDeploymentVersion'
-          description: The version that was current before executing this operation.
+          description: |-
+            The version that was current before executing this operation.
+             Deprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the
+             Current version info before calling this API. By passing the `conflict_token` got from the
+             `DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes
+             between the two calls.
     SetWorkerDeploymentManagerRequest:
       type: object
       properties:
@@ -11713,7 +11718,12 @@ components:
           format: bytes
         previousManagerIdentity:
           type: string
-          description: What the `manager_identity` field was before this change.
+          description: |-
+            What the `manager_identity` field was before this change.
+             Deprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the
+             manager identity before calling this API. By passing the `conflict_token` got from the
+             `DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes
+             between the two calls.
     SetWorkerDeploymentRampingVersionRequest:
       type: object
       properties:
@@ -11787,10 +11797,20 @@ components:
         previousDeploymentVersion:
           allOf:
             - $ref: '#/components/schemas/WorkerDeploymentVersion'
-          description: The version that was ramping before executing this operation.
+          description: |-
+            The version that was ramping before executing this operation.
+             Deprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the
+             Ramping version info before calling this API. By passing the `conflict_token` got from the
+             `DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes
+             between the two calls.
         previousPercentage:
           type: number
-          description: The ramping version percentage before executing this operation.
+          description: |-
+            The ramping version percentage before executing this operation.
+             Deprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the
+             Ramping version info before calling this API. By passing the `conflict_token` got from the
+             `DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes
+             between the two calls.
           format: float
     SignalExternalWorkflowExecutionFailedEventAttributes:
       type: object
diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto
@@ -2178,7 +2178,11 @@ message SetWorkerDeploymentCurrentVersionResponse {
     // Deprecated. Use `previous_deployment_version`.
     string previous_version = 2 [deprecated = true];
     // The version that was current before executing this operation.
-    temporal.api.deployment.v1.WorkerDeploymentVersion previous_deployment_version = 3;
+    // Deprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the
+    // Current version info before calling this API. By passing the `conflict_token` got from the
+    // `DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes
+    // between the two calls.
+    temporal.api.deployment.v1.WorkerDeploymentVersion previous_deployment_version = 3 [deprecated = true];
 }
 
 // Set/unset the Ramping Version of a Worker Deployment and its ramp percentage.
@@ -2234,9 +2238,17 @@ message SetWorkerDeploymentRampingVersionResponse {
     // Deprecated. Use `previous_deployment_version`.
     string previous_version = 2 [deprecated = true];
     // The version that was ramping before executing this operation.
-    temporal.api.deployment.v1.WorkerDeploymentVersion previous_deployment_version = 4;
+    // Deprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the
+    // Ramping version info before calling this API. By passing the `conflict_token` got from the
+    // `DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes
+    // between the two calls.
+    temporal.api.deployment.v1.WorkerDeploymentVersion previous_deployment_version = 4 [deprecated = true];
     // The ramping version percentage before executing this operation.
-    float previous_percentage = 3;
+    // Deprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the
+    // Ramping version info before calling this API. By passing the `conflict_token` got from the
+    // `DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes
+    // between the two calls.
+    float previous_percentage = 3 [deprecated = true];
 }
 
 message ListWorkerDeploymentsRequest {
@@ -2349,7 +2361,11 @@ message SetWorkerDeploymentManagerResponse {
     bytes conflict_token = 1;
 
     // What the `manager_identity` field was before this change.
-    string previous_manager_identity = 2;
+    // Deprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the
+    // manager identity before calling this API. By passing the `conflict_token` got from the
+    // `DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes
+    // between the two calls.
+    string previous_manager_identity = 2 [deprecated = true];
 }
 
 // Returns the Current Deployment of a deployment series.

Original file line number	Diff line number	Diff line change
`@@ -14753,7 +14753,7 @@`
`14753`	`14753`	`},`
`14754`	`14754`	`"previousDeploymentVersion": {`
`14755`	`14755`	`"$ref": "#/definitions/v1WorkerDeploymentVersion",`
`14756`		`- "description": "The version that was current before executing this operation."`
	`14756`	+ "description": "The version that was current before executing this operation.\nDeprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the\nCurrent version info before calling this API. By passing the `conflict_token` got from the\n`DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes\nbetween the two calls."
`14757`	`14757`	`}`
`14758`	`14758`	`}`
`14759`	`14759`	`},`
`@@ -14767,7 +14767,7 @@`
`14767`	`14767`	`},`
`14768`	`14768`	`"previousManagerIdentity": {`
`14769`	`14769`	`"type": "string",`
`14770`		- "description": "What the `manager_identity` field was before this change."
	`14770`	+ "description": "What the `manager_identity` field was before this change.\nDeprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the\nmanager identity before calling this API. By passing the `conflict_token` got from the\n`DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes\nbetween the two calls."
`14771`	`14771`	`}`
`14772`	`14772`	`}`
`14773`	`14773`	`},`
`@@ -14785,12 +14785,12 @@`
`14785`	`14785`	`},`
`14786`	`14786`	`"previousDeploymentVersion": {`
`14787`	`14787`	`"$ref": "#/definitions/v1WorkerDeploymentVersion",`
`14788`		`- "description": "The version that was ramping before executing this operation."`
	`14788`	+ "description": "The version that was ramping before executing this operation.\nDeprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the\nRamping version info before calling this API. By passing the `conflict_token` got from the\n`DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes\nbetween the two calls."
`14789`	`14789`	`},`
`14790`	`14790`	`"previousPercentage": {`
`14791`	`14791`	`"type": "number",`
`14792`	`14792`	`"format": "float",`
`14793`		`- "description": "The ramping version percentage before executing this operation."`
	`14793`	+ "description": "The ramping version percentage before executing this operation.\nDeprecated in favor of idempotency of the API. Use `DescribeWorkerDeployment` to get the\nRamping version info before calling this API. By passing the `conflict_token` got from the\n`DescribeWorkerDeployment` call to this API you can ensure there is no interfering changes\nbetween the two calls."
`14794`	`14794`	`}`
`14795`	`14795`	`}`
`14796`	`14796`	`},`