docs(cron): add when to table + examples for DST leap handling
#13723
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Alan Clucas <alan@clucas.org>
Joibel
added
area/docs
agilgur5
changed the title
when and DST docswhen to table + examples for DST leap handling
As requested in #13474 (review) |
agilgur5
reviewed
Oct 18, 2024
| | `timezone` | Machine timezone | [IANA Timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to run `Workflows`. Example: `America/Los_Angeles` | | ||
| | `suspend` | `false` | If `true` Workflow scheduling will not occur. Can be set from the CLI, GitOps, or directly | | ||
| | `concurrencyPolicy` | `Allow` | What to do if multiple `Workflows` are scheduled at the same time. `Allow`: allow all, `Replace`: remove all old before scheduling new, `Forbid`: do not allow any new while there are old | | ||
| | `startingDeadlineSeconds` | `0` | Seconds after [the last scheduled time](#crash-recovery) during which a missed `Workflow` will still be run. | | ||
| | `successfulJobsHistoryLimit` | `3` | Number of successful `Workflows` to persist | | ||
| | `failedJobsHistoryLimit` | `1` | Number of failed `Workflows` to persist | | ||
| | `stopStrategy` | `nil` | v3.6 and after: defines if the CronWorkflow should stop scheduling based on a condition | | ||
| | `when` | None | v3.6 and after: An optional [expression](walk-through/conditionals.md) which will be evaluated on each cron schedule hit and the workflow will only run if it evaluates to `true` | |
There was a problem hiding this comment.
Suggested change
| | `when` | None | v3.6 and after: An optional [expression](walk-through/conditionals.md) which will be evaluated on each cron schedule hit and the workflow will only run if it evaluates to `true` | | |
| | `when` | None | v3.6 and after: An optional [expression](variables.md#expression) that determines if a run should be scheduled | |
- simplify, per k8s style guide
- match language in feat(cron): cronworkflows
whenclause #13474 (comment)
also:
- "cron schedule hit" is also not an existing term in these docs.
- "if it evaluates to
true" is the definition of a conditional variables.md#expressionis the canonical link for "expression" per docs: consolidate expression links #12617, and that page contains variables for this statement too.- Since an independent
whensection wasn't added on this page, I also wouldn't necessary link toconditionals.mdsince it has different variables and also still usesgovaluatesyntax, both of which would be confusing. If it had its own section with variables, then you could link toconditionals.mdas a pre-existing reference forwhen
- Since an independent
Comment on lines
+130
to
+131
| !!! Warning "Can run at 3:00" | ||
| If you create this CronWorkflow between the desired time and 3:00 it will run at 3:00 as it has never run before. |
There was a problem hiding this comment.
Suggested change
| !!! Warning "Can run at 3:00" | |
| If you create this CronWorkflow between the desired time and 3:00 it will run at 3:00 as it has never run before. | |
| !!! Warning "Can run at 3:00" | |
| If you create this CronWorkflow between the desired time and 3:00 it will run at 3:00 as it has never run before. |
This syntax is incorrect, the contents of an admonition block must be 4 space indented. Please do check the HTML output of mkdocs if you're not sure. There is technically a preview in CI as well, it's just not easy to access.
There was a problem hiding this comment.
Since this was merged before I had a chance to review, can see what this syntax error currently looks like live:
| ``` | ||
|
|
||
| This will schedule at the first 01:30 on a skip backwards change. | ||
| The second will not run because of the `when` expression, which prevents this workflow running more often than once every 2 hours.. |
There was a problem hiding this comment.
Suggested change
| The second will not run because of the `when` expression, which prevents this workflow running more often than once every 2 hours.. | |
| The second will not run because of the `when` expression, which prevents this workflow running more often than once every 2 hours. |
typo
| @@ -109,6 +110,41 @@ For example, with `timezone: America/Los_Angeles`: | |||
| | | 2 | 2020-11-02 02:01:00 -0800 PST | | |||
| | | 3 | 2020-11-03 02:01:00 -0800 PST | | |||
|
|
|||
| #### Skip forward (missing schedule) | |||
There was a problem hiding this comment.
Per #13365 (comment), even if you left these split, I would still simplify these, per the style guide, and still use the word "leap" as that is the common term for this compared to "skip" (which has various other connotations, particularly in the context of workflows)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
This PR brings in the "once a day" documentation from #13365
Fixes #13700 whilst I'm there
Modifications
Add
whenclause to cron workflows "options" listDocument skip forward and skip backward correctors for DST as previously documented in #13365
Verification
make docspasses