fix!: consolidate cronworkflow variables #13702

Joibel · 2024-10-04T07:01:57Z

Context

Issues #13474 and #12305 both introduced expressions into CronWorkflows as new features for 3.6.
There are some inconsistencies between the two, per #13474 (comment) and #12305 (comment)

This PR was discussed at the October 1st 2024 Contributor meeting.

Motivation

The expressions for when include the prefix cronworkflow.. Those for stopStrategy.condition do not.

Unify both of these under cronworkflow. and allow both sets of variables to be used in both expressions. This simplifies the documentation and is less surprising. It also allows some use cases where you could check for previous run failures and take decisions based on that and time of day - so perhaps run every hour in the schedule but then use when to only actually take action if the previous run this day failed.

stopStrategy's condition is mostly not a field name used in workflows, so in agreement with @agilgur5 I've renamed it to expression.

Modifications

Renamed stopStrategy.condition to stopStrategy.expression

Created a single function to generate all the variables for both expressions and use that instead of the two disparate mechanisms.

Modified some code comments to be godoc compliant.

Verification

Existing tests still pass with appropriate amendments to the test cases

Note

This is a breaking change vs 3.6-rc1 and rc2 for users of stopStrategy only. This is not considered properly breaking as those are release candidates and not full releases.

Signed-off-by: Alan Clucas [email protected]

Joibel · 2024-10-04T07:07:48Z

Summoning

@eduardodbr, the effect of this change is mostly on your implementation, so I'd appreciate feedback
@isubasinghe, this doesn't much affect when, but I'd also appreciate feedback
@agilgur5, as you're the one who pointed this out and I'd like to know if it matches your expectations

agilgur5

Could you remove the @tag of me in the commit message? I'm getting notified for every single commit right now and uh would prefer not to, including when commits are backported or forked 😅

Joibel · 2024-10-04T14:30:45Z

Could you remove the @tag of me in the commit message? I'm getting notified for every single commit right now and uh would prefer not to, including when commits are backported or forked 😅

Oh, ha ha! That's not fun.
Done.

docs/fields.md

isubasinghe

I do apologize but I think this:
hack/api/swagger/swaggify.sh
is getting in your way.

Removed @ from commit message as requested

Joibel · 2024-10-07T08:36:20Z

I do apologize but I think this: hack/api/swagger/swaggify.sh is getting in your way.

This is annoying. I'm not going to attempt to address this hack at the moment, so I've reworded it. Probably the correct fix is to understand the json and only replace in the two (I think) places in the structure which actually want it to happen, or at least not in title and description fields.

agilgur5

There are some misses here and a semantic error in the docs. Do keep in mind the surrounding context when making docs changes, as they do reference and build upon each other.
The version annotations are also intentionally at the beginning.
See in-line comments below

docs/cron-workflows.md

agilgur5 · 2024-10-07T17:27:29Z

pkg/apis/workflow/v1alpha1/cron_workflow_types.go

@@ -69,11 +69,12 @@ type CronWorkflowSpec struct {
 	When string `json:"when,omitempty" protobuf:"bytes,12,opt,name=when"`
 }

-// v3.6 and after: StopStrategy defines if the CronWorkflow should stop scheduling based on a condition
+// StopStrategy defines if the CronWorkflow should stop scheduling based on an expression. v3.6 and after


The version annotation being consistently the first thing is intentional so that it is the first thing you see. This change makes this inconsistent with every other version annotation in the codebase, like lines 64-68 above, as well as harder to notice (and we already have trouble with users not noticing versions and so should not increase that).

I believe you made this change for GoDoc purposes, which does raise a conundrum since that apparently requires it to start the same way? If it's just a convention, the consistency and visibility should supersede that.

I did that to make it GoDoc compliant.

That does not address my comment (I mentioned that myself in my comment) and, as I wrote above, is inconsistent with the entirety of rest of the code and docs (where this exact comment is user-facing) on version annotation placement

pkg/apis/workflow/v1alpha1/cron_workflow_types.go

Issues #13474 and #12305 both introduced expressions into CronWorkflows as new features for 3.6. Motivation The expressions for `when` include the prefix `cronworkflow.`. Those for `stopStrategy.condition` do not. Unify both of these under `cronworkflow.` and allow both sets of variables to be used in both expressions. This simplifies the documentation and is less surprising. stopExpression's `condition` is mostly not a field name used, so in agreement with agilgur5 I've renamed it to `expression`. Modifications Renamed `stopStrategy.condition` to `stopStrategy.expression` Created a single function to generate all the variables for both expressions and use that instead of the two disparate mechanisms. Modified some code comments to be godoc compliant. Verification Existing tests still pass with appropriate amendments to the test cases Note This is a breaking change vs 3.6-rc1 and rc2 for users of stopStrategy only. Signed-off-by: Alan Clucas <[email protected]>

Signed-off-by: Alan Clucas <[email protected]>

isubasinghe

LGTM

Requested changes have been addressed

Signed-off-by: Alan Clucas <[email protected]>

agilgur5

Joibel dismissed agilgur5’s stale review 5 days ago:
Requested changes have been addressed

One of them was not addressed and the other was only partially addressed

agilgur5 · 2024-10-22T21:13:14Z

docs/cron-workflows.md

@@ -51,7 +51,7 @@ You can use `CronWorkflow.spec.workflowMetadata` to add `labels` and `annotation
 | `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 |
+| `stopStrategy.expression`    | `nil`                  | v3.6 and after: defines if the CronWorkflow should stop scheduling based on an expression, which if present must evaluate to false for the workflow to be created |


Suggested change

| `stopStrategy.expression` | `nil` | v3.6 and after: defines if the CronWorkflow should stop scheduling based on an expression, which if present must evaluate to false for the workflow to be created |

