Skip to content

Commit

Permalink
docs(schedule): improve description, deprecate Later syntax (#31958)
Browse files Browse the repository at this point in the history
  • Loading branch information
rarkins authored Oct 15, 2024
1 parent b923c40 commit 29c70b4
Showing 1 changed file with 24 additions and 52 deletions.
76 changes: 24 additions & 52 deletions docs/usage/configuration-options.md
Original file line number Diff line number Diff line change
Expand Up @@ -3780,77 +3780,49 @@ We recommend you do this selectively with `packageRules` and not globally.

## schedule

The `schedule` option allows you to define times of week or month for Renovate updates.
Running Renovate around the clock can be too "noisy" for some projects.
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.
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.
The `schedule` option allows you to define times of the day, week or month when you are willing to allow Renovate to create branches.

The default value for `schedule` is "at any time", which is functionally the same as declaring a `null` schedule.
i.e. Renovate will run on the repository around the clock.
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.

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).
We recommend you always use Cron syntax, due to its superior testing and robustness.
Config support questions are no longer accepted for Later syntax problems - you will be recommended to use Cron instead.

The default value for `schedule` is "at any time", which is functionally the same as declaring a `null` schedule or `* * * * *` with Cron.
i.e. Renovate will create Pull Requests at any time of any day, as needed.

The easiest way to define a schedule is to use a preset if one of them fits your requirements.
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.

```title="Some text schedules that are known to work"
every weekend
before 5:00am
after 10pm and before 5:00am
after 10pm and before 5am every weekday
on friday and saturday
every 3 months on the first day of the month
* 0 2 * *
```
Here are some example schedules and their Cron equivalent:

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

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

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.
You could then configure a schedule like this at the repository level:

```json
{
"schedule": ["after 10pm and before 5am every weekday", "every weekend"]
"schedule": ["* 22-23,0-4 * * *", "* * * * 0,6"]
}
```

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

This scheduling feature can also be particularly useful for "noisy" packages that are updated frequently, such as `aws-sdk`.

To restrict `aws-sdk` to only monthly updates, you could add this package rule:

```json
{
"packageRules": [
{
"matchPackageNames": ["aws-sdk"],
"extends": ["schedule:monthly"]
}
]
}
```

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".
Read the parser documentation at [breejs.github.io/later/parsers.html#text](https://breejs.github.io/later/parsers.html#text).
To parse Cron syntax, Renovate uses [cron-parser](https://github.com/harrisiirak/cron-parser).
Renovate does not support scheduled minutes or "at an exact time" granularity.

<!-- prettier-ignore -->
!!! tip
If you want to _disable_ Renovate, then avoid setting `schedule` to `"never"`.
Instead, use the `enabled` config option to disable Renovate.
Read the [`enabled` config option docs](#enabled) to learn more.

<!-- prettier-ignore -->
!!! note
Actions triggered via the [Dependency Dashboard](#dependencydashboard) are not restricted by a configured schedule.
It's common to use `schedule` in combination with [`timezone`](#timezone).
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.
You can also configure [`automergeSchedule`](#automergeschedule) to limit the hours in which branches/PRs are _automerged_ (if [`automerge`](#automerge) is configured).

## semanticCommitScope

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

## timezone

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.
It is only recommended to configure this field if you wish to use the `schedule` feature and want them evaluated in your local timezone.
Please see the above link for valid timezone names.

## updateInternalDeps
Expand Down

0 comments on commit 29c70b4

Please sign in to comment.