add ramp_down_current_deployment_name in SetRamping oneof

carlydf · carlydf · commit 6b5ddbed9f70 · 2025-05-01T16:42:40.000-07:00
diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json
@@ -7591,11 +7591,12 @@
           "description": "Deprecated. Use `current`."
         },
         "deploymentVersion": {
-          "$ref": "#/definitions/v1WorkerDeploymentVersion"
+          "$ref": "#/definitions/v1WorkerDeploymentVersion",
+          "description": "The Version you want to set as this Deployment's Current Version.\nSee `RoutingConfig.current_deployment_version` for more details."
         },
-        "unversionedDeploymentName": {
+        "unsetDeploymentName": {
           "type": "string",
-          "title": "The name of the Deployment where you want to set Current Version to unversioned.\nRepresents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)"
+          "description": "The name of the Deployment where you want to unset the Current Version.\nWhen the Current Version is removed from a Deployment, all the task queues\nin that version will have their `TaskQueueVersioningInfo.current_deployment_version`\nset to nil. Until the task queue is added to another deployment, tasks will be\nsent to unversioned workers (or the ramping version, if present)."
         },
         "conflictToken": {
           "type": "string",
@@ -7625,11 +7626,16 @@
           "description": "Deprecated. Use `ramping`."
         },
         "deploymentVersion": {
-          "$ref": "#/definitions/v1WorkerDeploymentVersion"
+          "$ref": "#/definitions/v1WorkerDeploymentVersion",
+          "description": "The Version you want to set as this Deployment's Ramping Version.\nSee `RoutingConfig.ramping_deployment_version` for more details.\nMust always be different from the Current Version."
         },
-        "unversionedDeploymentName": {
+        "unsetDeploymentName": {
           "type": "string",
-          "title": "The name of the Deployment where you want to set Ramping Version to unversioned.\nRepresents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)"
+          "description": "The name of the Deployment where you want to unset the Ramping Version.\nMust be paired with percentage=0."
+        },
+        "rampDownCurrentDeploymentName": {
+          "type": "string",
+          "description": "The name of the Deployment where you want to \"ramp down\" the Current Version\nin order to gradually shift traffic away from this Deployment.\nFor each task queue, the portion of traffic that is shifted \"away\"\nfrom this Deployment will be handled by the task queue's Current Version if present,\nor by unversioned workers if the task queue has no Current Version.\nFor example,\nRamping N% of traffic _from_ outside of this Deployment's scope _to_ a particular Version V in this Deployment:\n  ```\n  current_deployment_version = nil\n  ramping_deployment_version = V\n  ramping_version_percentage = N\n  ```\nRamping N% of traffic _from_ a particular Version V in this Deployment _to_ outside this Deployment's scope:\n  ```\n  current_deployment_version = nil\n  ramping_deployment_version = V\n  ramping_version_percentage = (100 - N)\n  ```\nPassing this field will atomically set:\n  ramping_deployment_version = current_deployment_version\n  current_deployment_version = nil\nfor the specified Worker Deployment."
         },
         "percentage": {
           "type": "number",
@@ -13349,11 +13355,9 @@
           "type": "string",
           "description": "Deprecated. Use `replaced_version`."
         },
-        "deploymentVersion": {
-          "$ref": "#/definitions/v1WorkerDeploymentVersion"
-        },
-        "unversioned": {
-          "type": "boolean"
+        "previousDeploymentVersion": {
+          "$ref": "#/definitions/v1WorkerDeploymentVersion",
+          "description": "The version that was current before executing this operation."
         }
       }
     },
@@ -13369,11 +13373,9 @@
           "type": "string",
           "description": "Deprecated. Use `replaced_version`."
         },
