Skip to content

Commit 29c70b4

Browse files
authored
docs(schedule): improve description, deprecate Later syntax (#31958)
1 parent b923c40 commit 29c70b4

File tree

1 file changed

+24
-52
lines changed

1 file changed

+24
-52
lines changed

docs/usage/configuration-options.md

+24-52
Original file line numberDiff line numberDiff line change
@@ -3780,77 +3780,49 @@ We recommend you do this selectively with `packageRules` and not globally.
37803780

37813781
## schedule
37823782

3783-
The `schedule` option allows you to define times of week or month for Renovate updates.
3784-
Running Renovate around the clock can be too "noisy" for some projects.
3785-
To reduce the noise you can use the `schedule` config option to limit the time frame in which Renovate will perform actions on your repository.
3786-
You can use the standard [Cron syntax](https://crontab.guru/crontab.5.html) and [Later syntax](https://github.com/breejs/later) to define your schedule.
3783+
The `schedule` option allows you to define times of the day, week or month when you are willing to allow Renovate to create branches.
37873784

3788-
The default value for `schedule` is "at any time", which is functionally the same as declaring a `null` schedule.
3789-
i.e. Renovate will run on the repository around the clock.
3785+
Setting a `schedule` does not itself cause or trigger Renovate to run. It's like putting a sign on your office which says "DHL deliveries only accepted between 9-11am". Such a sign won't _cause_ DHL to come to your office only at 9-11am, instead it simply means that if they come at any other time of the day then they'll honor the sign and skip you. It also means that if they rarely attempt between 9-11am then you'll often get no deliveries in a day. Similarly, if you set too restrictive of a Renovate `schedule` and the chance of Renovate running on your repo during those hours is low, then you might find your dependency updates regularly skipped. For this reason we recommend you usually allow a time window of at least 3-4 hours in any `schedule` unless your instance of Renovate is expected to run more frequently than that.
3786+
3787+
Renovate supports the standard [Cron syntax](https://crontab.guru/crontab.5.html) as well as deprecated support for a subset of [Later syntax](https://github.com/breejs/later).
3788+
We recommend you always use Cron syntax, due to its superior testing and robustness.
3789+
Config support questions are no longer accepted for Later syntax problems - you will be recommended to use Cron instead.
3790+
3791+
The default value for `schedule` is "at any time", which is functionally the same as declaring a `null` schedule or `* * * * *` with Cron.
3792+
i.e. Renovate will create Pull Requests at any time of any day, as needed.
37903793

37913794
The easiest way to define a schedule is to use a preset if one of them fits your requirements.
37923795
See [Schedule presets](./presets-schedule.md) for details and feel free to request a new one in the source repository if you think it would help others.
37933796

3794-
```title="Some text schedules that are known to work"
3795-
every weekend
3796-
before 5:00am
3797-
after 10pm and before 5:00am
3798-
after 10pm and before 5am every weekday
3799-
on friday and saturday
3800-
every 3 months on the first day of the month
3801-
* 0 2 * *
3802-
```
3797+
Here are some example schedules and their Cron equivalent:
38033798

3804-
<!-- prettier-ignore -->
3805-
!!! warning
3806-
You _must_ keep the number and the `am`/`pm` part _together_!
3807-
Correct: `before 5am`, or `before 5:00am`.
3808-
Wrong: `before 5 am`, or `before 5:00 am`.
3799+
| English description | Supported by Later? | Cron syntax |
3800+
| -------------------------------------------- | ------------------- | --------------------- |
3801+
| every weekend || `* * * * 0,6` |
3802+
| before 5:00am || `* 0-4 * * *` |
3803+
| after 10pm and before 5am every weekday || `* 22-23,0-4 * * 1-5` |
3804+
| on friday and saturday || `* * * * 5,6` |
3805+
| every 3 months on the first day of the month || `* * 1 */3 *` |
38093806

38103807
<!-- prettier-ignore -->
3811-
!!! warning
3808+
!!! note
38123809
For Cron schedules, you _must_ use the `*` wildcard for the minutes value, as Renovate doesn't support minute granularity.
38133810

38143811
One example might be that you don't want Renovate to run during your typical business hours, so that your build machines don't get clogged up testing `package.json` updates.
38153812
You could then configure a schedule like this at the repository level:
38163813

38173814
```json
38183815
{
3819-
"schedule": ["after 10pm and before 5am every weekday", "every weekend"]
3816+
"schedule": ["* 22-23,0-4 * * *", "* * * * 0,6"]
38203817
}
38213818
```
38223819

38233820
This would mean that Renovate can run for 7 hours each night plus all the time on weekends.
3821+
Note how the above example makes use of the "OR" logic of combining multiple schedules in the array.
38243822

3825-
This scheduling feature can also be particularly useful for "noisy" packages that are updated frequently, such as `aws-sdk`.
3826-
3827-
To restrict `aws-sdk` to only monthly updates, you could add this package rule:
3828-
3829-
```json
3830-
{
3831-
"packageRules": [
3832-
{
3833-
"matchPackageNames": ["aws-sdk"],
3834-
"extends": ["schedule:monthly"]
3835-
}
3836-
]
3837-
}
3838-
```
3839-
3840-
Technical details: We mostly rely on the text parsing of the library [@breejs/later](https://github.com/breejs/later) but only its concepts of "days", "time_before", and "time_after".
3841-
Read the parser documentation at [breejs.github.io/later/parsers.html#text](https://breejs.github.io/later/parsers.html#text).
3842-
To parse Cron syntax, Renovate uses [cron-parser](https://github.com/harrisiirak/cron-parser).
3843-
Renovate does not support scheduled minutes or "at an exact time" granularity.
3844-
3845-
<!-- prettier-ignore -->
3846-
!!! tip
3847-
If you want to _disable_ Renovate, then avoid setting `schedule` to `"never"`.
3848-
Instead, use the `enabled` config option to disable Renovate.
3849-
Read the [`enabled` config option docs](#enabled) to learn more.
3850-
3851-
<!-- prettier-ignore -->
3852-
!!! note
3853-
Actions triggered via the [Dependency Dashboard](#dependencydashboard) are not restricted by a configured schedule.
3823+
It's common to use `schedule` in combination with [`timezone`](#timezone).
3824+
You should configure [`updateNotScheduled=false`](#updatenotscheduled) if you want the schedule more strictly enforced so that _updates_ to existing branches aren't pushed out of schedule.
3825+
You can also configure [`automergeSchedule`](#automergeschedule) to limit the hours in which branches/PRs are _automerged_ (if [`automerge`](#automerge) is configured).
38543826

38553827
## semanticCommitScope
38563828

@@ -3971,7 +3943,7 @@ The above config will suppress the comment which is added to a PR whenever you c
39713943

39723944
## timezone
39733945

3974-
It is only recommended to configure this field if you wish to use the `schedules` feature and want to write them in your local timezone.
3946+
It is only recommended to configure this field if you wish to use the `schedule` feature and want them evaluated in your local timezone.
39753947
Please see the above link for valid timezone names.
39763948

39773949
## updateInternalDeps

0 commit comments

Comments
 (0)