| `stopStrategy.expression` | `nil` | v3.6 and after: defines if the CronWorkflow [should stop scheduling](#automatically-stopping-a-cronworkflow) based on an expression |

As suggested before

and still following existing language and k8s style guide on simplicity and directness

agilgur5 · 2024-10-22T21:15:48Z

pkg/apis/workflow/v1alpha1/cron_workflow_types.go

@@ -69,11 +69,12 @@ type CronWorkflowSpec struct {
 	When string `json:"when,omitempty" protobuf:"bytes,12,opt,name=when"`
 }

-// v3.6 and after: StopStrategy defines if the CronWorkflow should stop scheduling based on a condition
+// StopStrategy defines if the CronWorkflow should stop scheduling based on an expression. v3.6 and after


That does not address my comment (I mentioned that myself in my comment) and, as I wrote above, is inconsistent with the entirety of rest of the code and docs (where this exact comment is user-facing) on version annotation placement

docs/cron-workflows.md

Joibel requested review from terrytangyuan and sarabala1979 as code owners October 4, 2024 07:01

Joibel assigned Joibel and unassigned Joibel Oct 4, 2024

Joibel force-pushed the cron-variable-tidies branch from 84afcd9 to d4e3e02 Compare October 4, 2024 07:15

agilgur5 previously requested changes Oct 4, 2024

View reviewed changes

agilgur5 added this to the v3.6.0 milestone Oct 4, 2024

Joibel force-pushed the cron-variable-tidies branch from d4e3e02 to 08d15c2 Compare October 4, 2024 14:30

tooptoop4 reviewed Oct 4, 2024

View reviewed changes

docs/fields.md Outdated Show resolved Hide resolved

agilgur5 added area/cron-workflows area/templating Templating with `{{...}}` labels Oct 5, 2024

isubasinghe reviewed Oct 7, 2024

View reviewed changes

agilgur5 previously requested changes Oct 7, 2024

View reviewed changes

Joibel added 2 commits October 11, 2024 11:38

chore: fix swaggerify breaking the comments

3ec9cdf

Signed-off-by: Alan Clucas <[email protected]>

Joibel force-pushed the cron-variable-tidies branch from f93cd60 to 5878b21 Compare October 11, 2024 13:21

docs: review comments

1c20373

Signed-off-by: Alan Clucas <[email protected]>

Joibel force-pushed the cron-variable-tidies branch from 5878b21 to 1c20373 Compare October 11, 2024 13:23

isubasinghe approved these changes Oct 14, 2024

View reviewed changes

Joibel requested a review from agilgur5 October 15, 2024 08:09

Merge branch 'main' into cron-variable-tidies

8c367ce

Signed-off-by: Alan Clucas <[email protected]>

Joibel enabled auto-merge (squash) October 17, 2024 09:47

Joibel merged commit a88cddc into main Oct 17, 2024
28 checks passed

Joibel deleted the cron-variable-tidies branch October 17, 2024 10:18

agilgur5 reviewed Oct 22, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix!: consolidate cronworkflow variables #13702

fix!: consolidate cronworkflow variables #13702

Joibel commented Oct 4, 2024 •

edited by agilgur5

Loading

Joibel commented Oct 4, 2024

agilgur5 left a comment

Joibel commented Oct 4, 2024

isubasinghe left a comment •

edited by agilgur5

Loading

Joibel commented Oct 7, 2024 •

edited by agilgur5

Loading

agilgur5 left a comment •

edited

Loading

agilgur5 Oct 7, 2024 •

edited

Loading

Joibel Oct 11, 2024

agilgur5 Oct 22, 2024 •

edited

Loading

isubasinghe left a comment

agilgur5 left a comment

agilgur5 Oct 22, 2024 •

edited

Loading

agilgur5 Oct 22, 2024 •

edited

Loading

	\| `stopStrategy.expression` \| `nil` \| v3.6 and after: defines if the CronWorkflow should stop scheduling based on an expression, which if present must evaluate to false for the workflow to be created \|
	\| `stopStrategy.expression` \| `nil` \| v3.6 and after: defines if the CronWorkflow [should stop scheduling](#automatically-stopping-a-cronworkflow) based on an expression \|

fix!: consolidate cronworkflow variables #13702

fix!: consolidate cronworkflow variables #13702

Conversation

Joibel commented Oct 4, 2024 • edited by agilgur5 Loading

Context

Motivation

Modifications

Verification

Note

Joibel commented Oct 4, 2024

agilgur5 left a comment

Choose a reason for hiding this comment

Joibel commented Oct 4, 2024

isubasinghe left a comment • edited by agilgur5 Loading

Choose a reason for hiding this comment

Joibel commented Oct 7, 2024 • edited by agilgur5 Loading

agilgur5 left a comment • edited Loading

Choose a reason for hiding this comment

agilgur5 Oct 7, 2024 • edited Loading

Choose a reason for hiding this comment

Joibel Oct 11, 2024

Choose a reason for hiding this comment

agilgur5 Oct 22, 2024 • edited Loading

Choose a reason for hiding this comment

isubasinghe left a comment

Choose a reason for hiding this comment

agilgur5 left a comment

Choose a reason for hiding this comment

agilgur5 Oct 22, 2024 • edited Loading

Choose a reason for hiding this comment

agilgur5 Oct 22, 2024 • edited Loading

Choose a reason for hiding this comment

Joibel commented Oct 4, 2024 •

edited by agilgur5

Loading

isubasinghe left a comment •

edited by agilgur5

Loading

Joibel commented Oct 7, 2024 •

edited by agilgur5

Loading

agilgur5 left a comment •

edited

Loading

agilgur5 Oct 7, 2024 •

edited

Loading

agilgur5 Oct 22, 2024 •

edited

Loading

agilgur5 Oct 22, 2024 •

edited

Loading

agilgur5 Oct 22, 2024 •

edited

Loading