-        "deploymentVersion": {
-          "$ref": "#/definitions/v1WorkerDeploymentVersion"
-        },
-        "unversioned": {
-          "type": "boolean"
+        "previousDeploymentVersion": {
+          "$ref": "#/definitions/v1WorkerDeploymentVersion",
+          "description": "The version that was ramping before executing this operation."
         },
         "previousPercentage": {
           "type": "number",
diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml
@@ -10502,12 +10502,19 @@ components:
           type: string
           description: Deprecated. Use `current`.
         deploymentVersion:
-          $ref: '#/components/schemas/WorkerDeploymentVersion'
-        unversionedDeploymentName:
+          allOf:
+            - $ref: '#/components/schemas/WorkerDeploymentVersion'
+          description: |-
+            The Version you want to set as this Deployment's Current Version.
+             See `RoutingConfig.current_deployment_version` for more details.
+        unsetDeploymentName:
           type: string
           description: |-
-            The name of the Deployment where you want to set Current Version to unversioned.
-             Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
+            The name of the Deployment where you want to unset the Current Version.
+             When the Current Version is removed from a Deployment, all the task queues
+             in that version will have their `TaskQueueVersioningInfo.current_deployment_version`
+             set to nil. Until the task queue is added to another deployment, tasks will be
+             sent to unversioned workers (or the ramping version, if present).
         conflictToken:
           type: string
           description: |-
@@ -10549,10 +10556,10 @@ components:
         previousVersion:
           type: string
           description: Deprecated. Use `replaced_version`.
-        deploymentVersion:
-          $ref: '#/components/schemas/WorkerDeploymentVersion'
-        unversioned:
-          type: boolean
+        previousDeploymentVersion:
+          allOf:
+            - $ref: '#/components/schemas/WorkerDeploymentVersion'
+          description: The version that was current before executing this operation.
     SetWorkerDeploymentRampingVersionRequest:
       type: object
       properties:
@@ -10565,12 +10572,42 @@ components:
           type: string
           description: Deprecated. Use `ramping`.
         deploymentVersion:
-          $ref: '#/components/schemas/WorkerDeploymentVersion'
-        unversionedDeploymentName:
+          allOf:
+            - $ref: '#/components/schemas/WorkerDeploymentVersion'
+          description: |-
+            The Version you want to set as this Deployment's Ramping Version.
+             See `RoutingConfig.ramping_deployment_version` for more details.
+             Must always be different from the Current Version.
+        unsetDeploymentName:
           type: string
           description: |-
-            The name of the Deployment where you want to set Ramping Version to unversioned.
-             Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
+            The name of the Deployment where you want to unset the Ramping Version.
+             Must be paired with percentage=0.
+        rampDownCurrentDeploymentName:
+          type: string
+          description: |-
+            The name of the Deployment where you want to "ramp down" the Current Version
+             in order to gradually shift traffic away from this Deployment.
+             For each task queue, the portion of traffic that is shifted "away"
+             from this Deployment will be handled by the task queue's Current Version if present,
+             or by unversioned workers if the task queue has no Current Version.
+             For example,
+             Ramping N% of traffic _from_ outside of this Deployment's scope _to_ a particular Version V in this Deployment:
+               ```
+               current_deployment_version = nil
+               ramping_deployment_version = V
+               ramping_version_percentage = N
+               ```
+             Ramping N% of traffic _from_ a particular Version V in this Deployment _to_ outside this Deployment's scope:
+               ```
+               current_deployment_version = nil
+               ramping_deployment_version = V
+               ramping_version_percentage = (100 - N)
+               ```
+             Passing this field will atomically set:
+               ramping_deployment_version = current_deployment_version
+               current_deployment_version = nil
+             for the specified Worker Deployment.
         percentage:
           type: number
           description: 'Ramp percentage to set. Valid range: [0,100].'
@@ -10619,10 +10656,10 @@ components:
         previousVersion:
           type: string
           description: Deprecated. Use `replaced_version`.
-        deploymentVersion:
-          $ref: '#/components/schemas/WorkerDeploymentVersion'
-        unversioned:
-          type: boolean
+        previousDeploymentVersion:
+          allOf:
+            - $ref: '#/components/schemas/WorkerDeploymentVersion'
+          description: The version that was ramping before executing this operation.
         previousPercentage:
           type: number
           description: The ramping version percentage before executing this operation.
diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto
@@ -2040,10 +2040,15 @@ message SetWorkerDeploymentCurrentVersionRequest {
 
     // Required.
     oneof current {
+        // The Version you want to set as this Deployment's Current Version.
+        // See `RoutingConfig.current_deployment_version` for more details.
         temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7;
-        // The name of the Deployment where you want to set Current Version to unversioned.
-        // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
-        string unversioned_deployment_name = 8;
+        // The name of the Deployment where you want to unset the Current Version.
+        // When the Current Version is removed from a Deployment, all the task queues
+        // in that version will have their `TaskQueueVersioningInfo.current_deployment_version`
+        // set to nil. Until the task queue is added to another deployment, tasks will be
+        // sent to unversioned workers (or the ramping version, if present).
+        string unset_deployment_name = 8;
     };
     // Optional. This can be the value of conflict_token from a Describe, or another Worker
     // Deployment API. Passing a non-nil conflict token will cause this request to fail if the
@@ -2076,10 +2081,7 @@ message SetWorkerDeploymentCurrentVersionResponse {
     // Deprecated. Use `replaced_version`.
     string previous_version = 2 [deprecated = true];
     // The version that was current before executing this operation.
-    oneof replaced_version {
-        temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 3;
-        bool unversioned = 4;
-    };
+    temporal.api.deployment.v1.WorkerDeploymentVersion previous_deployment_version = 3;
 }
 
 // Set/unset the Ramping Version of a Worker Deployment and its ramp percentage.
@@ -2089,12 +2091,38 @@ message SetWorkerDeploymentRampingVersionRequest {
     string deployment_name = 2 [deprecated = true];
     // Deprecated. Use `ramping`.
     string version = 3 [deprecated = true];
-    // Pass an empty value to unset the Ramping Version. Must be paired with `percentage=0`.
+
     oneof ramping {
+        // The Version you want to set as this Deployment's Ramping Version.
+        // See `RoutingConfig.ramping_deployment_version` for more details.
+        // Must always be different from the Current Version.
         temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 8;
-        // The name of the Deployment where you want to set Ramping Version to unversioned.
-        // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
-        string unversioned_deployment_name = 9;
+        // The name of the Deployment where you want to unset the Ramping Version.
+        // Must be paired with percentage=0.
+        string unset_deployment_name = 9;
+        // The name of the Deployment where you want to "ramp down" the Current Version
+        // in order to gradually shift traffic away from this Deployment.
+        // For each task queue, the portion of traffic that is shifted "away"
+        // from this Deployment will be handled by the task queue's Current Version if present,
+        // or by unversioned workers if the task queue has no Current Version.
+        // For example,
+        // Ramping N% of traffic _from_ outside of this Deployment's scope _to_ a particular Version V in this Deployment:
+        //   ```
+        //   current_deployment_version = nil
+        //   ramping_deployment_version = V
+        //   ramping_version_percentage = N
+        //   ```
+        // Ramping N% of traffic _from_ a particular Version V in this Deployment _to_ outside this Deployment's scope:
+        //   ```
+        //   current_deployment_version = nil
+        //   ramping_deployment_version = V
+        //   ramping_version_percentage = (100 - N)
+        //   ```
+        // Passing this field will atomically set:
+        //   ramping_deployment_version = current_deployment_version
+        //   current_deployment_version = nil
+        // for the specified Worker Deployment.
+        string ramp_down_current_deployment_name = 10;
     };
     // Ramp percentage to set. Valid range: [0,100].
     float percentage = 4;
@@ -2133,10 +2161,7 @@ message SetWorkerDeploymentRampingVersionResponse {
     // Deprecated. Use `replaced_version`.
     string previous_version = 2 [deprecated = true];
     // The version that was ramping before executing this operation.
-    oneof replaced_version {
-        temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 4;
-        bool unversioned = 5;
-    };
+    temporal.api.deployment.v1.WorkerDeploymentVersion previous_deployment_version = 4;
     // The ramping version percentage before executing this operation.
     float previous_percentage = 3;
 }
