From 7eb629f43b1c07112432352cafe2760fb4693157 Mon Sep 17 00:00:00 2001
From: Rhys Arkins <rhys@arkins.net>
Date: Sun, 8 Dec 2019 16:46:43 +0100
Subject: [PATCH] docs: update config option descriptions

---
 docs/usage/configuration-options.md | 367 ++++++++++++++++++----------
 docs/usage/docker.md                |  69 ++++--
 lib/config/definitions.ts           |   2 +-
 renovate-schema.json                |   2 +-
 4 files changed, 289 insertions(+), 151 deletions(-)

diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md
index be2e3d332f..67249c6ed9 100644
--- a/docs/usage/configuration-options.md
+++ b/docs/usage/configuration-options.md
@@ -19,13 +19,13 @@ You can store your Renovate configuration file in one of the following locations
 
 Also, be sure to check out Renovate's [shareable config presets](/config-presets/) to save yourself from reinventing any wheels.
 
-If you have any questions about the below config options, or would like to get help/feedback about a config, please post it as an issue in [renovatebot/config-help](https://github.com/renovatebot/config-help) where it will be promptly answered.
+If you have any questions about the below config options, or would like to get help/feedback about a config, please post it as an issue in [renovatebot/config-help](https://github.com/renovatebot/config-help) where we will do our best to answer your question.
 
 ## aliases
 
-Package managers that support repo aliases can be configured here.
+The `aliases` object is used for configuring registry aliases. Currently it is needed/supported for the `helm-requiremenets` manager only.
 
-Currently only helm is supported, which contains this default repository alias:
+`helm-requirements` includes this default alias:
 
 ```json
 {
@@ -43,21 +43,21 @@ Add configuration here if you want to enable or disable something in particular
 
 ## assignAutomerge
 
-By default, Renovate will not assign reviewers and assignees if the PR is to be automerged, unless the status check failed. By configuring this setting, you can enable Renovate to always assign reviewers and assignees.
+By default, Renovate will not assign reviewers and assignees to an automerge-enabled PR unless it fails status checks. By configuring this setting to `true`, Renvoate will instead always assign reviewers and assignees for automerging PRs at time of creation.
 
 ## assignees
 
-Must be valid usernames.
+Must be valid usernames on the platform in use.
 
 ## assigneesSampleSize
 
-Take a random sample of given size from assignees.
+If configured, Renovate will take a random sample of given size from assignees and assign them only, instead of assigning the entire list of `assignees` you have configured.
 
 ## automerge
 
-By default, Renovate raises PRs but leaves them to someone/something else to merge them. By configuring this setting, you can enable Renovate to automerge branches or PRs itself, therefore reducing the amount of human intervention required.
+By default, Renovate raises PRs but leaves them to someone or something else to merge them. By configuring this setting, you can enable Renovate to automerge PRs or even branches itself, therefore reducing the amount of human intervention required.
 
-Usually you won't want to automerge _all_ PRs, for example most people would want to leave major dependency updates to a human to review first. In that case you will want to embed this setting inside `major`, `minor`, or `patch` configuration options. For example, you could add this to your `renovate.json` to automerge only non-major updates:
+Usually you won't want to automerge _all_ PRs, for example most people would want to leave major dependency updates to a human to review first. You could configure Renovate to automerge all but major this way:
 
 ```json
 {
@@ -70,7 +70,7 @@ Usually you won't want to automerge _all_ PRs, for example most people would wan
 }
 ```
 
-Also note that this option can be combined with other nested settings, such as dependency type. So for example you could elect to automerge all `devDependencies` only this way:
+Also note that this option can be combined with other nested settings, such as dependency type. So for example you could elect to automerge all (passing) `devDependencies` only this way:
 
 ```json
 {
@@ -83,12 +83,12 @@ Also note that this option can be combined with other nested settings, such as d
 }
 ```
 
-Warning: GitHub currently has a bug where automerge won't work if a GitHub Organization has protected their master branch, and there is no way to configure around this. Hence, automerging will try and fail in such situations. This doc will be updated once that bug/limitation is fixed by GitHub.
-
-Warning: GitHub won't do automerge if the PR has a negative feedback.
+Important: Renovate won't automerge on GitHub if a PR has a negative review outstanding.
 
 ## automergeComment
 
+Use this only if you configure `automergeType="pr-comment"`.
+
 Example use:
 
 ```json
@@ -101,11 +101,13 @@ Example use:
 
 ## automergeType
 
-This setting is only applicable if you opt in to set `automerge` to `true` for any of your dependencies.
+This setting is only applicable if you opt in to configure `automerge` to `true` for any of your dependencies.
 
-Automerging defaults to using Pull Requests (`automergeType="pr"`). In that case Renovate first creates a branch, then an associated Pull Request, and then automerges the first time it detects that the Pull Requests status checks are "green". Note: if you have no tests and still want to automerge, don't forget to configure `"requiredStatusChecks": null`.
+Automerging defaults to using Pull Requests (`automergeType="pr"`). In that case Renovate first creates a branch, then an associated Pull Request, and then automerges the first time it detects that the Pull Requests status checks are "green".
 
-If you prefer that Renovate more silently automerge _without_ Pull Requests at all, you can set `"automergeType": "branch"`. In this case Renovate will:
+Note: if you have no tests but still want Renovate to automerge, you need to add `"requiredStatusChecks": null` to your configuration.
+
+If you prefer that Renovate more silently automerge _without_ Pull Requests at all, you can configure `"automergeType": "branch"`. In this case Renovate will:
 
 - Create the branch, wait for test results
 - Rebase it any time it gets out of date with the base branch
@@ -116,9 +118,9 @@ The final value for `automergeType` is `"pr-comment"`, intended only for users w
 
 ## azureAutoComplete
 
-Setting this to true will set PRs in Azure DevOps to auto-complete after all (if any) branch policies have been met.
+Setting this to `true` will configure PRs in Azure DevOps to auto-complete after all (if any) branch policies have been met.
 
-You could also configure this using `packageRules`.
+You can also configure this using `packageRules` if you want to use it selectively (e.g. per-package).
 
 ## azureWorkItemId
 
@@ -126,45 +128,49 @@ When creating a PR in Azure DevOps, some branches can be protected with branch p
 
 ## baseBranches
 
-If left default (empty) then the default branch of the repository is used.
-
-For most projects, this should be left as default. An example use case for using this setting is a project who uses the default `master` branch for releases and a separate branch `next` for preparing for the next release. In that case, the project may prefer for Pull Requests from Renovate to be opened against the `next` branch instead of `master`.
+By default, Renovate will detect and process only the repository's default branch, e.g. `master`. For most projects, this is the expected approach. However, Renovate also allows users to explicitly configure `baseBranches`, e.g. for use cases such as:
 
-If instead the project needs _both_ `master` and `next` to be renovated, then both should be put into the `baseBranches` array.
+- You wish Renovate to process only a non-default branch, e.g. `dev`: `"baseBranches": ["dev"]`
+- You have multiple release streams you need Renovate to keep up to date, e.g. in branches `master` and `next`: `"baseBranches": ["master", "next"]`
 
-It's possible to add this setting into the `renovate.json` file as part of the "Configure Renovate" onboarding PR. If so then Renovate will reflect this setting in its description and use package file contents from the custom base branch instead of default.
+It's possible to add this setting into the `renovate.json` file as part of the "Configure Renovate" onboarding PR. If so then Renovate will reflect this setting in its description and use package file contents from the custom base branch(es) instead of default.
 
 ## bazel
 
+Bazel is quite unlike most other "package managers" that Renovate supports, which usually focus on a particular ecosystem like JavaScript, Ruby or Docker. Instead, Bazel is a build tool so supports a multitude of languages/datasources. Renovate does not support all possible Bazel references, although would like to, and feature requests are welcoe.
+
 ## bbUseDefaultReviewers
 
-Apply the default reviewers rules to PR's (Bitbucket only).
+Configuring this to `true` means that Renovate will detect and apply the default reviewers rules to PRs (Bitbucket only).
 
 ## branchName
 
-It's recommended to use our default templates, but you may override branch name if you really wish. It's recommended to still keep `depName` and `newMajor` in the branch name to make sure all other Renovate features can still work.
+Warning: it's strongly recommended not to configure this field directly. Use at your own risk. If you truly need to configure this then it probably means either:
 
-Example branch name: `renovate/eslint-4.x`.
+- You are hopefully mistaken, and there's a better approach you should use, so [ask here](https://github.com/renovatebot/config-help) or
+- You have a use case we didn't anticipate and we should have a feature request from you to add it to the project
 
 ## branchPrefix
 
-You can modify this field if you want to change the prefix used. For example if you want branches to be like `deps/eslint-4.x` instead of `renovate/eslint-4.x` then you set `branchPrefix` = `deps/`. Or if you wish to avoid forward slashes in branch names then you could use `renovate_` instead, for example.
+You can modify this field if you want to change the prefix used. For example if you want branches to be like `deps/eslint-4.x` instead of `renovate/eslint-4.x` then you configure `branchPrefix` = `deps/`. Or if you wish to avoid forward slashes in branch names then you could use `renovate_` instead, for example.
+
+Note that this setting does not change the default _onboarding_ branch name, i.e. `renovate/configure`. If you wish to change that too, you need to also configure the field `onboardingBranch` in your admin bot config.
 
 ## branchTopic
 
-This field is combined with `branchPrefix` and `managerBranchPrefix` to form the full `branchName`. `branchName` uniqueness is important for dependency update grouping or non-grouping so be cautious about ever editing this field manually.
+This field is combined with `branchPrefix` and `managerBranchPrefix` to form the full `branchName`. `branchName` uniqueness is important for dependency update grouping or non-grouping so be cautious about ever editing this field manually. This is an advance field and it's recommend you seek a config review before applying it.
 
 ## buildkite
 
 ## bumpVersion
 
-Set this value to `"patch"`, `"minor"` or `"major"` to have Renovate update the version in your edited `package.json`. e.g. if you wish Renovate to always increase the target `package.json` version with a patch update, set this to `"patch"`.
+Currently this setting supports `npm` only, so raise a feature request if you have a use for it with other package managers. It's purpose is if you want Renovate to update the `version` field within your file's `package.json` any time it updates depencies within. Usually this is for automatic release purposes, so that you don't need to add another step after Renovate before you can release a new version.
 
-You can also set this field to `"mirror:x"` where `x` is the name of a package in the `package.json`. Doing so means that the `package.json` `version` field will mirror whatever the version is that `x` depended on. Make sure that version is a pinned version of course, as otherwise it won't be valid.
+Configure this value to `"patch"`, `"minor"` or `"major"` to have Renovate update the version in your edited `package.json`. e.g. if you wish Renovate to always increase the target `package.json` version with a patch update, configure this to `"patch"`.
 
-## bundler
+You can also configure this field to `"mirror:x"` where `x` is the name of a package in the `package.json`. Doing so means that the `package.json` `version` field will mirror whatever the version is that `x` depended on. Make sure that version is a pinned version of course, as otherwise it won't be valid.
 
-Bundler is now in alpha stage and ready for testing! [Details](https://renovatebot.com/blog/ruby-bundler-support)
+## bundler
 
 ## cargo
 
@@ -172,14 +178,18 @@ Bundler is now in alpha stage and ready for testing! [Details](https://renovateb
 
 ## commitBody
 
-This is used whenever a commit `"body"` is needed, e.g. for adding `[skip ci]` or DCO signoff.
+Configure this if you wish Renovate to add a commit body, otherwise Renovate just uses a regular single-line commit.
 
 For example, To add `[skip ci]` to every commit you could configure:
 
 ```json
-{ "commitBody": "[skip ci]" }
+{
+  "commitBody": "[skip ci]"
+}
 ```
 
+Another example would be if you want to configure a DCO signoff to each commit.
+
 ## commitBodyTable
 
 ## commitMessage
@@ -188,7 +198,7 @@ Editing of `commitMessage` directly is now deprecated and not recommended. Pleas
 
 ## commitMessageAction
 
-This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. Actions may be like `Update`, `Pin`, `Roll back`, `Refresh`, etc.
+This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. Actions may be like `Update`, `Pin`, `Roll back`, `Refresh`, etc. Check out the default value for `commitMessage` to understand how this field is used.
 
 ## commitMessageExtra
 
@@ -220,11 +230,9 @@ This is used to manually restrict which versions are possible to upgrade to base
 
 ## composer
 
-Warning: composer support is in alpha stage so you probably only want to run this if you are helping get it feature-ready.
-
 ## configWarningReuseIssue
 
-Set this option to false if you prefer Renovate to open a new issue whenever there is config warning.
+Renovate's default behaviour is to reuse/reopen a single Config Warning issue in each repository so as to keep the "noise" down. However for some people this has the downside that the config warning won't be sorted near the top if you view issues by creation date. Configure this option to `false` if you prefer Renovate to open a new issue whenever there is a config warning.
 
 ## deps-edn
 
@@ -238,7 +246,18 @@ Add to this object if you wish to define rules that apply only to PRs that updat
 
 ## docker
 
-Add config here if you wish it to apply to all Docker package managers (Dockerfile, Docker Compose, CircleCI, etc).
+Add config here if you wish it to apply to Docker package managers Dockerfile and Docker Compose. If instead you mean to apply settings to any package manager that updates using the Docker _datasource_, use a package rule instead, e.g.
+
+```json
+{
+  "packageRules": [
+    {
+      "datasources": ["docker"],
+      "labels": ["docker-update"]
+    }
+  ]
+}
+```
 
 ## docker-compose
 
@@ -254,7 +273,15 @@ Add configuration here if you want to enable or disable something in particular
 
 ## enabled
 
-Renovate is enabled for all packages by default, but this setting allows you to disable Renovate for specific packages, dependency types, package files, or even for the whole repository.
+The most common use of `enabled` is if you want to turn Renovate's functionality off, for some reason.
+
+For example, if you wanted to disable Renovate completely on a repository, you could make this your `renovate.json`:
+
+```json
+{
+  "enabled": false
+}
+```
 
 To disable Renovate for all `eslint` packages, you can configure a package rule like:
 
@@ -269,13 +296,17 @@ To disable Renovate for all `eslint` packages, you can configure a package rule
 }
 ```
 
-To disable Renovate for `dependencies` but keep it for `devDependencies` you could configure:
+To disable Renovate for npm `devDependencies` but keep it for `dependencies` you could configure:
 
 ```json
 {
-  "dependencies": {
-    "enabled": false
-  }
+  "packageRules": [
+    {
+      "managers": ["npm"],
+      "depTypeList": ["devDependencies"],
+      "enabled": false
+    }
+  ]
 }
 ```
 
@@ -283,15 +314,13 @@ To disable Renovate for `dependencies` but keep it for `devDependencies` you cou
 
 This is a way to "whitelist" certain package managers and disable all others.
 
-By default, as Renovate supports more package managers we enable them once they are stable, but for some people only interested in perhaps npm dependencies, it can feel like "whack-a-mole" to keep disabling new ones you don't want.
-
 Possible managers are: `'ansible', 'bazel', 'buildkite', 'bundler', 'cargo', 'circleci', 'composer', 'deps-edn','docker-compose', 'dockerfile', 'droneci', 'github-actions', 'gitlabci', 'gitlabci-include', 'gomod', 'gradle', 'gradle-wrapper', 'homebrew', 'kubernetes', 'leiningen', 'maven', 'meteor', 'mix', 'npm', 'nuget', 'nvm', 'pip_requirements', 'pip_setup', 'pipenv', 'poetry', 'pub', 'sbt', 'swift', 'terraform', 'travis', 'ruby-version'`
 
 Example:
 
 ```json
 {
-  "enabledManagers": ["npm"]
+  "enabledManagers": ["dockerfile", "npm"]
 }
 ```
 
@@ -301,10 +330,12 @@ See [Private npm module support](https://docs.renovatebot.com/private-modules) f
 
 ## engines
 
-Extend this if you wish to configure rules specifically for `engines` definitions. Currently only `node` is supported.
+Extend this if you wish to configure rules specifically for `engines` definitions. Renovate extracts and updates `node`, `npm` and `yarn` fields within.
 
 ## excludeCommitPaths
 
+Warning: Advanced use!
+
 Be careful you know what you're doing with this option. The initial intended use is to allow the user to exclude certain dependencies from being added/removed/modified when "vendoring" dependencies. Example:
 
 ```json
@@ -313,49 +344,73 @@ Be careful you know what you're doing with this option. The initial intended use
 }
 ```
 
+The above would mean Renovate would not include files matching the above glob pattern in the commit, even if it thinks they should be updated.
+
 ## extends
 
 See [shareable config presets](https://docs.renovatebot.com/config-presets) for details.
 
 ## fileMatch
 
+`fileMatch` is used by Renovate to know which files in a repository to parse and extract, and it is possible to override defaults values to customize for your project's needs.
+
+Sometimes file matches are really simple - for example with Go Modules Renovate looks for any `go.mod` file, and you probably don't need to change that default.
+
+At other times, the possible files is too vague for Renovate to have any default. For default, Kubernetes manifests can exist in any `*.yaml` file and we don't want Renovate to parse every single YAML file in every repository just in case some of them contain a Kubernetes manifest, so Renovate's default `fileMatch` for manager `kubernetes` is actually empty (`[]`) and needs the user to tell Renovate what directories/files to look in.
+
+Finally, there are cases where Renovate's default `fileMatch` is good, but you may be using file patterns that a bot couldn't posibly guess about. For example, Renovate's default `fileMatch` for `Dockerfile` is `['(^|/)Dockerfile$', '(^|/)Dockerfile\\.[^/]*$']`. This will catch files like `backend/Dockerfile` or `Dockerfile.base`, but it will miss files like `ACTUALLY_A_DOCKERFILE.template`. Because `fileMatch` is mergeable, you don't need to duplicate the defaults and could just add the missing file like this:
+
+```json
+{
+  "dockerfile": {
+    "fileMatch": ["^ACTUALLY_A_DOCKERFILE.template$"]
+  }
+}
+```
+
 ## followTag
 
-The primary use case for this option is if you are following a pre-release tag of a certain dependency, e.g. `typescript` "insiders" build. When it's configured, Renovate bypasses its normal major/minor/patch logic and stable/unstable logic and simply raises a PR if the tag does not match your current version.
+Caution: advanced functionality. Only use it if you're sure you know what you're doing.
+
+This functionality requires that the datasource to support distribution streams/tags, such as npm does.
+
+The primary use case for this option is if you are following a pre-release tag of a certain dependency, e.g. `typescript`'s `"insiders"` build. If configured, Renovate bypasses its normal major/minor/patch upgrade logic and stable/unstable consistency logic and keeps your dependency version sync'd strictly to whatever version is in the tag.
+
+Beware that Renovate follows tags strictly. For example, if you are following a tag like `next` and then that stream is released as `stable` and `next` is no longer being updated then that means your dependencies also won't be getting updated.
 
 ## git-submodules
 
 ## gitLabAutomerge
 
-Please note that when this option is enabled it is possible that MRs with failing pipelines are getting merged. This is caused by a race condition in GitLab's Merge Request API - [read the corresponding issue](https://gitlab.com/gitlab-org/gitlab/issues/26293) for details.
+Caution: when this option is enabled it is possible due to a bug in GitLab that MRs with failing pipelines might still get merged. This is caused by a race condition in GitLab's Merge Request API - [read the corresponding issue](https://gitlab.com/gitlab-org/gitlab/issues/26293) for details.
 
 ## github-actions
 
-**Important note**: For security reasons, GitHub has blocked integrations/apps from editing GitHub Actions workflow files in _any_ branch, so this only works on GitHub if using a Personal Access Token.
+**Important note**: For security reasons, GitHub has blocked integrations/apps from editing GitHub Actions workflow files in _any_ branch, so this only works on GitHub if using a Personal Access Token instead of using the WhiteSource Renovate app.
 
-Add to this configuration setting if you need to override any of the GitHub Actions default settings. Use the `docker` config object instead if you wish for configuration to apply across all Docker-related package managers.
+Add to this configuration setting if you need to override any of the GitHub Actions default settings.
 
 ## gitlabci
 
-Add to this configuration setting if you need to override any of the GitLab CI default settings. Use the `docker` config object instead if you wish for configuration to apply across all Docker-related package managers.
+Add to this configuration setting if you need to override any of the GitLab CI default settings.
 
 ## gitlabci-include
 
-Add to this configuration setting if you need to override any of the GitLab CI default settings. Applies to the `include:` section only.
+Add to this configuration setting if you need to override any of the GitLab CI Includes default settings. Applies to the `include:` section only.
 
 ## golang
 
-Configuration added here applies for all Go-related updates, however currently the only supported package manager for Go is the native Go Modules (`go mod`).
+Configuration added here applies for all Go-related updates, however currently the only supported package manager for Go is the native Go Modules (the `gomod` manager).
 
 ## gomod
 
-Configuration for Go Modules (`go mod`). Supersedes anything in the `go` config object.
+Configuration for Go Modules. Supersedes anything in the `golang` config object.
 
-You might be interested to add `"postUpdateOptions": ["gomodTidy"]` to your config if you'd like Renovate to run `go mod tidy` after any update.
+You might be interested to add `"postUpdateOptions": ["gomodTidy"]` to your config if you'd like Renovate to run `go mod tidy` after every update before raising the PR.
 
 ## gradle
 
-Configuration for Java gradle projects
+Configuration for Java gradle projects.
 
 ## gradle-wrapper
 
@@ -363,33 +418,63 @@ Configuration for Gradle Wrapper updates. Changes here affect how Renovate updat
 
 ## group
 
+Caution: Advanced functionality only. Do not use unless you know what you're doing.
+
 The default configuration for groups are essentially internal to Renovate and you normally shouldn't need to modify them. However, you may choose to _add_ settings to any group by defining your own `group` configuration object.
 
 ## groupName
 
-There are multiple cases where it can be useful to group multiple upgrades together. Internally Renovate uses this for branches such as "Pin Dependencies", "Lock File Maintenance", etc. Another example used previously is to group together all related `eslint` packages, or perhaps `angular` or `babel`. To enable grouping, you set the `groupName` field to something non-null.
+There are multiple cases where it can be useful to group multiple upgrades together. Internally Renovate uses this for branches such as "Pin Dependencies", "Lock File Maintenance", etc. Another example used previously is to group together all related `eslint` packages, or perhaps `angular` or `babel`. To enable grouping, you configure the `groupName` field to something non-null.
+
+The `groupName` field allows free text and does not have any semantic interpretation by Renovate. All updates sharing the same `groupName` will be placed into the same branch/PR. For example, to group all non-major devDependencies updates together into a single PR:
+
+```json
+{
+  "packageRules": [
+    {
+      "depTypeList": ["devDependencies"],
+      "updateTypes": ["patch", "minor"],
+      "groupName": "devDependencies (non-major)"
+    }
+  ]
+}
+```
 
 ## groupSlug
 
-By default, Renovate will "slugify" the groupName to determine the branch name. For example if you named your group "All eslint packages" then the branchName would be `renovate/all-eslint-packages`. If you wished to override this then you could set like this:
+By default, Renovate will "slugify" the groupName to determine the branch name. For example if you named your group "devDependencies (non-major)" then the branchName would be `renovate/devdependencies-non-major`. If you wished to override this then you could configure like this:
 
 ```json
 {
-  "groupName": "eslint packages",
-  "groupSlug": "eslint"
+  "packageRules": [
+    {
+      "depTypeList": ["devDependencies"],
+      "updateTypes": ["patch", "minor"],
+      "groupName": "devDependencies (non-major)",
+      "groupSlug": "dev-dependencies"
+    }
+  ]
 }
 ```
 
-And then the branchName would be `renovate/eslint` instead.
+As a result of the above, the branchName would be `renovate/dev-dependencies` instead.
+
+Note: you shouldn't usually need to configure this unless you really care about your branch names.
 
 ## helm-requirements
 
+Renovate supports updating Helm Chart references within `requirements.yaml` files. If your Helm charts make use of Aliases then you will need to configure an `aliases` object in your config to tell Renovate where to look for them.
+
 ## homebrew
 
 ## hostRules
 
+Currently the purpose of `hostRules` is to configure credentials for host authentication. You tell Renovate how to match against the host you need authenticated, and then you also tell it which credentials to use.
+
 The lookup keys for a hostRule are: `hostType`, `domainName`, `hostName`, and `baseUrl`. All are optional, but you can only have one of the last three per rule.
 
+Supported credential fields are `token`, `username`, `password`, `timeout` and `insecureRegistry`.
+
 Example for configuring `docker` auth:
 
 ```json
@@ -406,18 +491,26 @@ Example for configuring `docker` auth:
 
 ### baseUrl
 
-Renovate will match against all baseUrls. It does not do a "longest match" algorithm so if you want one baseUrl to override another than make sure it occurs _after_ the first one in the order of `hostRules`.
+Use this instead of `domainName` or `hostName` if you need a rule to apply to a specific path on a host. For example, `"baseUrl": "https://api.github.com"` is equivalent to `"hostName": "api.github.com"` but `"baseUrl": "https://api.github.com/google/"` is not.
+
+Renovate does not do a "longest match" algorithm to pick between multiple matching `baseUrl` values in different rules, so put the longer `baseUrl` rule _after_ the shorter one in your `hostRules`.
 
 ### domainName
 
+If you have any uncertainty about exactly which hosts a service uses, then it can be more reliable to use `domainName` instead of `hostName` or `baseUrl`. e.g. configure `"hostName": "docker.io"` to cover both `index.docker.io` and `auth.docker.io` and any other host that's in use.
+
 ### hostName
 
 ### hostType
 
+`hostType` is another way to filter rules and can be either a platform such as `github` and `bitbucket-server`, or it can be a datasource such as `docker` and `rubygems`. You usually don't need to configure it in a host rule if you have already configured `domainName`, `hostName` or `baseUrl` and only one host type is in use for those, as is usually the case. `hostType` can help for cases like an enterprise registry that serves multiple package types and has different authentication for each, although it's often the case that multiple `baseUrl` rules could achieve the same thing.
+
 ### insecureRegistry
 
-Enable this option to allow Renovate to connect to an [insecure docker registry](https://docs.docker.com/registry/insecure/) that is http only.
-Warning: This is insecure and is not recommended.
+Warning: Advanced config, use at own risk.
+
+Enable this option to allow Renovate to connect to an [insecure docker registry](https://docs.docker.com/registry/insecure/) that is http only. This is insecure and is not recommended.
+
 Example:
 
 ```json
@@ -447,7 +540,9 @@ Use this figure to adjust the timeout for queries. The default is 60s, which is
 
 ## ignoreDeprecated
 
-By default, Renovate won't update any packages to deprecated versions unless the package version was _already_ deprecated. The goal of this is to make sure you don't upgrade from a non-deprecated version to a deprecated one just because it's higher than the current version. If for some reason you wish to _force_ deprecated updates on Renovate, you can set `ignoreDeprecated` to `false`, but this is not recommended for most situations.
+By default, Renovate won't update a dependency version to a deprecated release unless the current version was _itself_ deprecated. The goal of this is to make sure you don't upgrade from a non-deprecated version to a deprecated one just because it's higher than the current version.
+
+If for some reason you wish to _force_ deprecated updates with Renovate, you can configure `ignoreDeprecated` to `false`, but this is not recommended for most situations.
 
 ## ignoreDeps
 
@@ -459,11 +554,22 @@ The `ignoreDeps` configuration field allows you to define a list of dependency n
 }
 ```
 
-You could also configure this using `packageRules`, especially if you need patterns.
+The above is the same as if you wrote this package rule:
+
+```json
+{
+  "packageRules": [
+    {
+      "packageNames": ["eslint", "eslint-config-base"],
+      "enabled": false
+    }
+  ]
+}
+```
 
 ## ignoreNpmrcFile
 
-There may be times where an `.npmrc` file in your repository causes problems, such as during lock file generation. Set this to true and Renovate will ignore any `.npmrc` files it finds.
+By default, Renovate will look for and use any `.npmrc` file it finds in a repository. Additionally, it will be read in by `npm` or `yarn` at the time of lock file generation. Sometimes this causes problems, for example if the file contains placeholder values, so you can configure this to `true` and Renovate will ignore any `.npmrc` files it finds and temporarily remove the file before running `npm install` or `yarn install`. Renovate will try to configure this to `true` also if you have configured any `npmrc` string within your config file.
 
 ## ignorePaths
 
@@ -471,7 +577,7 @@ Using this setting, you can selectively ignore package files that you don't want
 
 ## ignorePresets
 
-Use this if you are extending a complex preset but won't want to use every "sub preset" that it uses. For example, take this config:
+Use this if you are extending a complex preset but don't want to use every "sub preset" that it includes. For example, consinder this config:
 
 ```json
 {
@@ -488,23 +594,26 @@ Applicable for npm and composer only for now. Set this to `true` if running scri
 
 ## ignoreUnstable
 
-By default, Renovate won't update any package versions to unstable versions (e.g. `4.0.0-rc3`) unless the current version has the same major.minor.patch and was _already_ unstable (e.g. it was already on `4.0.0-rc2`). Renovate will not "jump" unstable versions automatically, e.g. if you are on `4.0.0-rc2` and newer versions `4.0.0` and `4.1.0-alpha.1` exist then Renovate will update you to `4.0.0` only. If you need to force permanent unstable updates for a package, you can add a package rule setting `ignoreUnstable` to `false`.
+By default, Renovate won't update any package versions to unstable versions (e.g. `4.0.0-rc3`) unless the current version has the same `major.minor.patch` and was _already_ unstable (e.g. it was already on `4.0.0-rc2`). Renovate will also not "jump" unstable versions automatically, e.g. if you are on `4.0.0-rc2` and newer versions `4.0.0` and `4.1.0-alpha.1` exist then Renovate will update you to `4.0.0` only. If you need to force permanent unstable updates for a package, you can add a package rule setting `ignoreUnstable` to `false`.
 
 Also check out the `followTag` configuration option above if you wish Renovate to keep you pinned to a particular release tag.
 
 ## includeForks
 
-By default, the bot will skip over any repositories that are forked, even if they contain a config file, because that config may have been from the source repository anyway. To enable processing of a forked repository, you need to add `"includeForks": true` to your config or run the CLI command with `--include-forks`. If you are using the hosted Renovate application then you need to add a `renovate.json` to your forked repo manually, and include `"includeForks": true` inside.
+By default, Renovate will skip over any repositories that are forked. This includes if the forked repository contain a Renovate config file, because Renovate can't tell if that file was added by the original repository or not. If you wish to enable processing of a forked repository by Renovate, you need to add `"includeForks": true` to your repository config or run the CLI command with `--include-forks=true`.
+
+If you are using the hosted WhiteSource Renovate then this option will be configured to `true` automatically if you "Selected" repositories individually but remain as `false` if you installed for "All" repositories.
 
 ## includePaths
 
 If you wish for Renovate to process only select paths in the repository, use `includePaths`.
-If instead you need to just exclude/ignore certain paths then consider `ignorePaths` instead.
+
+Alternatively, if you need to just _exclude_ certain paths in the repository then consider `ignorePaths` instead.
 If you are more interested in including only certain package managers (e.g. `npm`), then consider `enabledManagers` instead.
 
 ## java
 
-Use this configuration option for shared config across all java projects.
+Use this configuration option for shared config across all java projects (Gradle and Maven).
 
 ## js
 
@@ -512,16 +621,16 @@ Use this configuration option for shared config across npm/yarn/pnpm and meteor
 
 ## kubernetes
 
-Add to this configuration object if you need to override any of the Kubernetes default settings. Use the `docker` config object instead if you wish for configuration to apply across all Docker-related package managers.
+Add to this configuration object if you need to override any of the Kubernetes manager default settings. Use the `docker` config object instead if you wish for configuration to apply across all Docker-related package managers.
 
-It's important to note that the `kubernetes` manager by default has no `fileMatch` defined - i.e. so it will never match any files. This is because there is no commonly accepted file/directory naming convention for Kubernetes yaml files and we don't want to download every single `.yaml` file in repositories just in case one of them has Kubernetes definitions inside.
+It's important to note that the `kubernetes` manager by default has no `fileMatch` defined - i.e. so it will never match any files unless you configure it. This is because there is no commonly accepted file/directory naming convention for Kubernetes YAML files and we don't want to download every single `*.yaml` file in repositories just in case any of them contain Kubernetes definitions.
 
 If most `.yaml` files in your repository are Kubnernetes ones, then you could add this to your config:
 
 ```json
 {
   "kubernetes": {
-    "fileMatch": ["(^|/)[^/]*\\.yaml$"]
+    "fileMatch": ["\\.yaml$"]
   }
 }
 ```
@@ -541,26 +650,42 @@ Or if it's just a single file then something like this:
 ```json
 {
   "kubernetes": {
-    "fileMatch": ["^config/k8s.yaml$"]
+    "fileMatch": ["^config/k8s\\.yaml$"]
   }
 }
 ```
 
 ## labels
 
-Add an array of 1 or more strings to `labels` and Renovate will apply these labels to any PR its created. Usually these will be a per-repository setting like `"renovate"`, or `"ready"`, or `"dependencies"`, however you can configure them right down to per-package level.
+By default, Renovate won't add any labels to its PRs. If you want Renovate to do so then define a `labels` array of one or more label strings. If you want the same label(s) for every PR then you can configure it at the top level of config. However you can also fully override them on a per-package basis.
+
+Consider this example:
+
+```json
+{
+  "labels": ["dependencies"],
+  "packageRules": [
+    {
+      "packagePatterns": ["eslint"],
+      "labels": ["linting"]
+    }
+  ]
+}
+```
+
+With the above config, every PR raised by Renovate will have the label `dependencies` while PRs containing `eslint`-related packages will instead have the label `linting`.
 
 ## lazyGrouping
 
-The default behaviour for Renovate is to only use group names for branches and PRs when there's more than one dependency in a group. For example you may have defined a dependency group calls "All eslint packages" with a `packagePattern` of `^eslint`, but if the only upgrade available at the time is `eslint-config-airbnb` then it makes more sense for the PR to be named "Upgrade eslint-config-airbnb to version 2.1.4" than to name it "Upgrade All eslint packages". If ever this behaviour is undesirable then you can override it by setting this option to `false`.
+By default, Renovate will use group names in Pull Request titles only when the PR contains two or more dependencies. For example you may have defined a dependency group calls "All eslint packages" with a `packagePattern` of `^eslint`, but if the only upgrade available at the time is `eslint-config-airbnb` then it makes more sense for the PR to be named "Upgrade eslint-config-airbnb to v2.1.4" than to name it "Upgrade All eslint packages". If ever this behaviour is undesirable then you can override it by setting this option to `false`.
 
 ## leiningen
 
 ## lockFileMaintenance
 
-This feature can be used to "maintain" lock files for each `package.json` if they exist already. "Maintaining" a lock file means recreating it to get an up-to-date version and committing that. Supported lock files include `package-lock.json` (npm >= 5) and `yarn.lock` (yarn).
+This feature can be used to refresh lock files and keep them up-to-date. "Maintaining" a lock file means recreating it so that every dependency version within it is updated to the latest. Supported lock files are `package-lock.json`, `yarn.lock` and `composer.lock`. Others may be added via feature request.
 
-This feature is off by default. If you wish to enable this feature then you could add this to your configuration:
+This feature is disabled by default. If you wish to enable this feature then you could add this to your configuration:
 
 ```json
 {
@@ -568,11 +693,7 @@ This feature is off by default. If you wish to enable this feature then you coul
 }
 ```
 
-To reduce "noise" in the repository, it defaults its schedule to "before 5am on monday", i.e. to achieve once per week semantics. Renovate may run a few times within that time - even possibly updating the lock file more than once - but it hopefully leaves enough time for tests to run and automerge to apply, if configured.
-
-The `recreateClosed` setting is necessary to tell Renovate to override its default behaviour of never recreating a PR if the same-titled one previously existed, so do not modify this.
-
-`commitMessage`, `prTitle` and `prBody` are custom templates to make sure that the branch and PR have names that make sense. You may override these with your own settings if you prefer.
+To reduce "noise" in the repository, it defaults its schedule to `"before 5am on monday"`, i.e. to achieve once-per-week semantics. Depending on its running schedule, Renovate may run a few times within that time window - even possibly updating the lock file more than once - but it hopefully leaves enough time for tests to run and automerge to apply, if configured.
 
 ## major
 
@@ -580,20 +701,20 @@ Add to this object if you wish to define rules that apply only to major updates.
 
 ## managerBranchPrefix
 
-This value defaults to empty string, as historically no prefix was necessary for when Renovate was JS-only. Now - for example - we use `docker-` for Docker branches, so they may look like `renovate/docker-ubuntu-16.x`.
+This value defaults to an empty string, because historically no prefix was necessary for when Renovate was JS-only. Now - for example - we use `docker-` for Docker branches, so they may look like `renovate/docker-ubuntu-16.x`. You normally don't need to configure this.
 
 ## masterIssue
 
-Configuration `masterIssue` to `true` will lead to the creation of a "Master Issue" within the repository. This Master Issue is akin to a mini dashboard and contains a list of all PRs pending, open, closed (unmerged) or in error.
+Configuring `masterIssue` to `true` will lead to the creation of a mini-dashboard "Master Issue" within the repository. This Master Issue contains a list of all PRs pending, open, closed (unmerged) or in error. The goal of this master issue is to give visibility into all updates that Renovate is managing.
 
 Examples of what having a master issue will allow you to do:
 
 - View all PRs in one place, rather than having to filter PRs by author
 - Rebase/retry multiple PRs without having to open each individually
 - Override any rate limiting (e.g. concurrent PRs) or scheduling to force Renovate to create a PR that would otherwise be suppressed
-- Recreate an unmerged PR (e.g. for a major update that you put off by closing the original PR)
+- Recreate an unmerged PR (e.g. for a major update that you postponed by closing the original PR)
 
-Note: Enabling the Master Issue does not itself change any of the "flow" of Renovate, e.g. it will otherwise still create and manage PRs exactly as it always has. The Master Issue therefore provides visibility as well as additional control.
+Note: Enabling the Master Issue does not itself change any of the "control flow" of Renovate, e.g. it will otherwise still create and manage PRs exactly as it always has, including scheduling and rate limiting. The Master Issue therefore provides visibility as well as additional control.
 
 ## masterIssueApproval
 
@@ -601,39 +722,26 @@ Setting `masterIssueApproval` to `true` means that Renovate will no longer creat
 
 In this case, the Master Issue _does_ change the flow of Renovate, because PRs will stop appearing until you approve them within the issue. Instead of enabling this repository-wide, you may instead with to use package rules to enable it selectively, e.g. for major updates only, or for certain package managers, etc. i.e. it is possible to require approval for only certain types of updates only.
 
-Note: Enabling Master Issue Approval implicitly enables `masterIssue` too, so it is not necessary to set both to `true`.
+Note: Enabling Master Issue Approval implicitly enables `masterIssue` too, so it is not necessary to configure both to `true`.
 
 ## masterIssueAutoclose
 
-You can set this to `true` if you prefer Renovate to autoclose its Master Issue whenever there are no outstanding PRs left.
+You can configure this to `true` if you prefer Renovate to close an existing Master Issue whenever there are no outstanding PRs left.
 
 ## masterIssueTitle
 
-Set this option if you prefer a different title for the Master Issue.
+Configure this option if you prefer a different title for the Master Issue.
 
 ## maven
 
 ## meteor
 
-Set enabled to `true` to enable meteor package updating.
-
 ## minor
 
 Add to this object if you wish to define rules that apply only to minor updates.
 
 ## mix
 
-Elixir support is in beta stage.
-It should be explicitly enabled in configuration file:
-
-```json
-{
-  "mix": {
-    "enabled": true
-  }
-}
-```
-
 ## node
 
 Using this configuration option allows you to apply common configuration and policies across all Node.js version updates even if managed by different package managers (`npm`, `yarn`, etc.).
@@ -665,7 +773,7 @@ The `nuget` configuration object is used to control settings for the NuGet packa
 
 ## nvm
 
-For settings common to all node.js version updates (e.g. travis, nvm, etc) you can use the `node` object instead.
+For settings common to all node.js version updates (e.g. travis, nvm, etc) you can use the `node` object instead of this.
 
 ## packageRules
 
@@ -867,7 +975,7 @@ Use this field if you want to have one or more exact name matches in your packag
 }
 ```
 
-The above will enable set `rangeStrategy` to `pin` only for the package `angular`.
+The above will configure `rangeStrategy` to `pin` only for the package `angular`.
 
 ### packagePatterns
 
@@ -884,7 +992,7 @@ Use this field if you want to have one or more package names patterns in your pa
 }
 ```
 
-The above will set `rangeStrategy` to `replace` for any package starting with `angular`.
+The above will configure `rangeStrategy` to `replace` for any package starting with `angular`.
 
 ### paths
 
@@ -1048,7 +1156,7 @@ This setting tells Renovate when you would like it to raise PRs:
 - `not-pending`: Renovate will wait until status checks have completed (passed or failed) before raising the PR
 - `status-success`: Renovate won't raise PRs unless tests pass
 
-Renovate defaults to `immediate` but some like to change to `not-pending`. If you set to immediate, it means you will usually get GitHub notifications that a new PR is available but if you view it immediately then it will still have "pending" tests so you can't take any action. With `not-pending`, it means that when you receive the PR notification, you can see if it passed or failed and take action immediately. Therefore you can customise this setting if you wish to be notified a little later in order to reduce "noise".
+Renovate defaults to `immediate` but some like to change to `not-pending`. If you configure to immediate, it means you will usually get GitHub notifications that a new PR is available but if you view it immediately then it will still have "pending" tests so you can't take any action. With `not-pending`, it means that when you receive the PR notification, you can see if it passed or failed and take action immediately. Therefore you can customise this setting if you wish to be notified a little later in order to reduce "noise".
 
 ## prHourlyLimit
 
@@ -1060,13 +1168,13 @@ This setting - if enabled - helps slow down Renovate, particularly during the on
 4.  User merges Pin PR
 5.  Renovate then creates every single upgrade PR necessary - potentially dozens
 
-The above can result in swamping CI systems, as well as a lot of retesting if branches need to be rebased every time one is merged. Instead, if `prHourlyLimit` is set to a value like 1 or 2, it will mean that Renovate creates at most that many new PRs within each hourly period (:00-:59). So the project should still result in all PRs created perhaps within the first 24 hours maximum, but at a rate that may allow users to merge them once they pass tests. It does not place a limit on the number of _concurrently open_ PRs - only on the rate they are created.
+The above can result in swamping CI systems, as well as a lot of retesting if branches need to be rebased every time one is merged. Instead, if `prHourlyLimit` is configure to a value like 1 or 2, it will mean that Renovate creates at most that many new PRs within each hourly period (:00-:59). So the project should still result in all PRs created perhaps within the first 24 hours maximum, but at a rate that may allow users to merge them once they pass tests. It does not place a limit on the number of _concurrently open_ PRs - only on the rate they are created.
 
 Note that this limit is enforced on a per-repository basis.
 
 ## prNotPendingHours
 
-If you set `prCreation=not-pending`, then Renovate will wait until tests are non-pending (all pass or at least one fails) before creating PRs. However there are cases where PRs may remain in pending state forever, e.g. absence of tests or status checks that are set to pending indefinitely. Therefore we set an upper limit - default 24 hours - for how long we wait until creating a PR. Note also this is the same length of time as for Renovate's own `unpublishSafe` status check for npm.
+If you configure `prCreation=not-pending`, then Renovate will wait until tests are non-pending (all pass or at least one fails) before creating PRs. However there are cases where PRs may remain in pending state forever, e.g. absence of tests or status checks that are configure to pending indefinitely. Therefore we configure an upper limit - default 24 hours - for how long we wait until creating a PR. Note also this is the same length of time as for Renovate's own `unpublishSafe` status check for npm.
 
 ## prPriority
 
@@ -1095,8 +1203,7 @@ The PR title is important for some of Renovate's matching algorithms (e.g. deter
 
 ## pruneStaleBranches
 
-Set to `false` to disable deleting orphan branches and autoclosing PRs.
-Defaults to `true`.
+Configure to `false` to disable deleting orphan branches and autoclosing PRs. Defaults to `true`.
 
 ## pub
 
@@ -1127,13 +1234,13 @@ Renovate's `"auto"` strategy works like this for npm:
 
 By default, Renovate assumes that if you are using ranges then it's because you want them to be wide/open. As such, Renovate won't deliberately "narrow" any range by increasing the semver value inside.
 
-For example, if your `package.json` specifies a value for `left-pad` of `^1.0.0` and the latest version on npmjs is `1.2.0`, then Renovate won't change anything because `1.2.0` satisfies the range. If instead you'd prefer to be updated to `^1.2.0` in cases like this, then set `rangeStrategy` to `bump` in your Renovate config.
+For example, if your `package.json` specifies a value for `left-pad` of `^1.0.0` and the latest version on npmjs is `1.2.0`, then Renovate won't change anything because `1.2.0` satisfies the range. If instead you'd prefer to be updated to `^1.2.0` in cases like this, then configure `rangeStrategy` to `bump` in your Renovate config.
 
 This feature supports simple caret (`^`) and tilde (`~`) ranges only, like `^1.0.0` and `~1.0.0`.
 
 ## rebaseConflictedPrs
 
-This field defaults to `true` which means Renovate will rebase whenever there is a merge conflict with the master branch. However, this default behavior may result in costing a lot of CI cycles. If you wish to disable auto-rebasing in case of merge conflicts with the master branch, set it's value to `false`.
+This field defaults to `true` which means Renovate will rebase whenever there is a merge conflict with the master branch. However, this default behavior may result in costing a lot of CI cycles. If you wish to disable auto-rebasing in case of merge conflicts with the master branch, configure it's value to `false`.
 
 ## rebaseLabel
 
@@ -1141,9 +1248,9 @@ On GitHub it is possible to add a label to a PR to manually request Renovate to
 
 ## rebaseStalePrs
 
-This field defaults to `null` because it has the potential to create a lot of noise and additional builds to your repository. If you enable it to true, it means each Renovate branch will be updated whenever the base branch has changed. If enabled, this also means that whenever a Renovate PR is merged (whether by automerge or manually via GitHub web) then any other existing Renovate PRs will then need to get rebased and retested.
+This field defaults to `null` because it has the potential to create a lot of noise and additional builds to your repository. If you enable it to `true`, it means each Renovate branch will be updated whenever the base branch has changed. If enabled, this also means that whenever a Renovate PR is merged (whether by automerge or manually via GitHub web) then any other existing Renovate PRs will then need to get rebased and retested.
 
-If you set it to `false` then that will take precedence - it means Renovate will ignore if you have configured the repository for "Require branches to be up to date before merging" in Branch Protection. However if you have configured it to `false` _and_ configured `branch` automerge then Renovate will still rebase as necessary for that.
+If you configure it to `false` then that will take precedence - it means Renovate will ignore if you have configured the repository for "Require branches to be up to date before merging" in Branch Protection. However if you have configured it to `false` _and_ configured `branch` automerge then Renovate will still rebase as necessary for that.
 
 ## recreateClosed
 
@@ -1179,7 +1286,7 @@ Take a random sample of given size from reviewers.
 
 ## rollbackPrs
 
-Set this to false either globally, per-language, or per-package if you want to disable Renovate's behaviour of generating rollback PRs when it can't find the current version on the registry anymore.
+Configure this to `false` either globally, per-language, or per-package if you want to disable Renovate's behaviour of generating rollback PRs when it can't find the current version on the registry anymore.
 
 ## ruby
 
@@ -1247,7 +1354,7 @@ By default you will see angular-style commit prefixes like `"chore(deps):"`. If
 
 ## semanticCommits
 
-If you are using a semantic prefix for your commits, then you will want to enable this setting. Although it's configurable to a package-level, it makes most sense to configure it at a repository level. If set to true, then the `semanticPrefix` field will be used for each commit message and PR title.
+If you are using a semantic prefix for your commits, then you will want to enable this setting. Although it's configurable to a package-level, it makes most sense to configure it at a repository level. If configured to `true`, then the `semanticPrefix` field will be used for each commit message and PR title.
 
 However, please note that Renovate will autodetect if your repository is already using semantic commits or not and follow suit, so you only really need to configure this if you wish to _override_ Renovate's autodetected setting.
 
@@ -1255,19 +1362,19 @@ However, please note that Renovate will autodetect if your repository is already
 
 Renovate's default behaviour is to create a separate branch/PR if both minor and major version updates exist. For example, if you were using Webpack 2.0.0 and versions 2.1.0 and 3.0.0 were both available, then Renovate would create two PRs so that you have the choice whether to apply the minor update to 2.x or the major update of 3.x. If you were to apply the minor update then Renovate would keep updating the 3.x branch for you as well, e.g. if Webpack 3.0.1 or 3.1.0 were released. If instead you applied the 3.0.0 update then Renovate would clean up the unneeded 2.x branch for you on the next run.
 
-It is recommended that you leave this setting to true, because of the polite way that Renovate handles this. For example, let's say in the above example that you decided you wouldn't update to Webpack 3 for a long time and don't want to build/test every time a new 3.x version arrives. In that case, simply close the "Update Webpack to version 3.x" PR and it _won't_ be recreated again even if subsequent Webpack 3.x versions are released. You can continue with Webpack 2.x for as long as you want and receive any updates/patches that are made for it. Then eventually when you do want to update to Webpack 3.x you can make that update to `package.json` yourself and commit it to master once it's tested. After that, Renovate will resume providing you updates to 3.x again! i.e. if you close a major upgrade PR then it won't come back again, but once you make the major upgrade yourself then Renovate will resume providing you with minor or patch updates.
+It is recommended that you leave this setting to `true`, because of the polite way that Renovate handles this. For example, let's say in the above example that you decided you wouldn't update to Webpack 3 for a long time and don't want to build/test every time a new 3.x version arrives. In that case, simply close the "Update Webpack to version 3.x" PR and it _won't_ be recreated again even if subsequent Webpack 3.x versions are released. You can continue with Webpack 2.x for as long as you want and receive any updates/patches that are made for it. Then eventually when you do want to update to Webpack 3.x you can make that update to `package.json` yourself and commit it to master once it's tested. After that, Renovate will resume providing you updates to 3.x again! i.e. if you close a major upgrade PR then it won't come back again, but once you make the major upgrade yourself then Renovate will resume providing you with minor or patch updates.
 
 ## separateMinorPatch
 
-By default, Renovate won't distinguish between "patch" (e.g. 1.0.x) and "minor" (e.g. 1.x.0) releases - it groups them together. E.g., if you are running version 1.0.0 of a package and both versions 1.0.1 and 1.1.0 are available then Renovate will raise a single PR for version 1.1.0. If you wish to distinguish between patch and minor upgrades, for example if you wish to automerge patch but not minor, then you can set this option to `true`.
+By default, Renovate won't distinguish between "patch" (e.g. 1.0.x) and "minor" (e.g. 1.x.0) releases - it groups them together. E.g., if you are running version 1.0.0 of a package and both versions 1.0.1 and 1.1.0 are available then Renovate will raise a single PR for version 1.1.0. If you wish to distinguish between patch and minor upgrades, for example if you wish to automerge patch but not minor, then you can configured this option to `true`.
 
 ## separateMultipleMajor
 
-Set this to true if you wish to receive one PR for every separate major version upgrade of a dependency. e.g. if you are on webpack@v1 currently then default behaviour is a PR for upgrading to webpack@v3 and not for webpack@v2. If this setting is true then you would get one PR for webpack@v2 and one for webpack@v3.
+Configure this to `true` if you wish to receive one PR for every separate major version upgrade of a dependency. e.g. if you are on webpack@v1 currently then default behaviour is a PR for upgrading to webpack@v3 and not for webpack@v2. If this setting is true then you would get one PR for webpack@v2 and one for webpack@v3.
 
 ## stabilityDays
 
-If this is set to a non-zero value, and an update has a release date/timestamp available, then Renovate will check if the configured "stability days" have elapsed. If the days since the release is less than the configured stability days then a "pending" status check will be added to the branch. If enough days have passed then a passing status check will be added.
+If this is configured to a non-zero value, and an update has a release date/timestamp available, then Renovate will check if the configured "stability days" have elapsed. If the days since the release is less than the configured stability days then a "pending" status check will be added to the branch. If enough days have passed then a passing status check will be added.
 
 There are a couple of uses for this:
 
@@ -1341,7 +1448,7 @@ The following _range_ constraints are also supported:
 
 ## timezone
 
-It is only recommended to set this field if you wish to use the `schedules` feature and want to write them in your local timezone. Please see the above link for valid timezone names.
+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. Please see the above link for valid timezone names.
 
 ## travis
 
@@ -1363,9 +1470,9 @@ Enabling `unpublishSafe` will add a `renovate/unpublish-safe` status check with
 
 ## updateNotScheduled
 
-When schedules are in use, it generally means "no updates". However there are cases where updates might be desirable - e.g. if you have set prCreation=not-pending, or you have rebaseStale=true and master branch is updated so you want Renovate PRs to be rebased.
+When schedules are in use, it generally means "no updates". However there are cases where updates might be desirable - e.g. if you have configured prCreation=not-pending, or you have rebaseStale=true and master branch is updated so you want Renovate PRs to be rebased.
 
-This defaults to true, meaning that Renovate will perform certain "desirable" updates to _existing_ PRs even when outside of schedule. If you wish to disable all updates outside of scheduled hours then set this field to false.
+This defaults to `true`, meaning that Renovate will perform certain "desirable" updates to _existing_ PRs even when outside of schedule. If you wish to disable all updates outside of scheduled hours then configure this field to `false`.
 
 ## versionScheme
 
@@ -1384,12 +1491,12 @@ For the `regex` `versionScheme`, will accept a regex string after a colon, for e
 The valid capture groups for the `regex` `versionScheme` are:
 
 - `major`, `minor`, and `patch`: at least one of these must be provided. When determining whether a package has updated, these values will be compared in the standard semantic versioning fashion. If any of these fields are omitted, they will be treated as if they were `0` -- in this way, you can describe versioning schemes with up to three incrementing values.
-- `prerelease`: this value, if captured, will mark a given release as a prerelease (eg. unstable). If this value is captured and you have set `"ignoreUnstable": true`, the given release will be skipped.
+- `prerelease`: this value, if captured, will mark a given release as a prerelease (eg. unstable). If this value is captured and you have configured `"ignoreUnstable": true`, the given release will be skipped.
 - `compatibility`: this value defines the "build compatibility" of a given dependency. A proposed Renovate update will never change the specified compatibility value. For example, if you are pinning to `1.2.3-linux` (and `linux` is captured as the compatbility value), Renovate will not update you to `1.2.4-osx`.
 
 ## vulnerabilityAlerts
 
-Use this object to customise PRs that are raised when vulnerability alerts are detected (GitHub-only). For example, to set custom labels and assignees:
+Use this object to customise PRs that are raised when vulnerability alerts are detected (GitHub-only). For example, to configure custom labels and assignees:
 
 ```json
 {
@@ -1400,7 +1507,7 @@ Use this object to customise PRs that are raised when vulnerability alerts are d
 }
 ```
 
-To disable vulnerability alerts completely, set like this:
+To disable vulnerability alerts completely, configure like this:
 
 ```json
 {
diff --git a/docs/usage/docker.md b/docs/usage/docker.md
index 201edddbeb..b669c037a1 100644
--- a/docs/usage/docker.md
+++ b/docs/usage/docker.md
@@ -11,17 +11,57 @@ Renovate supports upgrading dependencies in various types of Docker definition f
 - Docker Compose files
 - CircleCI config files
 - Kubernetes manifests
-- Ansible configuration iles
+- Ansible configuration files
 
 ## How It Works
 
 1.  Renovate will search each repository for any files matching each manager's configured `fileMatch` pattern(s)
-2.  Files are downloaded and then checked to see if they contain any Docker image references (e.g. `FROM` lines in `Dockerfile`s)
-3.  If the image tag in use "looks" like a semver (e.g. `node:8`, `node:8.9`, `node:8.9.0`, `node:8-onbuild`) then Renovate will look up the Docker registry to determine if any upgrades are available (e.g. `node:8.9.1`).
+2.  Files that match the pattern(s) are parsed and checked to see if they contain any Docker image references (e.g. `FROM` lines in a `Dockerfile`)
+3.  If the image tag in use "looks" like a semver (e.g. `node:12`, `node:12.1`, `node:12.1.0`, `node:12-onbuild`) then Renovate will look up the Docker registry to determine if any upgrades are available (e.g. `node:12.2.0`).
+
+## Preservation of Version Precision
+
+Renovate by default will preserve the precision of Docker images. For example if the existing image is `node:12.1` then Renovate would only propose upgrades to `node:12.2` or `node:12.3` and not to more specified versions like `node:12.2.0` or `node:12.3.0`. Renovate does not yet support "pinning" an imprecise version to a precise version, e.g. from `node:12.2` to `node:12.2.0`, however it's a feature we'd like to implement one day.
+
+## Version compatibility
+
+Although suffixes in semver indicate pre-releases (e.g. `v1.2.0-alpha.2`), in Docker they typically indicate compatibility, e.g. `12.2.0-alpine`. Renovate defaults to assuming suffixes indicate compatibility so will never _change_ it. e.g. `12.1.0-alpine` might get updated to `12.1.1-alpine` but never `12.1.1` or `12.1.1-stretch`.
+
+If this behaviour does not suit a particular package you have, Renovate allows you to customize the `versionScheme` in use. For example, if you have a Docker image `foo/bar` that sticks to semver versioning and you need Renovate to understand that suffixes indicate pre-releases versions and not compatibility, then you could configure this pacckage rule:
+
+```json
+{
+  "packageRules": [
+    {
+      "datasources": ["docker"],
+      "packageNames": ["foo/bar"],
+      "versionScheme": "semver"
+    }
+  ]
+}
+```
+
+Another example is the official `python` image, which follows `pep440` versioning. You can configure that with another package rule:
+
+```json
+{
+  "packageRules": [
+    {
+      "datasources": ["docker"],
+      "packageNames": ["python"],
+      "versionScheme": "pep440"
+    }
+  ]
+}
+```
+
+If traditional versioning doesn't work, consider using Renovate's built-in `loose` `versionScheme`. It essentially just does a best effort sort of versions, regardless of whether they contain letters or digits.
+
+Finally, if you use a Docker image that follows a versioning approach not captured by one of our existing version schemes, and which `loose` sorts incorrectly, you could see if the `regex` `versionScheme` can work. It uses regex capture group syntax to let you specify which part of the version string is major, minor, patch, pre-release, or compatibility. See the docs for `versionScheme` for documentation/examples of `regex` versioning in action.
 
 ## Digest Pinning
 
-Pinning your docker images to an exact digest is recommended for reasons of **immutability**. In short: so every time you `pull`, you get the same content.
+Pinning your docker images to an exact digest is recommended for reasons of **immutability**. In short: pin to digests so every time you `pull`, you get the same content.
 
 If your experience with dependency versioning comes from a place like javascript/npm, you might be used to exact versions being immutable, e.g. if you specify a version like `2.0.1` then you and your colleagues will always get the exact same "code". What you may not expect is that Docker's tags are not immutable versions even if they look like a version. e.g. you probably expect that `node:8` and `node:8.9` will change over time, but you might incorrectly assume that `node:8.9.0` would never change. Although it probably _shouldn't_, the reality is that any Docker image tag _can_ change content, and potentially break.
 
@@ -47,12 +87,11 @@ Currently, Renovate will upgrade minor/patch versions (e.g. from `8.9.0` to `8.9
 
 Renovate has a some docker-specific intelligence when it comes to versions. For example:
 
-- It understands that tag suffixes are frequently used, such as `node:8.9-onbuild`. Renovate will only upgrade from/to the same suffix.
-- It understands that some dependencies (e.g. `node` and `ubuntu`) use even numbers for stable and odd for unstable. Renovate won't upgrade from stable to unstable
-
 ## Configuring/Disabling
 
-If you wish to make changes that apply to all Docker managers, then add them to the `docker` config object. If you wish to override Docker settings for one particular type of manager, use that manager's config object instead. For example. to disable digest updates for Docker Compose only but leave them for other managers like `Dockerfile`, you would add this:
+If you wish to make changes that apply to all Docker managers, then add them to the `docker` config object. Note though that this is not foolproof, because some managers like `circleci` and `ansible` support multiple datasources so do not inherit from the `docker` config object.
+
+If you wish to override Docker settings for one particular type of manager, use that manager's config object instead. For example. to disable digest updates for Docker Compose only but leave them for other managers like `Dockerfile`, you would add this:
 
 ```json
   "docker-compose": {
@@ -107,21 +146,11 @@ module.exports = {
 };
 ```
 
-Alternatively, configure `DOCKER_USERNAME` and `DOCKER_PASSWORD` in env to achieve the same.
-
-The above two approaches create an identical host rule in renovatebot. It is possible to add additional host rules following the [documentation](https://docs.renovatebot.com/configuration-options/#hostrules)
-
-For example if you have some images you host yourself and some images you pull from docker hub without logging in you can configure that like this:
+It is possible to add additional host rules following the [documentation](https://docs.renovatebot.com/configuration-options/#hostrules). For example if you have some images you host yourself that are password protected and also some images you pull from docker hub without authentication then you can configure for a specific Docker host like this:
 
 ```js
 module.exports = {
   hostRules: [
-    {
-      hostType: 'docker',
-      hostName: 'index.docker.io',
-      username: '',
-      password: '',
-    },
     {
       hostType: 'docker',
       hostName: 'your.host.io',
@@ -131,3 +160,5 @@ module.exports = {
   ],
 };
 ```
+
+If you need to configure per-repository credentials then you can also configure the above within a repository's Renovate config (e.g. `renovate.json`);
diff --git a/lib/config/definitions.ts b/lib/config/definitions.ts
index 10f1eebb09..7404a9b50b 100644
--- a/lib/config/definitions.ts
+++ b/lib/config/definitions.ts
@@ -1337,7 +1337,7 @@ const options: RenovateOptions[] = [
   },
   {
     name: 'fileMatch',
-    description: 'JS RegExp pattern for matching manager files',
+    description: 'RegEx (re2) pattern for matching manager files',
     type: 'array',
     subType: 'string',
     format: 'regex',
diff --git a/renovate-schema.json b/renovate-schema.json
index 0d7a9ad510..e8061ee557 100644
--- a/renovate-schema.json
+++ b/renovate-schema.json
@@ -856,7 +856,7 @@
       "default": null
     },
     "fileMatch": {
-      "description": "JS RegExp pattern for matching manager files",
+      "description": "RegEx (re2) pattern for matching manager files",
       "type": "array",
       "items": {
         "type": "string",
-- 
GitLab