Evolve documentation of update polling parameters

Author: dandavison

openapi/openapiv2.json

@@ -3457,7 +3457,7 @@
         },
         "waitPolicy": {
           "$ref": "#/definitions/v1WaitPolicy",
-          "description": "Describes when this request should return - basically whether the\nupdate is synchronous, asynchronous, or somewhere in between."
+          "description": "How long to wait before returning control to the caller."
         },
         "request": {
           "type": "object",
@@ -6775,7 +6775,7 @@
         },
         "stage": {
           "$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage",
-          "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nUNSPECIFIED will be returned if and only if the server's maximum wait\ntime was reached before the Update reached the stage specified in the\nrequest WaitPolicy, and before the context deadline expired; clients may\nmay then retry the call as needed."
+          "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nIf the server's maximum wait time was reached before the stage requested by the client, then\nthe returned stage may be less than the requested stage. Clients may then retry the call as\nneeded."
         },
         "updateRef": {
           "$ref": "#/definitions/v1UpdateRef",
@@ -8907,7 +8907,7 @@
         },
         "waitPolicy": {
           "$ref": "#/definitions/v1WaitPolicy",
-          "description": "Describes when this request should return - basically whether the\nupdate is synchronous, asynchronous, or somewhere in between."
+          "description": "How long to wait before returning control to the caller."
         },
         "request": {
           "$ref": "#/definitions/apiupdatev1Request",
@@ -8928,7 +8928,7 @@
         },
         "stage": {
           "$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage",
-          "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nUNSPECIFIED will be returned if and only if the server's maximum wait\ntime was reached before the Update reached the stage specified in the\nrequest WaitPolicy, and before the context deadline expired; clients may\nmay then retry the call as needed."
+          "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nIf the server's maximum wait time was reached before the stage requested by the client, then\nthe returned stage may be less than the requested stage. Clients may then retry the call as\nneeded."
         }
       }
     },
@@ -8984,10 +8984,10 @@
       "properties": {
         "lifecycleStage": {
           "$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage",
-          "description": "Indicates the update lifecycle stage that the gRPC call should wait for\nbefore returning."
+          "description": "The update stage that this request should attempt to wait for."
         }
       },
-      "description": "Specifies to the gRPC server how long the client wants the an update-related\nRPC call to wait before returning control to the caller."
+      "description": "How long the client wants an update-related RPC call to wait before returning control to the caller."
     },
     "v1WorkerVersionCapabilities": {
       "type": "object",

openapi/openapiv3.yaml

@@ -6648,9 +6648,7 @@ components:
         waitPolicy:
           allOf:
             - $ref: '#/components/schemas/WaitPolicy'
-          description: |-
-            Describes when this request should return - basically whether the
-             update is synchronous, asynchronous, or somewhere in between.
+          description: How long to wait before returning control to the caller.
         request:
           allOf:
             - $ref: '#/components/schemas/Request'
@@ -6684,14 +6682,12 @@ components:
           description: |-
             The most advanced lifecycle stage that the Update is known to have
              reached, where lifecycle stages are ordered
-             UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <
              UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <
              UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <
              UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.
-             UNSPECIFIED will be returned if and only if the server's maximum wait
-             time was reached before the Update reached the stage specified in the
-             request WaitPolicy, and before the context deadline expired; clients may
-             may then retry the call as needed.
+             If the server's maximum wait time was reached before the stage requested by the client, then
+             the returned stage may be less than the requested stage. Clients may then retry the call as
+             needed.
           format: enum
     UpsertWorkflowSearchAttributesEventAttributes:
       type: object
@@ -6728,13 +6724,9 @@ components:
             - UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED
             - UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED
           type: string
-          description: |-
-            Indicates the update lifecycle stage that the gRPC call should wait for
-             before returning.
+          description: The update stage that this request should attempt to wait for.
           format: enum
-      description: |-
-        Specifies to the gRPC server how long the client wants the an update-related
-         RPC call to wait before returning control to the caller.
+      description: How long the client wants an update-related RPC call to wait before returning control to the caller.
     WorkerVersionCapabilities:
       type: object
       properties:

temporal/api/update/v1/message.proto

@@ -35,12 +35,9 @@ import "temporal/api/common/v1/message.proto";
 import "temporal/api/enums/v1/update.proto";
 import "temporal/api/failure/v1/message.proto";
 
-// Specifies to the gRPC server how long the client wants the an update-related
-// RPC call to wait before returning control to the caller.
+// How long the client wants an update-related RPC call to wait before returning control to the caller.
 message WaitPolicy {
-
-    // Indicates the update lifecycle stage that the gRPC call should wait for
-    // before returning.
+    // The update stage that this request should attempt to wait for.
     temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage lifecycle_stage = 1;
 }
 

temporal/api/workflowservice/v1/request_response.proto

@@ -1389,8 +1389,7 @@ message UpdateWorkflowExecutionRequest {
     // part of the same execution chain as this id.
     string first_execution_run_id = 3;
 
-    // Describes when this request should return - basically whether the
-    // update is synchronous, asynchronous, or somewhere in between.
+    // How long to wait before returning control to the caller.
     temporal.api.update.v1.WaitPolicy wait_policy = 4;
 
     // The request information that will be delivered all the way down to the
@@ -1409,14 +1408,12 @@ message UpdateWorkflowExecutionResponse {
 
     // The most advanced lifecycle stage that the Update is known to have
     // reached, where lifecycle stages are ordered
-    // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.
-    // UNSPECIFIED will be returned if and only if the server's maximum wait
-    // time was reached before the Update reached the stage specified in the
-    // request WaitPolicy, and before the context deadline expired; clients may
-    // may then retry the call as needed.
+    // If the server's maximum wait time was reached before the stage requested by the client, then
+    // the returned stage may be less than the requested stage. Clients may then retry the call as
+    // needed.
     temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage stage = 3;
 }
 
@@ -1535,14 +1532,12 @@ message PollWorkflowExecutionUpdateResponse {
     temporal.api.update.v1.Outcome outcome = 1;
     // The most advanced lifecycle stage that the Update is known to have
     // reached, where lifecycle stages are ordered
-    // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <
     // UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.
-    // UNSPECIFIED will be returned if and only if the server's maximum wait
-    // time was reached before the Update reached the stage specified in the
-    // request WaitPolicy, and before the context deadline expired; clients may
-    // may then retry the call as needed.
+    // If the server's maximum wait time was reached before the stage requested by the client, then
+    // the returned stage may be less than the requested stage. Clients may then retry the call as
+    // needed.
     temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage stage = 2;
     // Sufficient information to address this update.
     temporal.api.update.v1.UpdateRef update_ref = 3;