fix(docs): clarify CronWorkflow startingDeadlineSeconds. Fixes #12971 (#13280)

Signed-off-by: qingfeng777 <[email protected]>
Signed-off-by: Anton Gilgur <[email protected]>
Signed-off-by: Anton Gilgur <[email protected]>
Co-authored-by: Neile Havens <[email protected]>
Co-authored-by: Anton Gilgur <[email protected]>
Co-authored-by: Anton Gilgur <[email protected]>
(cherry picked from commit 9c5dd5b)

Author: 4 people

docs/cron-workflows.md

@@ -45,7 +45,7 @@ The resulting `Workflow` name will be a generated name based on the `CronWorkflo
 |          `timezone`          |    Machine timezone    | Timezone during which the Workflow will be run from the IANA timezone standard, e.g. `America/Los_Angeles`                                                                                                                              |
 |           `suspend`          |         `false`        | If `true` Workflow scheduling will not occur. Can be set from the CLI, GitOps, or directly                                                                                                                                              |
 |      `concurrencyPolicy`     |         `Allow`        | Policy that determines what to do if multiple `Workflows` are scheduled at the same time. Available options: `Allow`: allow all, `Replace`: remove all old before scheduling a new, `Forbid`: do not allow any new while there are old  |
-| `startingDeadlineSeconds`    |           `0`          | Number of seconds after the last successful run during which a missed `Workflow` will be run                                                                                                                                            |
+| `startingDeadlineSeconds`    |           `0`          | Number of seconds after the last scheduled time during which a missed `Workflow` will still be run. See [Crash Recovery](#crash-recovery) for more details. |
 | `successfulJobsHistoryLimit` |           `3`          | Number of successful `Workflows` that will be persisted at a time                                                                                                                                                                       |
 | `failedJobsHistoryLimit`     | `1`                    | Number of failed `Workflows` that will be persisted at a time                                                                                                                                                                           |
 
@@ -57,9 +57,11 @@ More detailed documentation for the specific library used is [documented here](h
 
 ### Crash Recovery
 
-If the `workflow-controller` crashes (and hence the `CronWorkflow` controller), there are some options you can set to ensure that `CronWorkflows` that would have been scheduled while the controller was down can still run. Mainly `startingDeadlineSeconds` can be set to specify the maximum number of seconds past the last successful run of a `CronWorkflow` during which a missed run will still be executed.
+If the Controller crashes, you can ensure that any missed schedules still run.
 
-For example, if a `CronWorkflow` that runs every minute is last run at 12:05:00, and the controller crashes between 12:05:55 and 12:06:05, then the expected execution time of 12:06:00 would be missed. However, if `startingDeadlineSeconds` is set to a value greater than 65 (the amount of time passing between the last scheduled run time of 12:05:00 and the current controller restart time of 12:06:05), then a single instance of the `CronWorkflow` will be executed exactly at 12:06:05.
+With `startingDeadlineSeconds` you can specify a maximum grace period past the last scheduled time during which it will still run.
+For example, if a `CronWorkflow` that runs every minute is last run at 12:05:00, and the controller crashes between 12:05:55 and 12:06:05, then the expected execution time of 12:06:00 would be missed.
+However, if `startingDeadlineSeconds` is set to a value greater than 5 (the time passed between the last scheduled time of 12:06:00 and the current time of 12:06:05), then a single instance of the `CronWorkflow` will be executed exactly at 12:06:05.
 
 Currently only a single instance will be executed as a result of setting `startingDeadlineSeconds`.