Clarifying usage of + with % in CRON for scheduled builds

[neilcampbell]

Hi,
Sorry in advance for the long message 😄

We make fairly heavy use of scheduled builds and needed to change a build schedule which had 1%4+3, so I went to the docs. This was a little confusing to me, so spoke to a colleague who originally set it up. He mentioned that he'd been chatting to your team and had sent a PR to clarify, which has now been updated.

I wanted to clarify that I understand the syntax correctly before trying to make the docs clearer (and also make the schedule changes on our side).
The modulo syntax performs a calculation on the day specified and using + 1 offsets that day.
Instead of the operation working on the calendar day of the week number itself, it actually operates of the number of occurrences the day has been seen by the scheduling system since inception.

Sounds like the scheduling system starts from 2019-01-01 and counts weeks from that day.
Using some numbers in the future, below is the number of weeks from inception on Sunday (0).
07/02/21 = 109
14/02/21 = 110
21/02/21 = 111
28/02/21 = 112
07/03/21 = 113
14/03/21 = 114
21/03/21 = 115
28/03/21 = 116
04/04/21 = 117
11/04/21 = 118

Now given a CRON of 30 10 * * 0%4 Australia/Melbourne, the day calcs would be:
109%4 = 1 (Don't run on 07/02/21)
110%4 = 2 (Don't run on 14/02/21)
111%4 = 3 (Don't run on 21/02/21)
112%4 = 0 (Run on 28/02/21)
113%4 = 1 (Don't run on 07/03/21)
114%4 = 2 (Don't run on 14/03/21)
115%4 = 3 (Don't run on 21/03/21)
116%4 = 0 (Run on 28/03/21)
117%4 = 1 (Don't run on 04/04/21)
118%4 = 2 (Don't run on 11/04/21)

Now given a CRON of 30 10 * * 0%4+3 Australia/Melbourne, the day calcs would be:
109+3%4 = 0 (Run on 07/02/21)
110+3%4 = 1 (Don't run on 14/02/21)
111+3%4 = 2 (Don't run on 21/02/21)
112+3%4 = 3 (Don't run on 28/02/21)
113+3%4 = 0 (Run on 07/03/21)
114+3%4 = 1 (Don't run on 14/03/21)
115+3%4 = 2 (Don't run on 21/03/21)
116+3%4 = 3 (Don't run on 28/03/21)
117+3%4 = 0 (Run on 04/04/21)
118+3%4 = 1 (Don't run on 11/04/21)

This gives us always a predictable run on a Sunday every 4 weeks, the offset just lets you change when it's first run. If we were to use the calendar day number for the calcs, we'd get an unpredictable behaviour.

Is this the correct way of understanding the syntax?
If so, I'll try summarise this and send a docs PR.

[JuanitoFatas]

Hello Neil.

Thanks for your interest in contributing to our docs on a beautiful Friday in Melbourne!! This is so awesome!

We use fugit under the hood and I think the examples you provide means:

30 10 * * 0%4 Australia/Melbourne - Every Sunday
30 10 * * 0%4+3 Australia/Melbourne - Every third Sunday

according to their modulo docs.

If you want every nth Sunday, then use the # syntax:

30 10 * * 0#1 Australia/Melbourne - Every first Sunday

Also you can change the 0 to Sun to make it more readable:

30 10 * * Sun%4 Australia/Melbourne

Does this help? Thank you!

[neilcampbell]

@JuanitoFatas As I understand it 30 10 * * 0%4 Australia/Melbourne runs every 4th Sunday and 30 10 * * 0%4+3 Australia/Melbourne run every 4th Sunday with the start day offset by 3 Sundays (as described above). The modulo docs are a bit confusing as well, for example it says For odd Sundays, one can write 9 0 * * sun%2+1, but it also has 9 0 * * sun%2,tue%3+2 without explaining what that means. Is that even Tuesdays?

We aren't actually trying to get a specific day in the month, it's more that we are trying to deploy components every x weeks and also not have too many deployments on that same day.

[JuanitoFatas]

30 10 * * 0%4 Australia/Melbourne runs every 4th Sunday and 30 10 * * 0%4+3 Australia/Melbourne run every 4th Sunday with the start day offset by 3 Sundays

Yes, you’re right.

9 0 * * sun%2,tue%3+2 — I think this example mean you can have two rules in one cron syntax. Every other Sunday + every third Tuesday offset by 2 Tuesdays.

We aren't actually trying to get a specific day in the month, it's more that we are trying to deploy components every x weeks and also not have too many deployments on that same day.

Noted and I think you have figured it out!

[neilcampbell]

I have updated the original question to better match how Fugit describes the reference/inception date.

The thing that I find weird/confusing in the BK docs and Fugit docs is:

From Fugit:

For odd Sundays, one can write 9 0 * * sun%2+1.

From BK:

0 0 * * 0%3+1 will create a schedule to run a build every third Sunday that is an odd calendar number.

Using the CRON in the Fugit example of 9 0 * * sun%2+1, the day calcs would be:

109+1%2 = 0 (Run on 07/02/21)

110+1%2 = 1 (Don't run on 14/02/21)

111+1%2 = 0 (Run on 21/02/21)


112+1%2 = 1 (Don't run on 28/02/21)



113+1%2 = 0 (Run on 07/03/21)



114+1%2 = 1 (Don't run on 14/03/21)



115+1%2 = 0 (Run on 21/03/21)




116+1%2 = 1 (Don't run on 28/03/21)





117+1%2 = 0 (Run on 04/04/21)





118+1%2 = 1 (Don't run on 11/04/21)





It seems that when Fugit is referring to For odd Sundays it's actually referring to the week number that Sunday resides in since 2019-01-01, and not the calendar day for that Sunday. As you can see the CRON will run on 04/04/21, which is an even day (from a calendar perspective).

Do you are your team have that same understanding? I don't want to update the docs to make them incorrect.

[ticky]

I think this is a hard concept to convey clearly and concisely 😅.

"Calendar number" is, I believe, attempting to imply that it's not based on the day of the month, specifically, but it's perhaps not doing the best job of it. If you have ideas for better ways to express it, I'd love to hear them (and maybe we could encourage improvements upstream so the understanding is easier for everyone!) 😃

[neilcampbell]

Sorry, completely forgot about this issue.
@ticky Yeah 100% agree, it's a tough one to describe. That's what threw me.

It's a weird one because the 0 in 0%3+1 represents day of the week (Sunday in this case), but when doing the calc the week number since epoch (2019-01-01) is substituted in. I don't really have a good word to describe that when referencing a calendar. Maybe adding more examples with how the math is performed is a better way to describe this feature?

[karensawrey]

@neilcampbell I'm also digging into this issue ("odd Sunday") from my side on @plaindocs' request. Hoping to be back with an update and better wording soon.

[plaindocs]

We tweaked the wording for this, and I think it is clearer now: