Skip to content

Commit

Permalink
docs: rewrite FAQ (#8592)
Browse files Browse the repository at this point in the history
  • Loading branch information
@HonkingGoose
HonkingGoose committed Feb 9, 2021
1 parent cab5d4e commit 5831db6
Showing 1 changed file with 90 additions and 60 deletions.
150 changes: 90 additions & 60 deletions docs/usage/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,60 +5,64 @@ description: Frequently Asked Questions for Renovate Configuration

# Frequently Asked Questions (FAQ)

## What Is The Default Behavior?
## What is the default behavior?

Renovate will:

- Look for configuration options in a configuration file (e.g. `renovate.json`) and in each `package.json` file
- Find and process all package files (e.g. `package.json`, `package.js`, `Dockerfile`, etc) in each repository
- Find and process all package files (e.g. `package.json`, `composer.json`, `Dockerfile`, etc) in each repository
- Use separate branches/PR for each dependency
- Use separate branches for each _major_ version of each dependency
- Pin devDependencies to a single version, rather than use ranges
- Pin dependencies to a single version if it appears not to be a library
- Update `yarn.lock` and/or `package-lock.json` files if found
- Create Pull Requests immediately after branch creation

## What If I Need To .. ?
## What if I need to .. ?

### Use an alternative branch for Pull Request target
### Use an alternative branch as my Pull Request target

If for example your repository default branch is `master` but your Pull Requests should target branch `next`, then you can configure this via the `baseBranches` configuration option.
To do this, add this line to the `renovate.json` in the _default_ branch (i.e. `master` in this example).
Say your repository's default branch is `master` but you want Renovate to use the `next` branch as its PR target.
You can configure the PR target branch via the `baseBranches` option.

```
Add this line to the `renovate.json` file that's in the _default_ branch (`master` in this example).

```json
{
"baseBranches": ["next"]
}
```

You may configure more than one in the above.
You can set more than one PR target branch in the `baseBranches` array.

### Support private npm modules

See the dedicated [Private npm module support](/private-modules/) page.

### Control renovate's schedule
### Control Renovate's schedule

Renovate itself will run as often as its administrator has configured it (e.g. hourly, daily, etc).
But you may wish to update certain repositories less often, or even specific packages at a different schedule.
You may want to update certain repositories less often.
Or you may even want to use different schedules for specific packages.

If you want to control the days of the week or times of day that renovate updates packages, use the `timezone` and `schedule` configuration options.
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.

By default, Renovate schedules will use the UTC timezone.
This can be overridden in global config.
Finally, it can be overridden on a per-repository basis too, e.g.:
You can set a specific time zone in your local config file as well:

```
"timezone": "America/Los_Angeles",
```json
{
"timezone": "America/Los_Angeles"
}
```

The timezone must be one of the valid
[IANA time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
The timezone must be a valid [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

Now that your timezone is set, you can define days of week or hours of the day in which renovate will make changes.
For this we rely on text parsing of the library [later](https://bunkat.github.io/later/parsers.html#text) and its concepts of "days", "time_before", and "time_after".
With the timezone set, you can define days of week or hours of the day in which Renovate will make changes.
Renovate uses the [later](https://bunkat.github.io/later/parsers.html#text) library to parse the text.
The _later_ library also handles the concepts of "days", time_before", and "time_after".

Example scheduling:
Examples of the kind of schedules you can create:

```
every weekend
Expand All @@ -68,11 +72,11 @@ before 5:00am
on friday and saturday
```

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

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

```
```json
"packageRules": [
{
"matchPackageNames": ["aws-sdk"],
Expand All @@ -81,12 +85,12 @@ To restrict `aws-sdk` to only weekly updates, you could add this package rule:
]
```

Note that schedule must be in the form of an array, even if only one schedule is present.
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".

### Disable renovate for certain dependency types
### Disable Renovate for certain dependency types

Define a packageRules entry which has the dependency type(s) in `matchDepTypes` and `"enabled": false`.
Define a `packageRules` entry which has the dependency type(s) in `matchDepTypes` and `"enabled": false`.

### Use a single branch/PR for all dependency upgrades

Expand All @@ -96,42 +100,42 @@ Add a configuration for configuration option `groupName` set to value `"all"`, a

Set configuration option `separateMajorMinor` to `false`.

### Keep using semver ranges, instead of pinning dependencies
### Keep using SemVer ranges, instead of pinning dependencies

Set configuration option `rangeStrategy` to `"replace"`.

### Keep lock files (including sub-dependencies) up-to-date, even when `package.json` hasn't changed

This is enabled by default, but its schedule is set to `["before 5am on monday"]`.
If you want it more frequently, then update the `schedule` field inside the `lockFileMaintenance` object.
By default, if you enable lock-file maintenance, Renovate will update the lockfile `["before 5am on monday"]`.
If you want to update the lock file more often, update the `schedule` field inside the `lockFileMaintenance` object.

### Wait until tests have passed before creating the PR

Set configuration option `prCreation` to `"status-success"`.
Failing branches will never get a Pull Request created until they eventually pass.
Set the configuration option `prCreation` to `"status-success"`.
Branches with failing tests will remain in Git and continue to get updated if necessary, but no PR will be created until their tests pass.

### Wait until tests have passed before creating a PR, but create the PR even if they fail

Set configuration option `prCreation` to `"not-pending"`
Set the configuration option `prCreation` to `"not-pending"`.

### Assign PRs to specific user(s)

Set the configuration option `assignees` to an array of usernames.

### Add labels to PRs

Set the configuration option `labels` to an array of labels to use
Set the configuration option `labels` to an array of labels to use.

### Apply a rule, but only to package `abc`?

1. Add a `packageRules` array to your configuration
2. Create one object inside this array
3. Set field `matchPackageNames` to value `["abc"]`
4. Add the configuration option to the same object
1. Add a `packageRules` array to your configuration
2. Create one object inside this array
3. Set field `matchPackageNames` to value `["abc"]`
4. Add the configuration option to the same object

e.g.

```
```json
"packageRules": [
{
"matchPackageNames": ["abc"],
Expand All @@ -142,9 +146,9 @@ e.g.

### Apply a rule, but only for packages starting with `abc`

Do the same as above, but instead of using `matchPackageNames`, use `matchPackagePatterns` and a regex. e.g.
Do the same as above, but instead of using `matchPackageNames`, use `matchPackagePatterns` and a regex:

```
```json
"packageRules": [
{
"matchPackagePatterns": "^abc",
Expand All @@ -155,9 +159,9 @@ Do the same as above, but instead of using `matchPackageNames`, use `matchPackag

### Group all packages starting with `abc` together in one PR

As above, but apply a `groupName`, e.g.
As above, but apply a `groupName`:

```
```json
"packageRules": [
{
"matchPackagePatterns": "^abc",
Expand All @@ -168,31 +172,57 @@ As above, but apply a `groupName`, e.g.

### Change the default branch name, commit message, PR title or PR description

Set the `branchName`, `commitMessage`, `prTitle` or `prBody` configuration options:

```
"branchName": "vroom/{{depName}}-{{newMajor}}.x",
"commitMessage": "Vroom vroom dependency {{depName}} to version {{newValue}}",
"prTitle": "Vroom {{depName}},
```
You can use the `branchName`, `commitMessage`, `prTitle` or `prBody` configuration options to change the defaults for those settings.

### Automatically merge passing Pull Requests

Set configuration option `autoMerge` to `true`.
Set the configuration option `autoMerge` to `true`.
Nest it inside config objects `patch` or `minor` if you want it to apply to certain types only.

### Separate patch releases from minor releases

Renovate's default behavior is to separate major and minor releases, while patch releases are also consider "minor".
For example if you were running `q@0.8.7` you would receive one branch for the minor update to `q@0.9.7` and a second for the major update to `q@1.4.1`.
#### Renovate's default behavior for major/minor releases

Renovate's default behavior is to separate major and minor releases, patch releases are also considered "minor".
Let's explain the default behavior with an example:

Say you are using a package `snorgleborf`, it's the `0.8.0` version.
The `snorgleborf` maintainers then release the following versions:

- `0.8.1` (patch)
- `0.9.0` (minor)
- `1.0.0` (major)

Renovate would then open the following PRs:

- Update dependency `snorgleborf` to `0.9.0` (minor)
- Update dependency `snorgleborf` to `1.0.0` (major)

Note how Renovate groups the patch and minor versions together into one PR.
This means you only get a PR for the minor version, `0.9.0`.

You can override the default behavior.
To learn more read the section below.

#### Overriding the default behavior for major/minor releases

You can see in the example above that Renovate won't normally open a PR for the `snorgleborf` patch release.

There are 2 ways to tell renovate to open a separate PR for the patch release:

- Set `separateMinorPatch` to `true`
- Set `automerge` to the value: `"patch"`

In both cases, Renovate will open 3 PRs:

If you set the configuration option `separateMinorPatch` to `true`, or you configure `automerge` to have value `"patch"`, then Renovate will then separate patch releases as well.
For example, if you did this when running `q@0.8.7` then you'd receive three PRs - for `q@0.8.13`, `q@0.9.7` and `q@1.4.1`.
- Update dependency `snorgleborf` to `0.8.1` (patch)
- Update dependency `snorgleborf` to `0.9.0` (minor)
- Update dependency `snorgleborf` to `1.0.0` (major)

Of course, most people don't want _more_ PRs, so you would probably want to utilise this feature to make less work for yourself instead.
As an example, you might:
Most people don't want more PRs though.
But it can still be handy to get PRs for patches when using automerge:

- Update patch updates daily and automerge if they pass tests
- Update minor and major updates weekly
- Get daily patch updates which are automerged once tests pass
- Get weekly updates for minor and major updates.

The result of this would hopefully be that you barely notice Renovate during the week, while still getting the benefits of patch updates.
The end result would be that you barely notice Renovate during the week, while you still get the benefits of patch level updates.

0 comments on commit 5831db6

Please sign in to comment.