From 4871f4142858ca9f753a8b0a875f3327da5f0b1a Mon Sep 17 00:00:00 2001
From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>
Date: Mon, 30 Aug 2021 10:20:02 +0200
Subject: [PATCH] docs: create page for key concept scheduling (#11278)

---
 docs/usage/dependency-pinning.md      |   2 +
 docs/usage/faq.md                     |  49 +--------
 docs/usage/key-concepts/scheduling.md | 140 ++++++++++++++++++++++++++
 docs/usage/noise-reduction.md         |   2 +
 4 files changed, 145 insertions(+), 48 deletions(-)
 create mode 100644 docs/usage/key-concepts/scheduling.md

diff --git a/docs/usage/dependency-pinning.md b/docs/usage/dependency-pinning.md
index f87fa22dc8..354c299fda 100644
--- a/docs/usage/dependency-pinning.md
+++ b/docs/usage/dependency-pinning.md
@@ -126,6 +126,8 @@ So to reduce the interruptions of automated dependency updates, consider putting
 - Update only on weekends? This way you update packages at most once per week, _and_ your CI build runners are likely to be idle anyway
 - Update daily, but between hours like midnight and 5am? That way notifications don't pop up in people's feed while they're working, _and_ you also get the benefit of not tying up build machines when developers need to use them
 
+To learn all about controlling Renovate's schedule, read the [key concepts, scheduling](https://docs.renovatebot.com/key-concepts/scheduling/) docs.
+
 ### Grouping related packages
 
 Although it's good to isolate each dependency update for ease of troubleshooting, there are times when the extra noise isn't worth it, or when packages naturally belong together anyway (such as all `babel` packages).
diff --git a/docs/usage/faq.md b/docs/usage/faq.md
index 69d3e1c9f6..7f0b1201f6 100644
--- a/docs/usage/faq.md
+++ b/docs/usage/faq.md
@@ -127,54 +127,7 @@ See the dedicated [Private npm module support](./getting-started/private-package
 
 ### Control Renovate's schedule
 
-Renovate itself will run as often as its administrator has configured it (e.g. hourly, daily, etc).
-You may want to update certain repositories less often.
-Or you may even want to use different schedules for specific packages.
-
-To control the days of the week or times of day that Renovate updates packages, use the `timezone` and `schedule` configuration options.
-By default, Renovate schedules use the UTC timezone, but you can override this in the global config.
-
-You can set a specific time zone in your local config file as well:
-
-```json
-{
-  "timezone": "America/Los_Angeles"
-}
-```
-
-The timezone must be a valid [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-
-With the timezone set, you can define days of week or hours of the day in which Renovate will make changes.
-Renovate uses the [@breejs/later](https://github.com/breejs/later) library to parse the text.
-Read the parser documentation at [breejs.github.io/later/parsers.html#text](https://breejs.github.io/later/parsers.html#text).
-The _@breejs/later_ library also handles the concepts of "days", time_before", and "time_after".
-Renovate does not support scheduled minutes or "at an exact time" granularity.
-
-Examples of the kind of schedules you can create:
-
-```
-every weekend
-before 5:00am
-[after 10pm, before 5:00am]
-[after 10pm every weekday, before 5am every weekday]
-on friday and saturday
-```
-
-The scheduling feature can be very useful for "noisy" packages that are updated frequently, such as `aws-sdk`.
-
-To restrict `aws-sdk` to weekly updates, you could add this package rule:
-
-```json
-  "packageRules": [
-    {
-      "matchPackageNames": ["aws-sdk"],
-      "schedule": ["after 9pm on sunday"]
-    }
-  ]
-```
-
-The "schedule" propery must always be defined in an array, even if you only set a single schedule.
-Multiple entries in the array means "or".
+To learn all about controlling Renovate schedule, read the [key concepts, scheduling](https://docs.renovatebot.com/key-concepts/scheduling/) docs.
 
 ### Disable Renovate for certain dependency types
 
diff --git a/docs/usage/key-concepts/scheduling.md b/docs/usage/key-concepts/scheduling.md
new file mode 100644
index 0000000000..f45178bdf0
--- /dev/null
+++ b/docs/usage/key-concepts/scheduling.md
@@ -0,0 +1,140 @@
+---
+title: Renovate scheduling
+description: Learn how to schedule when Renovate runs
+---
+
+This document describes Renovate's scheduling.
+
+## Default behavior
+
+By default, Renovate bot runs as often as its administrator has configured it to (e.g. hourly, daily, etc.).
+The exact frequency at which Renovate can process individual repositories depends on the combination of how often it runs, how many repositories are installed, and whether there's a lot of work to be done in each repository (e.g. if a commonly used dependency has recently received a new update, which triggers a lot of PRs to be created).
+
+By default, Renovate schedules use the UTC timezone.
+You can override the default timezone by setting your own `timezone` config option.
+
+## Global schedule vs specific schedule
+
+When we talk about scheduling Renovate, there are 2 senses in which you can schedule Renovate:
+
+- A global sense: when the bot is allowed to do work at all. This is determined by the bot admin using tools such as `cron`
+- A specific sense: when Renovate is allowed to look for updates to a specific dependency
+
+While as an end user you may think of scheduling in terms of when you allow it to raise updates, it's important to remember that such updates can only occur if the bot gets the opportunity to run within the schedule window you provide.
+
+Because Renovate defaults to "always on" and "open PRs right away" it can be overwhelming your repository with notifications of new PRs.
+To reduce overwhelm, we provide scheduling tools.
+
+You may want to update certain repositories less often, or you may even want to use different schedules for specific packages.
+
+## Scheduling use cases
+
+Some common reasons to schedule when Renovate runs:
+
+- Make Renovate run outside office hours, to free up continuous integration resources for developers during the day
+- Get updates for certain packages on a regular interval instead of right away
+- Reduce Renovate bot PR notifications during the day
+
+## Customizing the schedule
+
+You can customize when Renovate runs, by using the `timezone` and `schedule` configuration options.
+
+At a high level you need to follow these steps:
+
+1. Tell Renovate what `timezone` you want to use
+1. Learn about the scheduling syntax
+1. Optional: configure a "in repository schedule"
+1. Optional: create packageRules with a custom `schedule` for specific packages
+
+### Setting your timezone
+
+By default, Renovate schedules use the UTC timezone.
+If you want Renovate to use your local time, use the `timezone` configuration option.
+The timezone must be a valid [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+You can set a specific time zone in your local config file like this:
+
+```json
+{
+  "timezone": "America/Los_Angeles"
+}
+```
+
+Read our docs on the [timezone](https://docs.renovatebot.com/configuration-options/#timezone) configuration option.
+
+### Scheduling syntax
+
+After you've set your local timezone, you can define "days of the week" or "hours of the day" in which Renovate is allowed to make changes.
+
+Examples of the kind of schedules you can create include:
+
+```
+every weekend
+before 5:00am
+[after 10pm, before 5:00am]
+[after 10pm every weekday, before 5am every weekday]
+on friday and saturday
+```
+
+**Warning:** Renovate does not support scheduled minutes or "at an exact time" granularity.
+Granularity must be at least one hour.
+
+Renovate uses the [@breejs/later](https://github.com/breejs/later) library to parse the text, so Renovate is limited to that library's syntax support.
+Read the parser documentation at [breejs.github.io/later/parsers.html#text](https://breejs.github.io/later/parsers.html#text) for more details.
+The _@breejs/later_ library also handles the concepts of "days", time_before", and "time_after".
+
+### In repository schedule configuration
+
+Reminder: the times when the Renovate process runs are controlled by the bot admin using tools such as `cron`.
+If you use the GitHub hosted app, the default is that Renovate will always be allowed to run.
+
+Be sure to schedule enough time for Renovate to process your repository.
+Do not set schedules like "Run Renovate for an hour each Sunday" as you _will_ run into problems.
+
+Say you want Renovate bot to run each day before 2 am:
+
+```json
+{
+  "schedule": ["before 2am"]
+}
+```
+
+Or you could tell Renovate to run outside of common office hours like this:
+
+```json
+{
+  "schedule": [
+    "after 10pm every weekday",
+    "before 5am every weekday",
+    "every weekend"
+  ]
+}
+```
+
+#### Schedule presets
+
+Renovate has preset schedules that you might want to use, go to [Schedule Presets](https://docs.renovatebot.com/presets-schedule/) to see them.
+
+These preset schedules only affect when Renovate bot checks for updates, and do not affect any specific dependencies/packages.
+
+### Schedule when to update specific dependencies
+
+The scheduling feature can be very useful for "noisy" packages that are updated frequently, such as `aws-sdk`.
+
+Say you want to restrict `aws-sdk` to weekly updates, you would create this package rule:
+
+```json
+{
+  "packageRules": [
+    {
+      "matchPackageNames": ["aws-sdk"],
+      "schedule": ["after 9pm on sunday"]
+    }
+  ]
+}
+```
+
+The "schedule" property must _always_ be defined in an array, even if you only set a single schedule.
+Multiple entries in the array means "or".
+
+Read the [schedule config option](https://docs.renovatebot.com/configuration-options/#schedule) documentation to earn more.
diff --git a/docs/usage/noise-reduction.md b/docs/usage/noise-reduction.md
index de2929281e..a44270a4c3 100644
--- a/docs/usage/noise-reduction.md
+++ b/docs/usage/noise-reduction.md
@@ -46,6 +46,8 @@ You will also have less flexibility about what to do when one or more in the gro
 
 ## Scheduling Renovate
 
+For a high level overview of scheduling when Renovate bot runs, read the [key concepts, scheduling](https://docs.renovatebot.com/key-concepts/scheduling/) docs.
+
 On its own, the Renovate CLI tool runs once and then exits.
 Hence, it only runs as often as its administrator sets it to (e.g. via `cron`).
 For the [Renovate app on GitHub](https://github.com/apps/renovate), it currently runs continuously using a job queue that gets refreshed hourly, or when you make relevant commits to your repository.
-- 
GitLab