add explanation for fast-forward override

Author: feiyang3cat

openapi/openapiv2.json

@@ -19680,14 +19680,14 @@
         },
         "fastForward": {
           "type": "string",
-          "description": "Optionally fast-forward the current workflow execution by this duration ahead of current workflow execution time.\nWhen the fast-forward completes, time skipping is disabled by the call that initiated the fast-forward, and this\naction is recorded in the WorkflowExecutionTimeSkippingTransitionedEvent. It can be re-enabled by\nsetting `enabled` to true via UpdateWorkflowExecutionOptions.\nThe current workflow execution is a chain of runs (retries, cron, continue-as-new);\nchild workflows are separate executions, so this fast_forward won't affect them."
+          "description": "Optionally fast-forward the current workflow execution by this duration ahead of current workflow execution time.\nWhen the fast-forward completes, time skipping is disabled by the call that initiated the fast-forward, and this\naction is recorded in the WorkflowExecutionTimeSkippingTransitionedEvent. It can be re-enabled by\nsetting `enabled` to true via UpdateWorkflowExecutionOptions.\nThe current workflow execution is a chain of runs (retries, cron, continue-as-new);\nchild workflows are separate executions, so this fast_forward won't affect them.\n\nFor a given workflow execution, only one active fast-forward is allowed at a time.\nIf a new fast-forward is set via UpdateWorkflowExecutionOptions before the previous\none completes, the new one will override the previous one.\nIf the fast-forward duration exceeds the remaining execution timeout, time will only\nbe fast-forwarded up to the end of the execution."
         },
         "disableChildPropagation": {
           "type": "boolean",
           "description": "By default, child workflows inherit the \"enabled\" flag when they are started.\nThis flag disables that inheritance."
         }
       },
-      "description": "The configuration for time skipping of a workflow execution (a chain of runs including retries, cron, continue-as-new).\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\nand possibly other features added in the future.\nUser timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the\ntime point of the registered fast_forward when there is no in-flight work.\n\nFor child workflows, by default, if the parent execution is skipping time, the child execution will also skip time,\nbut a parent's fast_forward won't affect its child's execution. A flag is provided to disable propagation of the\n\"enabled\" flag to child workflows; regardless of that flag, a child workflow inherits the virtual time from the\nparent execution as its start time."
+      "description": "The configuration for time skipping of a workflow execution (a chain of runs including retries, cron, continue-as-new).\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\nand possibly other features added in the future.\nUser timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the\ntime point of the registered fast forward when there is no in-flight work.\nWhen time is skipped, a WorkflowExecutionTimeSkippingTransitionedEvent will be\nadded to the workflow history to capture the state changes.\n\nFor child workflows, by default, if the parent execution is skipping time, the child execution will also skip time,\nbut a parent's fast_forward won't affect its child's execution. A flag is provided to disable propagation of the\n\"enabled\" flag to child workflows; regardless of that flag, a child workflow inherits the virtual time from the\nparent execution as its start time."
     },
     "v1TimeSkippingStatePropagation": {
       "type": "object",

openapi/openapiv3.yaml

@@ -17442,6 +17442,12 @@ components:
              setting `enabled` to true via UpdateWorkflowExecutionOptions.
              The current workflow execution is a chain of runs (retries, cron, continue-as-new);
              child workflows are separate executions, so this fast_forward won't affect them.
+
+             For a given workflow execution, only one active fast-forward is allowed at a time.
+             If a new fast-forward is set via UpdateWorkflowExecutionOptions before the previous
+             one completes, the new one will override the previous one.
+             If the fast-forward duration exceeds the remaining execution timeout, time will only
+             be fast-forwarded up to the end of the execution.
         disableChildPropagation:
           type: boolean
           description: |-
@@ -17453,7 +17459,9 @@ components:
          In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,
          and possibly other features added in the future.
          User timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the
-         time point of the registered fast_forward when there is no in-flight work.
+         time point of the registered fast forward when there is no in-flight work.
+         When time is skipped, a WorkflowExecutionTimeSkippingTransitionedEvent will be
+         added to the workflow history to capture the state changes.
 
          For child workflows, by default, if the parent execution is skipping time, the child execution will also skip time,
          but a parent's fast_forward won't affect its child's execution. A flag is provided to disable propagation of the

temporal/api/history/v1/message.proto

@@ -209,8 +209,8 @@ message WorkflowExecutionStartedEventAttributes {
     reserved 42;
     reserved "initial_skipped_duration";
 
-  // The time-skipping state propagated from a previous run of this workflow. This can be nil
-  // if no time skipping has occurred or there is no previous run.
+    // The time-skipping state propagated from a previous run of this workflow. This can be nil
+    // if no time skipping has occurred or there is no previous run.
     temporal.api.workflow.v1.TimeSkippingStatePropagation time_skipping_state_propagation = 43;
 
 }

temporal/api/workflow/v1/message.proto

@@ -596,7 +596,9 @@ message WorkflowExecutionOptions {
 // In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,
 // and possibly other features added in the future.
 // User timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the
-// time point of the registered fast_forward when there is no in-flight work.
+// time point of the registered fast forward when there is no in-flight work.
+// When time is skipped, a WorkflowExecutionTimeSkippingTransitionedEvent will be
+// added to the workflow history to capture the state changes.
 //
 // For child workflows, by default, if the parent execution is skipping time, the child execution will also skip time,
 // but a parent's fast_forward won't affect its child's execution. A flag is provided to disable propagation of the
@@ -612,6 +614,12 @@ message TimeSkippingConfig {
     // setting `enabled` to true via UpdateWorkflowExecutionOptions.
     // The current workflow execution is a chain of runs (retries, cron, continue-as-new);
     // child workflows are separate executions, so this fast_forward won't affect them.
+    //
+    // For a given workflow execution, only one active fast-forward is allowed at a time.
+    // If a new fast-forward is set via UpdateWorkflowExecutionOptions before the previous
+    // one completes, the new one will override the previous one.
+    // If the fast-forward duration exceeds the remaining execution timeout, time will only
+    // be fast-forwarded up to the end of the execution.
     google.protobuf.Duration fast_forward = 2;
 
     // By default, child workflows inherit the "enabled" flag when they are started.