Clarify docs for CronWorkflow startingDeadlineSeconds

[nhavens]

Pre-requisites

• I have double-checked my configuration
• I have tested with the :latest image tag (i.e. quay.io/argoproj/workflow-controller:latest) and can confirm the issue still exists on :latest. If not, I have explained why, in detail, in my description below.
• I have searched existing issues and could not find a match for this bug
• I'd like to contribute the fix myself (see contributing guide)

What happened/what did you expect to happen?

The CronWorkflow docs describe startingDeadlineSeconds as:

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.

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.

This does not match the logic in the implementation. Based on the code, the docs should be reworded to something like the following:

Mainly startingDeadlineSeconds can be set to specify the maximum number of seconds past the last scheduled run of a CronWorkflow during which a missed run will still be executed.

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 amount of time passing between the last scheduled run 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.

Similar changes should be made elsewhere, as the comparison is not against the last successful run, but rather the last desired/expected/scheduled run time.

tl;dr startingDeadlineSeconds should be clearly documented as the "grace period" beyond the scheduled run during which a CronWorkflow may still be executed.

Version

v3.5.5

Paste a small workflow that reproduces the issue. We must be able to run the workflow; don't enter a workflows that uses private images.

n/a

Logs from the workflow controller

n/a

Logs from in your workflow's wait container

n/a

[Joibel]

PRs welcome on this.

[parambath92]

Hello @Joibel, I am interested in picking this up if nobody else is working on it.