From 32dd49067236b17c663a290f89be575d4e6a01a4 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 2 Nov 2020 09:52:37 +0100 Subject: [PATCH] docs: use one sentence per line (#7625) --- .github/contributing.md | 22 +- SECURITY.md | 3 +- docs/development/adding-a-package-manager.md | 9 +- docs/development/branches-commits.md | 6 +- docs/development/configuration.md | 17 +- docs/development/design-decisions.md | 60 +-- docs/development/local-development.md | 49 +- docs/development/readme.md | 3 +- docs/development/shareable-configs.md | 59 +-- docs/usage/config-presets.md | 69 ++- docs/usage/configuration-options.md | 457 +++++++++++++------ docs/usage/configuration-templates.md | 39 +- docs/usage/configure-renovate.md | 10 +- docs/usage/dependency-pinning.md | 130 ++++-- docs/usage/docker.md | 63 ++- docs/usage/faq.md | 73 ++- docs/usage/golang.md | 12 +- docs/usage/install-github-app.md | 3 +- docs/usage/install-gitlab-app.md | 18 +- docs/usage/java.md | 6 +- docs/usage/modules/datasource.md | 3 +- docs/usage/modules/manager.md | 14 +- docs/usage/modules/versioning.md | 6 +- docs/usage/noise-reduction.md | 77 +++- docs/usage/nuget.md | 11 +- docs/usage/php.md | 6 +- docs/usage/private-modules.md | 25 +- docs/usage/python.md | 32 +- docs/usage/reconfigure-renovate.md | 13 +- docs/usage/ruby.md | 6 +- docs/usage/self-hosted-configuration.md | 76 ++- docs/usage/self-hosting.md | 39 +- docs/usage/semantic-commits.md | 10 +- docs/usage/setup-azure-devops.md | 3 +- docs/usage/templates.md | 6 +- docs/usage/updating-rebasing.md | 21 +- readme.md | 22 +- 37 files changed, 971 insertions(+), 507 deletions(-) diff --git a/.github/contributing.md b/.github/contributing.md index 1e283e6ed..220f14d5b 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -2,7 +2,8 @@ ## Security -If you think you've found a **security issue**, please do not mention it in this repository. Instead, email security@renovatebot.com with as much details as possible so that it can be handled confidentially. +If you think you've found a **security issue**, please do not mention it in this repository. +Instead, email security@renovatebot.com with as much details as possible so that it can be handled confidentially. ## Support @@ -14,12 +15,12 @@ If you've found a **bug** or have a **feature request** then please create an is ## Code -If you would like to fix a bug or implement a feature, please fork the repository and create a Pull Request. More information on getting set up locally can be found in [docs/development/local-development.md](https://github.com/renovatebot/renovate/blob/master/docs/development/local-development.md). +If you would like to fix a bug or implement a feature, please fork the repository and create a Pull Request. +More information on getting set up locally can be found in [docs/development/local-development.md](https://github.com/renovatebot/renovate/blob/master/docs/development/local-development.md). -Before you start any Pull Request, it's recommended that you create an issue to discuss -first if you have any doubts about requirement or implementation. That way you can be sure that the maintainer(s) -agree on what to change and how, and you can hopefully get a quick merge -afterwards. Also, let the maintainers know that you plan to work on a particular issue so that no one else starts any duplicate work. +Before you start any Pull Request, it's recommended that you create an issue to discuss first if you have any doubts about requirement or implementation. +That way you can be sure that the maintainer(s) agree on what to change and how, and you can hopefully get a quick merge afterwards. +Also, let the maintainers know that you plan to work on a particular issue so that no one else starts any duplicate work. Pull Requests can only be merged once all status checks are green, which means `yarn test` passes, and coverage is 100%. @@ -31,12 +32,15 @@ Commit as many times as you need in your pull request branch. ## Slack collaboration with maintainers -Sometimes the codebase can be a challenge to navigate, especially for a first-time contributor. We don't want you spending an hour trying to work out something that would take us only a minute to explain. +Sometimes the codebase can be a challenge to navigate, especially for a first-time contributor. +We don't want you spending an hour trying to work out something that would take us only a minute to explain. -For that reason, we have a Slack channel dedicated to helping anyone who's working on Pull Requests for Renovate. Please email rhys@renovatebot.com and simply mention that you need an invitation to the channel. +For that reason, we have a Slack channel dedicated to helping anyone who's working on Pull Requests for Renovate. +Please email rhys@renovatebot.com and simply mention that you need an invitation to the channel. ## Legal Pull Request authors must sign the [Renovate CLA](https://cla-assistant.io/renovateapp/renovate). -If you cannot or do not want to sign this CLA (e.g. your employment contract for your employer may not allow this), you should not submit a PR. Open an issue and someone else can do the work. +If you cannot or do not want to sign this CLA (e.g. your employment contract for your employer may not allow this), you should not submit a PR. +Open an issue and someone else can do the work. diff --git a/SECURITY.md b/SECURITY.md index a66193213..b3e5f84f1 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,3 +1,4 @@ # Security Policy -Please send an email to [renovate-disclosure@whitesourcesoftware.com](mailto:renovate-disclosure@whitesourcesoftware.com) describing what you have found. Please do not raise an issue in this repository or publicize your concern in any other forum without giving us adequate time to investigate first. +Please send an email to [renovate-disclosure@whitesourcesoftware.com](mailto:renovate-disclosure@whitesourcesoftware.com) describing what you have found. +Please do not raise an issue in this repository or publicize your concern in any other forum without giving us adequate time to investigate first. diff --git a/docs/development/adding-a-package-manager.md b/docs/development/adding-a-package-manager.md index 791eaac1b..6cf0b1284 100644 --- a/docs/development/adding-a-package-manager.md +++ b/docs/development/adding-a-package-manager.md @@ -22,7 +22,8 @@ The manager's `index.ts` file supports the following values/functions: ##### `extractPackageFile(content, packageFile, config)` (async, semi-mandatory) -This function is mandatory unless you use `extractAllPackageFiles` instead. It takes as arguments the file's content and optionally the file's full file pathname and config, and returns an array of detected/extracted dependencies, including: +This function is mandatory unless you use `extractAllPackageFiles` instead. +It takes as arguments the file's content and optionally the file's full file pathname and config, and returns an array of detected/extracted dependencies, including: - dependency name - dependency type (e.g. dependencies, devDependencies, etc) @@ -31,7 +32,8 @@ This function is mandatory unless you use `extractAllPackageFiles` instead. It t This function doesn't necessarily need to _understand_ the file or even syntax that it is passed, instead it just needs to understand enough to extract an accurate list of dependencies. -As a general approach, we want to extract _all_ dependencies from each dependency file, even if they contain values we don't support. For any that have unsupported values that we cannot renovate, this `extractPackageFile` function should set a `skipReason` to a value that would be helpful to someone reading the logs. +As a general approach, we want to extract _all_ dependencies from each dependency file, even if they contain values we don't support. +For any that have unsupported values that we cannot renovate, this `extractPackageFile` function should set a `skipReason` to a value that would be helpful to someone reading the logs. Also, if a file is passed to `extractPackageFile` which is a "false match" (e.g. not an actual package file, or contains no dependencies) then this function can return `null` to have it ignored and removed from the list of package files. @@ -47,7 +49,8 @@ This function takes an array of filenames as input and returns an array of filen #### `getRangeStrategy(config)` (optional) -This optional function should be written if you wish the manager to support "auto" range strategies, e.g. pinning or not pinning depending on other values in the package file. `npm` uses this to pin `devDependencies` but not `dependencies` unless the package file is detected as an app. +This optional function should be written if you wish the manager to support "auto" range strategies, e.g. pinning or not pinning depending on other values in the package file. +`npm` uses this to pin `devDependencies` but not `dependencies` unless the package file is detected as an app. If left undefined, then a default `getRangeStrategy` will be used that always returns "replace". diff --git a/docs/development/branches-commits.md b/docs/development/branches-commits.md index 88b1278a4..8e0d8301f 100644 --- a/docs/development/branches-commits.md +++ b/docs/development/branches-commits.md @@ -2,7 +2,8 @@ ## Multiple files per branch -Renovate can/should update multiple files in the same branch/PR. e.g. it might be `package.json` and `yarn.lock`, or it might be multiple `package.json` files in a monorepo. +Renovate can/should update multiple files in the same branch/PR. +e.g. it might be `package.json` and `yarn.lock`, or it might be multiple `package.json` files in a monorepo. ## One commit per branch @@ -12,4 +13,5 @@ A positive side effect of this is that it allows us to have a shortcut rule of, ## Updating branches -If files in an already-existing branch need updating (e.g. an even newer version has been released), then we still aim to have just one commit. We achieve this by force pushing with `git` to the existing branch. +If files in an already-existing branch need updating (e.g. an even newer version has been released), then we still aim to have just one commit. +We achieve this by force pushing with `git` to the existing branch. diff --git a/docs/development/configuration.md b/docs/development/configuration.md index ce6819f5b..6d65b277a 100644 --- a/docs/development/configuration.md +++ b/docs/development/configuration.md @@ -27,14 +27,11 @@ Default configuration values can be found in ### Configuration File -You can override default configuration using a configuration file, with default -name `config.js` in the working directory. If you need an alternate location or -name, set it in the environment variable `RENOVATE_CONFIG_FILE`. +You can override default configuration using a configuration file, with default name `config.js` in the working directory. +If you need an alternate location or name, set it in the environment variable `RENOVATE_CONFIG_FILE`. -Using a configuration file gives you very granular configuration options. For -instance, you can override most settings at the global (file), repository, or -package level. e.g. apply one set of labels for `backend/package.json` and a -different set for `frontend/package.json` in the same repository. +Using a configuration file gives you very granular configuration options. +For instance, you can override most settings at the global (file), repository, or package level. e.g. apply one set of labels for `backend/package.json` and a different set for `frontend/package.json` in the same repository. ```javascript module.exports = { @@ -52,7 +49,8 @@ module.exports = { $ node renovate --help ``` -To configure any `` items, separate with commas. E.g. `renovate --labels=renovate,dependency`. +To configure any `` items, separate with commas. +E.g. `renovate --labels=renovate,dependency`. ### renovate.json @@ -60,8 +58,7 @@ If you add a `renovate.json` file to the root of your repository, you can use th ### package.json -If you add configuration options to your `package.json` then these will override -any other settings above. +If you add configuration options to your `package.json` then these will override any other settings above. ```json "renovate": { diff --git a/docs/development/design-decisions.md b/docs/development/design-decisions.md index 14345830a..7c0f55dbd 100644 --- a/docs/development/design-decisions.md +++ b/docs/development/design-decisions.md @@ -4,11 +4,8 @@ This file documents the design choices as well as configuration options. ## Stateless -No state storage is needed on `renovate` or the source code repository apart -from what you see publicly (branches, Pull Requests). It, therefore, doesn't -matter if you stop/restart the script and would even still work if you had it -running from two different locations, as long as their configuration was the -same. +No state storage is needed on `renovate` or the source code repository apart from what you see publicly (branches, Pull Requests). +It, therefore, doesn't matter if you stop/restart the script and would even still work if you had it running from two different locations, as long as their configuration was the same. ## Synchronous Operation @@ -19,33 +16,27 @@ The script current processes repositories and branches within them all synchrono ## Cascading Configuration -Configuration options applied per-package (e.g. with package rules) override those applied per -package-type, which override those per-repository, which override those which -are global (all repositories). +Configuration options applied per-package (e.g. with package rules) override those applied per package-type, which override those per-repository, which override those which are global (all repositories). ## Automatic discovery of package file locations -The default behaviour is to auto-discover all package file (e.g. `package.json`) locations in a repository and process them all. Doing so means that "monorepos" are supported by default. This can be overridden by the configuration option `includePaths`, where you list the file paths manually (e.g. limit to just `package.json` in the root of the repository). +The default behaviour is to auto-discover all package file (e.g. `package.json`) locations in a repository and process them all. +Doing so means that "monorepos" are supported by default. +This can be overridden by the configuration option `includePaths`, where you list the file paths manually (e.g. limit to just `package.json` in the root of the repository). ## Separate Branches per dependency -By default, `renovate` will maintain separate branches per-dependency. So if 20 -dependencies need updating, there will be at least 20 branches/PRs. Although -this may seem undesirable, it was considered even less desirable if all 20 were -in the same Pull Request and it's up to the users to determine which dependency -upgrade(s) caused the build to fail. +By default, `renovate` will maintain separate branches per-dependency. +So if 20 dependencies need updating, there will be at least 20 branches/PRs. +Although this may seem undesirable, it was considered even less desirable if all 20 were in the same Pull Request and it's up to the users to determine which dependency upgrade(s) caused the build to fail. -However, it's still possible to override the default branch and PR name -templates in such a way to produce a single branch for all dependencies. The -`groupName` configuration option can be used at a repository level (e.g. give it -the value `All`) and then all dependency updates will be in the same branch/PR. +However, it's still possible to override the default branch and PR name templates in such a way to produce a single branch for all dependencies. +The `groupName` configuration option can be used at a repository level (e.g. give it the value `All`) and then all dependency updates will be in the same branch/PR. ## Separate Minor and Major PRs -`renovate` will create multiple branches/PRs if both major and minor branch upgrades -are available. For example, if the current example is 1.6.0 and upgrades to 1.7.0 -and 2.0.0 exist, then `renovate` will raise PRs for both the 1.x upgrade(s) and -2.x upgrade(s). +`renovate` will create multiple branches/PRs if both major and minor branch upgrades are available. +For example, if the current example is 1.6.0 and upgrades to 1.7.0 and 2.0.0 exist, then `renovate` will raise PRs for both the 1.x upgrade(s) and 2.x upgrade(s). - It's often the case that projects can't upgrade major dependency versions immediately. - It's also often the case that previous major versions continue receiving Minor or Patch updates. @@ -64,29 +55,24 @@ Note: Branch names are configurable using string templates. ## Pull Request Recreation -By default, the script does not create a new PR if it finds an identical one -already closed. This allows users to close unwelcome upgrade PRs and not worry about -them being recreated every run. Typically this is most useful for major -upgrades. This option is configurable. +By default, the script does not create a new PR if it finds an identical one already closed. +This allows users to close unwelcome upgrade PRs and not worry about them being recreated every run. +Typically this is most useful for major upgrades. +This option is configurable. ## Rebasing Unmergeable Pull Requests -With the default behaviour of one branch per dependency, it's often that case -that a PR gets merge conflicts after an adjacent dependency update is merged. -Although platforms often have a web interface for simple merge conflicts, this is -still annoying to resolve manually. +With the default behaviour of one branch per dependency, it's often that case that a PR gets merge conflicts after an adjacent dependency update is merged. +Although platforms often have a web interface for simple merge conflicts, this is still annoying to resolve manually. -`renovate` will rebase any unmergeable branches and add the latest necessary -commit on top of the most recent `master` commit. +`renovate` will rebase any unmergeable branches and add the latest necessary commit on top of the most recent `master` commit. -Note: `renovate` will only do this if the original branch hasn't been modified -by anyone else. +Note: `renovate` will only do this if the original branch hasn't been modified by anyone else. ## Suppressing string templates from CLI -String templates (e.g. commit or PR name) are not configurable via CLI options, -in order to not pollute the CLI help and make it unreadable. If you must -configure via CLI, use an environment variable instead. e.g. +String templates (e.g. commit or PR name) are not configurable via CLI options, in order to not pollute the CLI help and make it unreadable. +If you must configure via CLI, use an environment variable instead. e.g. ```sh $ RENOVATE_BRANCH_NAME=foo renovate diff --git a/docs/development/local-development.md b/docs/development/local-development.md index 7b3a47d46..852d41b4b 100644 --- a/docs/development/local-development.md +++ b/docs/development/local-development.md @@ -37,7 +37,8 @@ You can also use [SDKMAN](https://sdkman.io/) to manage Java versions. _Windows_ -The following steps work to set up a brand new Windows 10 installation for developing Renovate. If you already have some components installed, you can naturally skip them. +The following steps work to set up a brand new Windows 10 installation for developing Renovate. +If you already have some components installed, you can naturally skip them. - Install [Git](https://git-scm.com/downloads). Make sure you've [configured your username and email](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup). - Install [Node.js LTS](https://nodejs.org/en/download/) @@ -84,15 +85,19 @@ We use [Yarn](https://github.com/yarnpkg/yarn) so run `yarn install` to install #### Build Renovate -Run `yarn build`. You should get no errors. +Run `yarn build`. +You should get no errors. #### Verify tests -Run `yarn test`. You should see it pass with 100% test coverage. Make sure you've run `yarn build` first. +Run `yarn test`. +You should see it pass with 100% test coverage. +Make sure you've run `yarn build` first. #### Verify installation -Run `yarn start`. You should see this error: +Run `yarn start`. +You should see this error: ``` Fatal error: No authentication found for platform https://api.github.com/ (github) @@ -100,7 +105,8 @@ Fatal error: No authentication found for platform https://api.github.com/ (githu ## Platform Account Setup -Although it's possible to make small source code improvements without testing against a real repository, in most cases it's important that you run a "real" test on a repository before you submit a feature or fix. It's possible to do this against GitHub, GitLab or Bitbucket public servers. +Although it's possible to make small source code improvements without testing against a real repository, in most cases it's important that you run a "real" test on a repository before you submit a feature or fix. +It's possible to do this against GitHub, GitLab or Bitbucket public servers. #### Register new account (optional) @@ -110,7 +116,8 @@ e.g. if your GitHub username is "alex88" then maybe you register "alex88-testing #### Generate platform token -Once you have decided on your platform and account, log in and [generate a "Personal Access Token"](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) that can be used to authenticate Renovate. Select **repo** scope when generating the token. +Once you have decided on your platform and account, log in and [generate a "Personal Access Token"](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) that can be used to authenticate Renovate. +Select **repo** scope when generating the token. #### Export platform token @@ -119,21 +126,29 @@ You are better off to instead export the Environment Variable `RENOVATE_TOKEN` f #### Run against a real repo -To make sure everything is working, create a test repo in your account, e.g. like `https://github.com/r4harry/testrepo1`. Now, add a file called `.nvmrc` with the content `8.13.0`. Now run against the test repo you created, e.g. `yarn start r4harry/testrepo1`. If your token is set up correctly, you should find that it added a "Configure Renovate" PR inside the repo. +To make sure everything is working, create a test repo in your account, e.g. like `https://github.com/r4harry/testrepo1`. +Now, add a file called `.nvmrc` with the content `8.13.0`. +Now run against the test repo you created, e.g. `yarn start r4harry/testrepo1`. +If your token is set up correctly, you should find that it added a "Configure Renovate" PR inside the repo. If this is working then in future you can create other test repos to verify your code changes against. ## Tests -You can run `yarn test` locally to test your code. We test all PRs using the same tests, run on CircleCI and Azure Pipelines. `yarn test` runs an `eslint` check, a `prettier` check, a `type` check and then all the unit tests using `jest`. +You can run `yarn test` locally to test your code. +We test all PRs using the same tests, run on CircleCI and Azure Pipelines. `yarn test` runs an `eslint` check, a `prettier` check, a `type` check and then all the unit tests using `jest`. ## Jest -You can run just the Jest unit tests by running `yarn jest`. You can also run just a subset of the Jest tests using file matching, e.g. `yarn jest composer` or `yarn jest workers/branch`. If you get a test failure due to a "snapshot" mismatch, and you are sure that you need to update the snapshot, then you can append `-u` to the end. e.g. `yarn jest composer -u` would update the saved snapshots for _all_ tests in `test/manager/composer/*`. +You can run just the Jest unit tests by running `yarn jest`. +You can also run just a subset of the Jest tests using file matching, e.g. `yarn jest composer` or `yarn jest workers/branch`. +If you get a test failure due to a "snapshot" mismatch, and you are sure that you need to update the snapshot, then you can append `-u` to the end. +e.g. `yarn jest composer -u` would update the saved snapshots for _all_ tests in `test/manager/composer/*`. #### Prerequisites -You need to have Python with `mock` installed for all tests to pass. Python 3 includes `mock` so that approach is recommended. +You need to have Python with `mock` installed for all tests to pass. +Python 3 includes `mock` so that approach is recommended. You also need to make sure that you don't have a local `.npmrc` file that overrides npm's default registry. @@ -144,12 +159,15 @@ Using `// istanbul ignore` is not ideal but sometimes is a pragmatic solution if To view the current test coverage locally, open up `coverage/index.html` in your browser. -Do not let coverage put you off submitting a PR! Maybe we can help, or at least guide. +Do not let coverage put you off submitting a PR! +Maybe we can help, or at least guide. Also, it can be good to submit your PR as a work in progress (WIP) without tests first so that you can get a thumbs up from others about the changes, and write tests after. #### Linting and formatting -We use [Prettier](https://github.com/prettier/prettier) for code formatting. If your code fails `yarn test` due to a `prettier` rule then run `yarn lint-fix` to fix it or most `eslint` errors automatically before running `yarn test` again. You usually shouldn't need to fix any Prettier errors manually. +We use [Prettier](https://github.com/prettier/prettier) for code formatting. +If your code fails `yarn test` due to a `prettier` rule then run `yarn lint-fix` to fix it or most `eslint` errors automatically before running `yarn test` again. +You usually shouldn't need to fix any Prettier errors manually. ## Keeping your Renovate fork up to date @@ -186,15 +204,14 @@ The above will delete any existing `debug.log` and then save Renovate's output t #### Adding configuration options -We wish to keep backwards-compatibility as often as possible, as well as make -the code configurable, so most new functionality should be controllable via -configuration options. +We wish to keep backwards-compatibility as often as possible, as well as make the code configurable, so most new functionality should be controllable via configuration options. If you wish to add one, add it to `lib/config/definitions.ts` and then add documentation to `website/docs/configuration-options.md`. ## Debugging -It's really easy to debug Renovate using Chrome's inspect tool. Try like this: +It's really easy to debug Renovate using Chrome's inspect tool. +Try like this: 1. Open `chrome://inspect` in Chrome, then click on "Open dedicated DevTools for Node" 2. Add a `debugger;` statement somewhere in the source code where you want to start debugging diff --git a/docs/development/readme.md b/docs/development/readme.md index cef6c918b..d9c8a3ff5 100644 --- a/docs/development/readme.md +++ b/docs/development/readme.md @@ -1,5 +1,6 @@ # Renovate Developer Docs -This directory is intended to provide documentation for developers/contributors on the Renovate project. For user-facing documentation - e.g. for how to configure Renovate as a user - please see https://docs.renovatebot.com +This directory is intended to provide documentation for developers/contributors on the Renovate project. +For user-facing documentation - e.g. for how to configure Renovate as a user - please see https://docs.renovatebot.com If you would like to contribute to Renovate or get it running locally for some other reason, please check out [contributing.md](../../.github/contributing.md) for steps on how to set up the project locally. diff --git a/docs/development/shareable-configs.md b/docs/development/shareable-configs.md index 3bebcb860..7bf54aa41 100644 --- a/docs/development/shareable-configs.md +++ b/docs/development/shareable-configs.md @@ -1,30 +1,20 @@ # Preset configs -Renovate uses the term "presets" to refer to shareable config snippets, similar -to ESLint. Unlike ESLint though: +Renovate uses the term "presets" to refer to shareable config snippets, similar to ESLint. +Unlike ESLint though: -- Presets may be as small as a list of package names, or as large as a full - config +- Presets may be as small as a list of package names, or as large as a full config - Shared config files can contain many presets ## Preset config URIs In human-understandable form, the rules are: -- A full preset URI consists of package name, preset name, and preset - parameters, such as `package:preset(param)` -- If a package scope is specified and no package, then the package name is - assumed to be `renovate-config`, e.g. `@rarkins:webapp` is expanded to - `@rarkins/renovate-config:webapp` -- If a non-scoped package is specified then it is assumed to have prefix - `renovate-config-`. e.g. `rarkins:webapp` is expanded to - `renovate-config-rarkins:webapp` -- If a package name is specified and no preset name, then `default` is assumed, - e.g. `@rarkins` expands in full to `@rarkins/renovate-config:default` and - `rarkins` expands in full to `renovate-config-rarkins:default` -- There is a special "default" namespace where no package name is necessary. - e.g. `:webapp` (not the leading `:`) expands to - `renovate-config-default:webapp` +- A full preset URI consists of package name, preset name, and preset parameters, such as `package:preset(param)` +- If a package scope is specified and no package, then the package name is assumed to be `renovate-config`, e.g. `@rarkins:webapp` is expanded to `@rarkins/renovate-config:webapp` +- If a non-scoped package is specified then it is assumed to have prefix `renovate-config-`. e.g. `rarkins:webapp` is expanded to `renovate-config-rarkins:webapp` +- If a package name is specified and no preset name, then `default` is assumed, e.g. `@rarkins` expands in full to `@rarkins/renovate-config:default` and `rarkins` expands in full to `renovate-config-rarkins:default` +- There is a special "default" namespace where no package name is necessary. e.g. `:webapp` (not the leading `:`) expands to `renovate-config-default:webapp` ## Supported config syntax @@ -34,8 +24,7 @@ In human-understandable form, the rules are: @somescope ``` -This will resolve to use the preset `default` in the npm package -`@somescope/renovate-config`. +This will resolve to use the preset `default` in the npm package `@somescope/renovate-config`. ### Scoped with package name @@ -43,8 +32,7 @@ This will resolve to use the preset `default` in the npm package @somescope/somepackagename ``` -This will resolve to use the preset `default` in the npm package -`@somescope/somepackagename`. +This will resolve to use the preset `default` in the npm package `@somescope/somepackagename`. ### Scoped with preset name @@ -52,8 +40,7 @@ This will resolve to use the preset `default` in the npm package @somescope:webapp ``` -This will resolve to use the preset `webapp` in the npm package -`@somescope/renovate-config`. +This will resolve to use the preset `webapp` in the npm package `@somescope/renovate-config`. ### Scoped with params @@ -61,8 +48,7 @@ This will resolve to use the preset `webapp` in the npm package @somescope(eslint, stylelint) ``` -This will resolve to use the preset `default` in the npm package -`@somescope/renovate-config` and pass the parameters `eslint` and `stylelint`. +This will resolve to use the preset `default` in the npm package `@somescope/renovate-config` and pass the parameters `eslint` and `stylelint`. ### Scoped with preset name and params @@ -70,8 +56,7 @@ This will resolve to use the preset `default` in the npm package @somescope:webapp(eslint, stylelint) ``` -This will resolve to use the preset `webapp` in the npm package -`@somescope/renovate-config` and pass the parameters `eslint` and `stylelint`. +This will resolve to use the preset `webapp` in the npm package `@somescope/renovate-config` and pass the parameters `eslint` and `stylelint`. ### Scoped with package name and preset name @@ -79,8 +64,7 @@ This will resolve to use the preset `webapp` in the npm package @somescope/somepackagename:webapp ``` -This will resolve to use the preset `webapp` in the npm package -`@somescope/somepackagename`. +This will resolve to use the preset `webapp` in the npm package `@somescope/somepackagename`. ### Scoped with package name and preset name and params @@ -88,8 +72,7 @@ This will resolve to use the preset `webapp` in the npm package @somescope/somepackagename:webapp(eslint, stylelint) ``` -This will resolve to use the preset `webapp` in the npm package -`@somescope/somepackagename` and pass the parameters `eslint` and `stylelint`. +This will resolve to use the preset `webapp` in the npm package `@somescope/somepackagename` and pass the parameters `eslint` and `stylelint`. ### Non-scoped short with preset name @@ -99,8 +82,7 @@ Note: if using non-scoped packages, a preset name is mandatory. somepackagename:default ``` -This will resolve to use the preset `default` in the npm package -`renovate-config-somepackagename`. +This will resolve to use the preset `default` in the npm package `renovate-config-somepackagename`. ### Non-scoped short with preset name and params @@ -110,8 +92,7 @@ Note: if using non-scoped packages, a preset name is mandatory. somepackagename:default(eslint) ``` -This will resolve to use the preset `default` in the npm package -`renovate-config-somepackagename` with param `eslint`. +This will resolve to use the preset `default` in the npm package `renovate-config-somepackagename` with param `eslint`. ### Non-scoped full with preset name @@ -121,8 +102,7 @@ Note: if using non-scoped packages, a preset name is mandatory. renovate-config-somepackagename:default ``` -This will resolve to use the preset `default` in the npm package -`renovate-config-somepackagename`. +This will resolve to use the preset `default` in the npm package `renovate-config-somepackagename`. ### Non-scoped full with preset name and params @@ -132,5 +112,4 @@ Note: if using non-scoped packages, a preset name is mandatory. renovate-config-somepackagename:default(eslint) ``` -This will resolve to use the preset `default` in the npm package -`renovate-config-somepackagename` and param `eslint`. +This will resolve to use the preset `default` in the npm package `renovate-config-somepackagename` and param `eslint`. diff --git a/docs/usage/config-presets.md b/docs/usage/config-presets.md index 8178981d6..df1fda4be 100644 --- a/docs/usage/config-presets.md +++ b/docs/usage/config-presets.md @@ -5,7 +5,9 @@ description: Renovate's support for ESLint-like shareable configs # Shareable Config Presets -Renovate's "config presets" are a convenient way to distribute config that is reused across multiple repositories. It is similar in design to `eslint`'s shareable configs, and can be used both for whole repository configs as well as for individual rules. They are defined using the `extends` array within config and may also be nested. +Renovate's "config presets" are a convenient way to distribute config that is reused across multiple repositories. +It is similar in design to `eslint`'s shareable configs, and can be used both for whole repository configs as well as for individual rules. +They are defined using the `extends` array within config and may also be nested. In short: @@ -40,19 +42,24 @@ The following namespace is used: - `gitlab>abc/foo`: gitlab repository `https://gitlab.com/abc/foo` and preset `default` - `gitlab>abc/foo:xyz`: gitlab repository `https://gitlab.com/abc/foo` and preset `xyz` -In general, GitHub or GitLab-based preset hosting is easier than npm because you avoid the "publish" step - simply commit preset code to the default branch and it will be picked up by Renovate the next time it runs. An additional benefit of using source code hosting is that the same token/authentication can be reused by Renovate in case you want to make your config private. +In general, GitHub or GitLab-based preset hosting is easier than npm because you avoid the "publish" step - simply commit preset code to the default branch and it will be picked up by Renovate the next time it runs. +An additional benefit of using source code hosting is that the same token/authentication can be reused by Renovate in case you want to make your config private. ## Example configs -An example of a small rule is `:preserveSemverRanges`, which has the description "Preserve (but continue to upgrade) any existing semver ranges". It simply sets the configuration option `rangeStrategy` to `replace`. +An example of a small rule is `:preserveSemverRanges`, which has the description "Preserve (but continue to upgrade) any existing semver ranges". +It simply sets the configuration option `rangeStrategy` to `replace`. -An example of a full config is `config:base`, which is Renovate's default configuration. It mostly uses Renovate config defaults but adds a few smart customisations such as grouping monorepo packages together. +An example of a full config is `config:base`, which is Renovate's default configuration. +It mostly uses Renovate config defaults but adds a few smart customisations such as grouping monorepo packages together. -Special note: the `:xyz` naming convention (with `:` prefix) is a special shorthand for the `default:` presets. i.e. `:xyz` is equivalent to `default:xyz`. +Special note: the `:xyz` naming convention (with `:` prefix) is a special shorthand for the `default:` presets. +i.e. `:xyz` is equivalent to `default:xyz`. ## How to Use Preset Configs -By default, the Renovate App's onboarding process will suggest `["config:base]"`. If you are self hosting then you must add `"onboardingConfig": { "extends": ["config:base"] }` to your bot's config. +By default, the Renovate App's onboarding process will suggest `["config:base]"`. +If you are self hosting then you must add `"onboardingConfig": { "extends": ["config:base"] }` to your bot's config. A typical onboarding `renovate.json` will then look like this: @@ -62,7 +69,8 @@ A typical onboarding `renovate.json` will then look like this: } ``` -Let's say you wish to modify that default behaviour, such as to schedule Renovate to process upgrades only during non-office hours. In that case you could modify the default `renovate.json` to be like this: +Let's say you wish to modify that default behaviour, such as to schedule Renovate to process upgrades only during non-office hours. +In that case you could modify the default `renovate.json` to be like this: ```json { @@ -70,7 +78,8 @@ Let's say you wish to modify that default behaviour, such as to schedule Renovat } ``` -This makes use of the `schedules:` presets. To see all presets published by the Renovate team then browse the "Config Presets" section of [Renovate Docs](https://docs.renovatebot.com). +This makes use of the `schedules:` presets. +To see all presets published by the Renovate team then browse the "Config Presets" section of [Renovate Docs](https://docs.renovatebot.com). ## Preset Parameters @@ -101,17 +110,22 @@ Here is how you would use these in your Renovate config: ] ``` -In short, the number of `{{argx}}` params in the definition is how many parameters you need to provide. Parameters must be strings, non-quoted, and separated by commas if there are more than one. +In short, the number of `{{argx}}` params in the definition is how many parameters you need to provide. +Parameters must be strings, non-quoted, and separated by commas if there are more than one. If you find that you are repeating config a lot, you might consider publishing one of these types of parameterised presets yourself, or if you think your preset would be valuable for others, please contribute a PR to the Renovate repository. ## How to Publish Preset Configs -If you manage multiple repositories using Renovate and want the same custom config across all or most of them, then you might want to consider publishing your own preset config so that you can "extend" it in every applicable repository. That way when you want to change your Renovate configuration you can make the change in one location rather than having to copy/paste it to every repository individually. +If you manage multiple repositories using Renovate and want the same custom config across all or most of them, then you might want to consider publishing your own preset config so that you can "extend" it in every applicable repository. +That way when you want to change your Renovate configuration you can make the change in one location rather than having to copy/paste it to every repository individually. -Let's say that your username on npm and elsewhere is "fastcore". In that case, you can choose between publishing your preset config package as `@fastcore/renovate-config` or `renovate-config-fastcore`. Let's assume you choose `renovate-config-fastcore` as the package name: +Let's say that your username on npm and elsewhere is "fastcore". +In that case, you can choose between publishing your preset config package as `@fastcore/renovate-config` or `renovate-config-fastcore`. +Let's assume you choose `renovate-config-fastcore` as the package name: -You then need to publish the `renovate-config-fastcore` package where the `package.json` contains the field `renovate-config` and then put your config under the field `default`. For example: +You then need to publish the `renovate-config-fastcore` package where the `package.json` contains the field `renovate-config` and then put your config under the field `default`. +For example: ```json { @@ -142,7 +156,8 @@ Note: if you prefer to publish using the namespace `@fastcore/renovate-config` t ## GitHub-hosted Presets -It is also possible to host your preset config using just a regular GitHub repository and without needing to publish it to npmjs. In such cases Renovate will simply look for a renovate.json file in the default branch, e.g. master. +It is also possible to host your preset config using just a regular GitHub repository and without needing to publish it to npmjs. +In such cases Renovate will simply look for a renovate.json file in the default branch, e.g. master. To host your preset config on GitHub: @@ -154,11 +169,13 @@ To host your preset config on GitHub: "extends": ["github>rarkins/renovate-config"] ``` -From then on Renovate will use the renovate config from the preset repo's default branch. You do not need to add it as a devDependency or add any other files to the preset repo. +From then on Renovate will use the renovate config from the preset repo's default branch. +You do not need to add it as a devDependency or add any other files to the preset repo. ## GitLab-hosted Presets -It is also possible to host your preset config using just a regular GitLab repository and without needing to publish it to npmjs. In such cases Renovate will simply look for a renovate.json file in the default branch, (for now only the master branch is supported). +It is also possible to host your preset config using just a regular GitLab repository and without needing to publish it to npmjs. +In such cases Renovate will simply look for a renovate.json file in the default branch, (for now only the master branch is supported). To host your preset config on GitLab: @@ -168,26 +185,36 @@ To host your preset config on GitLab: ## Local presets -Renovate also supports local presets, i.e. presets that are hosted on the same platform as the target repository. This is especially helpful in self-hosted scenarios where public presets cannot be used. Local presets are only supported on GitHub, GitLab and Bitbucket Server. Local presets are specified either by leaving out any prefix, e.g. `owner/name`, or explicitly by adding a `local>` prefix, e.g. `local>owner/name`. Renovate will determine the current platform and look up the preset from there. +Renovate also supports local presets, i.e. presets that are hosted on the same platform as the target repository. +This is especially helpful in self-hosted scenarios where public presets cannot be used. +Local presets are only supported on GitHub, GitLab and Bitbucket Server. +Local presets are specified either by leaving out any prefix, e.g. `owner/name`, or explicitly by adding a `local>` prefix, e.g. `local>owner/name`. +Renovate will determine the current platform and look up the preset from there. ## Presets and Private Modules -Using your own preset config along with private npm modules can present a chicken and egg problem. You want to configure the encrypted token just once, which means in the preset. But you also probably want the preset to be private too, so how can the other repos reference it? +Using your own preset config along with private npm modules can present a chicken and egg problem. +You want to configure the encrypted token just once, which means in the preset. +But you also probably want the preset to be private too, so how can the other repos reference it? -The answer is to host your preset using GitHub or GitLab - not npmjs - and make sure you have added the preset's repo to Renovate too. GitHub will then permit Renovate to access the preset repo whenever it is processing any other repos within the same account/org. +The answer is to host your preset using GitHub or GitLab - not npmjs - and make sure you have added the preset's repo to Renovate too. +GitHub will then permit Renovate to access the preset repo whenever it is processing any other repos within the same account/org. ## Contributing to presets -Have you configured a rule that you think others might benefit from? Please consider contributing it to the [Renovate](https://github.com/renovatebot/renovate) repository so that it gains higher visibility and saves others from reinventing the same thing. +Have you configured a rule that you think others might benefit from? +Please consider contributing it to the [Renovate](https://github.com/renovatebot/renovate) repository so that it gains higher visibility and saves others from reinventing the same thing. ## Organization level presets -Whenever repository onboarding happens, Renovate checks if the current user/group/org contains a default config to extend. It looks for: +Whenever repository onboarding happens, Renovate checks if the current user/group/org contains a default config to extend. +It looks for: - A repository called `renovate-config` under the same user/group/org with either `default.json` or `renovate.json`, or - A repository named like `.{{platform}}` (e.g. `.github`) under the same user/group/org with `renovate-config.json` -If found, that repository's preset will be suggested as the the sole extended preset, and any existing `onboardingConfig` config will be ignored/overridden. For example the result may be: +If found, that repository's preset will be suggested as the the sole extended preset, and any existing `onboardingConfig` config will be ignored/overridden. +For example the result may be: ```json { diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index ce1a02410..7a0e7479f 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -5,7 +5,8 @@ description: Configuration Options usable in renovate.json or package.json # Configuration Options -This document describes all the configuration options you may configure in a Renovate configuration file. Any config you define applies to the whole repository (e.g. if you have a monorepo). +This document describes all the configuration options you may configure in a Renovate configuration file. +Any config you define applies to the whole repository (e.g. if you have a monorepo). You can store your Renovate configuration file in one of the following locations: @@ -19,7 +20,8 @@ You can store your Renovate configuration file in one of the following locations - `.renovaterc` - `package.json` _(within a `"renovate"` section)_ -Renovate always uses the config from the repository's default branch, even if that configuration specifies multiple `baseBranches`. Renovate does not read/override the config from within each base branch if present. +Renovate always uses the config from the repository's default branch, even if that configuration specifies multiple `baseBranches`. +Renovate does not read/override the config from within each base branch if present. Also, be sure to check out Renovate's [shareable config presets](/config-presets/) to save yourself from reinventing any wheels. @@ -27,7 +29,9 @@ If you have any questions about the below config options, or would like to get h ## additionalBranchPrefix -This value defaults to an empty string, and is typically not necessary. Some managers populate this field for historical reasons, 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, but one example where it can be useful is combining with `parentDir` in monorepos to split PRs based on where the package definition is located, e.g. +This value defaults to an empty string, and is typically not necessary. +Some managers populate this field for historical reasons, 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, but one example where it can be useful is combining with `parentDir` in monorepos to split PRs based on where the package definition is located, e.g. ```json { @@ -37,11 +41,13 @@ This value defaults to an empty string, and is typically not necessary. Some man ## additionalReviewers -In contrast to `reviewers`, this option adds to the existing reviewer list, rather than replacing it. This makes it suitable for augmenting a preset or base list without displacing the original, for example when adding focused reviewers for a specific package group. +In contrast to `reviewers`, this option adds to the existing reviewer list, rather than replacing it. +This makes it suitable for augmenting a preset or base list without displacing the original, for example when adding focused reviewers for a specific package group. ## aliases -The `aliases` object is used for configuring registry aliases. Currently it is needed/supported for the `helm-requirements` manager only. +The `aliases` object is used for configuring registry aliases. +Currently it is needed/supported for the `helm-requirements` manager only. `helm-requirements` includes this default alias: @@ -57,7 +63,8 @@ Alias values must be properly formatted URIs. ## assignAutomerge -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`, Renovate will instead always assign reviewers and assignees for automerging PRs at time of creation. +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`, Renovate will instead always assign reviewers and assignees for automerging PRs at time of creation. ## assignees @@ -75,9 +82,11 @@ If configured, Renovate will take a random sample of given size from assignees a ## automerge -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. +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. You could configure Renovate to automerge all but major this way: +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 { @@ -90,7 +99,8 @@ 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 (passing) `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 { @@ -123,7 +133,8 @@ Example use: 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". +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 but still want Renovate to automerge, you need to add `"requiredStatusChecks": null` to your configuration. @@ -134,7 +145,8 @@ If you prefer that Renovate more silently automerge _without_ Pull Requests at a - Automerge the branch commit if it's: (a) up-to-date with the base branch, and (b) passing all tests - As a backup, raise a PR only if either: (a) tests fail, or (b) tests remain pending for too long (default: 24 hours) -The final value for `automergeType` is `"pr-comment"`, intended only for users who already have a "merge bot" such as [bors-ng](https://github.com/bors-ng/bors-ng) and want Renovate to _not_ actually automerge by itself and instead tell `bors-ng` to merge for it, by using a comment in the PR. If you're not already using `bors-ng` or similar, don't worry about this option. +The final value for `automergeType` is `"pr-comment"`, intended only for users who already have a "merge bot" such as [bors-ng](https://github.com/bors-ng/bors-ng) and want Renovate to _not_ actually automerge by itself and instead tell `bors-ng` to merge for it, by using a comment in the PR. +If you're not already using `bors-ng` or similar, don't worry about this option. ## azureAutoComplete @@ -144,16 +156,20 @@ You can also configure this using `packageRules` if you want to use it selective ## azureWorkItemId -When creating a PR in Azure DevOps, some branches can be protected with branch policies to [check for linked work items](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops#check-for-linked-work-items). Creating a work item in Azure DevOps is beyond the scope of Renovate, but Renovate can link an already existing work item when creating PRs. +When creating a PR in Azure DevOps, some branches can be protected with branch policies to [check for linked work items](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops#check-for-linked-work-items). +Creating a work item in Azure DevOps is beyond the scope of Renovate, but Renovate can link an already existing work item when creating PRs. ## baseBranches -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: +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: - 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(es) 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. ## bbUseDefaultReviewers @@ -161,30 +177,42 @@ Configuring this to `true` means that Renovate will detect and apply the default ## branchName -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: +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: - 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 configure `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. -`branchPrefix` must be configured at the root of the configuration (e.g. not within any package rule) and is not allowed to use template values. e.g. instead of `renovate/{{parentDir}}-`, configure the template part in `additionalBranchPrefix`, like `"additionalBranchPrefix": "{{parentDir}}-"`. +`branchPrefix` must be configured at the root of the configuration (e.g. not within any package rule) and is not allowed to use template values. +e.g. instead of `renovate/{{parentDir}}-`, configure the template part in `additionalBranchPrefix`, like `"additionalBranchPrefix": "{{parentDir}}-"`. -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. +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 `additionalBranchPrefix` 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. +This field is combined with `branchPrefix` and `additionalBranchPrefix` 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. ## bumpVersion -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 dependencies 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. +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 dependencies 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. -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"`. +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"`. -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. +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. ## commitBody @@ -204,37 +232,48 @@ Another example would be if you want to configure a DCO signoff to each commit. ## commitMessage -Editing of `commitMessage` directly is now deprecated and not recommended. Please instead edit the fields such as `commitMessageAction`, `commitMessageExtra`, etc. +Editing of `commitMessage` directly is now deprecated and not recommended. +Please instead edit the fields such as `commitMessageAction`, `commitMessageExtra`, etc. ## 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. Check out the default value for `commitMessage` to understand how this field is used. +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 -This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. The "extra" is usually an identifier of the new version, e.g. "to v1.3.2" or "to tag 9.2". +This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. +The "extra" is usually an identifier of the new version, e.g. "to v1.3.2" or "to tag 9.2". ## commitMessagePrefix -This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. The "prefix" is usually an automatically applied semantic commit prefix, however it can also be statically configured. +This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. +The "prefix" is usually an automatically applied semantic commit prefix, however it can also be statically configured. ## commitMessageSuffix -This is used to add a suffix to commit messages. Usually left empty except for internal use (multiple base branches, and vulnerability alerts). +This is used to add a suffix to commit messages. +Usually left empty except for internal use (multiple base branches, and vulnerability alerts). ## commitMessageTopic -This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. The "topic" is usually refers to the dependency being updated, e.g. `"dependency react"`. +This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. +The "topic" is usually refers to the dependency being updated, e.g. `"dependency react"`. ## configWarningReuseIssue -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. +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. ## constraints -Constraints are used in package managers which use third party tools to update "artifacts" like lock files or checksum files. Typically, the constraint is detected automatically by Renovate from files within the repository and there is no need to manually configure it. +Constraints are used in package managers which use third party tools to update "artifacts" like lock files or checksum files. +Typically, the constraint is detected automatically by Renovate from files within the repository and there is no need to manually configure it. -Constraints are also used to manually restrict which _datasource_ versions are possible to upgrade to based on their language support. For now this only supports `python`, other compatibility restrictions will be added in the future. +Constraints are also used to manually restrict which _datasource_ versions are possible to upgrade to based on their language support. +For now this only supports `python`, other compatibility restrictions will be added in the future. ```json { @@ -260,7 +299,9 @@ Note: make sure not to mix this up with the term `compatibility`, which Renovate ## dependencyDashboard -Configuring `dependencyDashboard` to `true` will lead to the creation of a "Dependency Dashboard" issue within the repository. This issue contains a list of all PRs pending, open, closed (unmerged) or in error. The goal of this issue is to give visibility into all updates that Renovate is managing. +Configuring `dependencyDashboard` to `true` will lead to the creation of a "Dependency Dashboard" issue within the repository. +This issue contains a list of all PRs pending, open, closed (unmerged) or in error. +The goal of this issue is to give visibility into all updates that Renovate is managing. Examples of what having a Dependency Dashboard will allow you to do: @@ -269,13 +310,16 @@ Examples of what having a Dependency Dashboard will allow you to do: - 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 postponed by closing the original PR) -Note: Enabling the Dependency Dashboard 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 Dependency Dashboard therefore provides visibility as well as additional control. +Note: Enabling the Dependency Dashboard 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 Dependency Dashboard therefore provides visibility as well as additional control. ## dependencyDashboardApproval Setting `dependencyDashboardApproval` to `true` means that Renovate will no longer create branches/PRs automatically but instead wait for manual approval from within the Dependency Dashboard. -In this case, the Dependency Dashboard _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. +In this case, the Dependency Dashboard _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 Dependency Dashboard Approval implicitly enables `dependencyDashboard` too, so it is not necessary to configure both to `true`. @@ -293,7 +337,8 @@ Configure this option if you prefer a different title for the Dependency Dashboa ## description -The description field is used by config presets to describe what they do. They are then collated as part of the onboarding description. +The description field is used by config presets to describe what they do. +They are then collated as part of the onboarding description. ## digest @@ -301,7 +346,8 @@ 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 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. +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 { @@ -328,7 +374,8 @@ If you want the PRs created by Renovate to be considered as drafts rather than n This option is evaluated at PR/MR creation time and is only supported on the following platforms: GitHub, GitLab, Azure. -Note that GitLab implements draft status by checking whether the PR's title starts with certain strings. Therefore, draftPR on GitLab is incompatible with the legacy method of triggering Renovate to rebase a PR by renaming the PR to start with `rebase!`. +Note that GitLab implements draft status by checking whether the PR's title starts with certain strings. +Therefore, draftPR on GitLab is incompatible with the legacy method of triggering Renovate to rebase a PR by renaming the PR to start with `rebase!`. ## enabled @@ -391,7 +438,9 @@ See [Private npm module support](https://docs.renovatebot.com/private-modules) f 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: +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 { @@ -407,7 +456,8 @@ See [shareable config presets](https://docs.renovatebot.com/config-presets) for ## extractVersion -Use this only when the raw version strings from the datasource do not match the expected format that you need in your package file. You must defined a "named capture group" called `version` as shown in the below examples. +Use this only when the raw version strings from the datasource do not match the expected format that you need in your package file. +You must defined a "named capture group" called `version` as shown in the below examples. For example, to extract only the major.minor precision from a GitHub release, the following would work: @@ -437,7 +487,8 @@ Alternatively, to strip a `release-` prefix: } ``` -The above will change a raw version of `release-2.0.0` to `2.0.0`, for example. A similar one could strip leading `v` prefixes: +The above will change a raw version of `release-2.0.0` to `2.0.0`, for example. +A similar one could strip leading `v` prefixes: ```json { @@ -460,9 +511,13 @@ Configure this to `false` if you want to disable release notes fetching 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. +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 possibly guess about. For example, Renovate's default `fileMatch` for `Dockerfile` is `['(^|/|\\.)Dockerfile$', '(^|/)Dockerfile\\.[^/]*$']`. This will catch files like `backend/Dockerfile`, `prefix.Dockerfile` or `Dockerfile.suffix`, 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: +Finally, there are cases where Renovate's default `fileMatch` is good, but you may be using file patterns that a bot couldn't possibly guess about. +For example, Renovate's default `fileMatch` for `Dockerfile` is `['(^|/|\\.)Dockerfile$', '(^|/)Dockerfile\\.[^/]*$']`. +This will catch files like `backend/Dockerfile`, `prefix.Dockerfile` or `Dockerfile.suffix`, 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 { @@ -472,7 +527,8 @@ Finally, there are cases where Renovate's default `fileMatch` is good, but you m } ``` -If you configure `fileMatch` then it must be within a manager object (e.g. `dockerfile` in the above example). The full list of supported managers can be found [here](https://docs.renovatebot.com/modules/manager/). +If you configure `fileMatch` then it must be within a manager object (e.g. `dockerfile` in the above example). +The full list of supported managers can be found [here](https://docs.renovatebot.com/modules/manager/). ## followTag @@ -480,13 +536,16 @@ Caution: advanced functionality. Only use it if you're sure you know what you're 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. +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. +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. ## gitLabAutomerge -Caution (fixed in GitLab >= 12.7): 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. +Caution (fixed in GitLab >= 12.7): 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. ## golang @@ -496,13 +555,19 @@ Configuration added here applies for all Go-related updates, however currently t 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. +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 configure 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: +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 { @@ -518,7 +583,9 @@ The `groupName` field allows free text and does not have any semantic interpreta ## groupSlug -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: +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 { @@ -539,9 +606,11 @@ Note: you shouldn't usually need to configure this unless you really care about ## 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. +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. +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`, `enabled` and `insecureRegistry`. @@ -580,11 +649,13 @@ A preset alternative to the above is: } ``` -Note: Disabling a host is only 100% effective if added to self-hosted config. Renovate currently still checks its _cache_ for results first before making connection attempts, so if a public host is blocked in your repository config (e.g. `renovate.json`) then it's possible you may get cached _results_ from that host if another repository using the same bot has successfully queried for the same dependency recently. +Note: Disabling a host is only 100% effective if added to self-hosted config. +Renovate currently still checks its _cache_ for results first before making connection attempts, so if a public host is blocked in your repository config (e.g. `renovate.json`) then it's possible you may get cached _results_ from that host if another repository using the same bot has successfully queried for the same dependency recently. ### abortIgnoreStatusCodes -This field can be used to configure status codes that Renovate ignores and passes through when `abortOnError` is set to `true`. For example to also skip 404 responses then configure the following: +This field can be used to configure status codes that Renovate ignores and passes through when `abortOnError` is set to `true`. +For example to also skip 404 responses then configure the following: ```json { @@ -601,7 +672,8 @@ Note that this field is _not_ mergeable, so the last-applied host rule will take ### abortOnError -Use this field to configure Renovate to abort runs for custom hosts. By default, Renovate will only abort for known public hosts, which has the downside that transient errors for other hosts can cause autoclosing of PRs. +Use this field to configure Renovate to abort runs for custom hosts. +By default, Renovate will only abort for known public hosts, which has the downside that transient errors for other hosts can cause autoclosing of PRs. To abort Renovate runs for http failures from _any_ host: @@ -645,13 +717,15 @@ When this field is enabled, Renovate will abort its run if it encounters either ### baseUrl -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. +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. +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. ### enableHttp2 @@ -661,13 +735,16 @@ Enable got [http2](https://github.com/sindresorhus/got/blob/v11.5.2/readme.md#ht ### 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. +`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 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. +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: @@ -684,7 +761,9 @@ Example: ### timeout -Use this figure to adjust the timeout for queries. The default is 60s, which is quite high. To adjust it down to 10s for all queries, do this: +Use this figure to adjust the timeout for queries. +The default is 60s, which is quite high. +To adjust it down to 10s for all queries, do this: ```json { @@ -698,13 +777,15 @@ Use this figure to adjust the timeout for queries. The default is 60s, which is ## ignoreDeprecated -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. +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 -The `ignoreDeps` configuration field allows you to define a list of dependency names to be ignored by Renovate. Currently it supports only "exact match" dependency names and not any patterns. e.g. to ignore both `eslint` and `eslint-config-base` you would add this to your config: +The `ignoreDeps` configuration field allows you to define a list of dependency names to be ignored by Renovate. +Currently it supports only "exact match" dependency names and not any patterns. e.g. to ignore both `eslint` and `eslint-config-base` you would add this to your config: ```json { @@ -727,15 +808,20 @@ The above is the same as if you wrote this package rule: ## ignoreNpmrcFile -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. +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 -Using this setting, you can selectively ignore package files that you don't want Renovate autodiscovering. For instance if your repository has an "examples" directory of many package.json files that you don't want to be kept up to date. +Using this setting, you can selectively ignore package files that you don't want Renovate autodiscovering. +For instance if your repository has an "examples" directory of many package.json files that you don't want to be kept up to date. ## ignorePresets -Use this if you are extending a complex preset but don't want to use every "sub preset" that it includes. For example, consider 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, consider this config: ```json { @@ -752,13 +838,17 @@ 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 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`. +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, 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`. +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. @@ -779,7 +869,10 @@ Use this configuration option for shared config across npm/Yarn/pnpm and meteor ## labels -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. +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: @@ -799,9 +892,13 @@ With the above config, every PR raised by Renovate will have the label `dependen ## lockFileMaintenance -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`, `composer.lock`, `Gemfile.lock`, `poetry.lock` and `Cargo.lock`. Others may be added via feature request. +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`, `composer.lock`, `Gemfile.lock`, `poetry.lock` and `Cargo.lock`. +Others may be added via feature request. -This feature is disabled 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 { @@ -809,7 +906,8 @@ This feature is disabled by default. If you wish to enable this feature then you } ``` -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. +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 @@ -827,7 +925,8 @@ Check out our [Node.js documentation](https://docs.renovatebot.com/node) for a c ## npmToken -See [Private npm module support](https://docs.renovatebot.com/private-modules) for details on how this is used. Typically you would encrypt it and put it inside the `encrypted` object. +See [Private npm module support](https://docs.renovatebot.com/private-modules) for details on how this is used. +Typically you would encrypt it and put it inside the `encrypted` object. ## npmrc @@ -867,7 +966,10 @@ Here is an example where you might want to limit the "noisy" package `aws-sdk` t For Maven dependencies, the package name is ``, eg `"packageNames": ["com.thoughtworks.xstream:xstream"]` -Note how the above uses `packageNames` instead of `packagePatterns` because it is an exact match package name. This is the equivalent of defining `"packagePatterns": ["^aws\-sdk$"]` and hence much simpler. However you can mix together both `packageNames` and `packagePatterns` in the same package rule and the rule will be applied if _either_ match. Example: +Note how the above uses `packageNames` instead of `packagePatterns` because it is an exact match package name. +This is the equivalent of defining `"packagePatterns": ["^aws\-sdk$"]` and hence much simpler. +However you can mix together both `packageNames` and `packagePatterns` in the same package rule and the rule will be applied if _either_ match. +Example: ```json { @@ -883,7 +985,8 @@ Note how the above uses `packageNames` instead of `packagePatterns` because it i The above rule will group together the `neutrino` package and any package matching `@neutrino/*`. -Path rules are convenient to use if you wish to apply configuration rules to certain package files using patterns. For example, if you have an `examples` directory and you want all updates to those examples to use the `chore` prefix instead of `fix`, then you could add this configuration: +Path rules are convenient to use if you wish to apply configuration rules to certain package files using patterns. +For example, if you have an `examples` directory and you want all updates to those examples to use the `chore` prefix instead of `fix`, then you could add this configuration: ```json { @@ -896,7 +999,8 @@ Path rules are convenient to use if you wish to apply configuration rules to cer } ``` -If you wish to limit renovate to apply configuration rules to certain files in the root repository directory, you have to use `paths` with either a partial string match or a minimatch pattern. For example you have multiple `package.json` and want to use `dependencyDashboardApproval` only on the root `package.json`: +If you wish to limit renovate to apply configuration rules to certain files in the root repository directory, you have to use `paths` with either a partial string match or a minimatch pattern. +For example you have multiple `package.json` and want to use `dependencyDashboardApproval` only on the root `package.json`: ```json { @@ -909,11 +1013,13 @@ If you wish to limit renovate to apply configuration rules to certain files in t } ``` -Important to know: Renovate will evaluate all `packageRules` and not stop once it gets a first match. Therefore, you should order your `packageRules` in order of importance so that later rules can override settings from earlier rules if necessary. +Important to know: Renovate will evaluate all `packageRules` and not stop once it gets a first match. +Therefore, you should order your `packageRules` in order of importance so that later rules can override settings from earlier rules if necessary. ### allowedVersions -Use this - usually within a packageRule - to limit how far to upgrade a dependency. For example, if you wish to upgrade to Angular v1.5 but not to `angular` v1.6 or higher, you could define this to be `<= 1.5` or `< 1.6.0`: +Use this - usually within a packageRule - to limit how far to upgrade a dependency. +For example, if you wish to upgrade to Angular v1.5 but not to `angular` v1.6 or higher, you could define this to be `<= 1.5` or `< 1.6.0`: ```json { @@ -928,7 +1034,8 @@ Use this - usually within a packageRule - to limit how far to upgrade a dependen The valid syntax for this will be calculated at runtime because it depends on the versioning scheme, which is itself dynamic. -This field also supports Regular Expressions if they begin and end with `/`. For example, the following will enforce that only 3 or 4-section versions are supported, without any prefixes: +This field also supports Regular Expressions if they begin and end with `/`. +For example, the following will enforce that only 3 or 4-section versions are supported, without any prefixes: ```json { @@ -941,7 +1048,8 @@ This field also supports Regular Expressions if they begin and end with `/`. For } ``` -This field also supports a special negated regex syntax for ignoring certain versions. Use the syntax `!/ /` like the following: +This field also supports a special negated regex syntax for ignoring certain versions. +Use the syntax `!/ /` like the following: ```json { @@ -956,13 +1064,16 @@ This field also supports a special negated regex syntax for ignoring certain ver ### depTypeList -Use this field if you want to limit a `packageRule` to certain `depType` values. Invalid if used outside of a `packageRule`. +Use this field if you want to limit a `packageRule` to certain `depType` values. +Invalid if used outside of a `packageRule`. ### excludePackageNames -**Important**: Do not mix this up with the option `ignoreDeps`. Use `ignoreDeps` instead if all you want to do is have a list of package names for Renovate to ignore. +**Important**: Do not mix this up with the option `ignoreDeps`. +Use `ignoreDeps` instead if all you want to do is have a list of package names for Renovate to ignore. -Use `excludePackageNames` if you want to have one or more exact name matches excluded in your package rule. See also `packageNames`. +Use `excludePackageNames` if you want to have one or more exact name matches excluded in your package rule. +See also `packageNames`. ```json { @@ -979,7 +1090,8 @@ The above will match all package names starting with `eslint` but exclude the sp ### excludePackagePatterns -Use this field if you want to have one or more package name patterns excluded in your package rule. See also `packagePatterns`. +Use this field if you want to have one or more package name patterns excluded in your package rule. +See also `packagePatterns`. ```json { @@ -1063,7 +1175,8 @@ Use this field to restrict rules to a particular datasource. e.g. ### packageNames -Use this field if you want to have one or more exact name matches in your package rule. See also `excludedPackageNames`. +Use this field if you want to have one or more exact name matches in your package rule. +See also `excludedPackageNames`. ```json { @@ -1080,7 +1193,8 @@ The above will configure `rangeStrategy` to `pin` only for the package `angular` ### packagePatterns -Use this field if you want to have one or more package names patterns in your package rule. See also `excludePackagePatterns`. +Use this field if you want to have one or more package names patterns in your package rule. +See also `excludePackagePatterns`. ```json { @@ -1097,7 +1211,8 @@ The above will configure `rangeStrategy` to `replace` for any package starting w ### paths -Renovate will match `paths` against both a partial string match or a minimatch glob pattern. If you want to avoid the partial string matching so that only glob matching is performed, wrap your string in `+(...)` like so: +Renovate will match `paths` against both a partial string match or a minimatch glob pattern. +If you want to avoid the partial string matching so that only glob matching is performed, wrap your string in `+(...)` like so: ``` "paths": ["+(package.json)"], @@ -1139,7 +1254,8 @@ Here's an example of where you use this to group together all packages from the ### updateTypes -Use this field to match rules against types of updates. For example to apply a special label for Major updates: +Use this field to match rules against types of updates. +For example to apply a special label for Major updates: ```json { @@ -1154,7 +1270,8 @@ Use this field to match rules against types of updates. For example to apply a s ## patch -Add to this object if you wish to define rules that apply only to patch updates. See also `major` and `minor` configuration options. +Add to this object if you wish to define rules that apply only to patch updates. +See also `major` and `minor` configuration options. ## php @@ -1175,9 +1292,12 @@ If enabled Renovate will pin Docker images by means of their SHA256 digest and n ## postUpgradeTasks -Post-upgrade tasks are commands that are executed by Renovate after a dependency has been updated but before the commit is created. The intention is to run any additional command line tools that would modify existing files or generate new files when a dependency changes. +Post-upgrade tasks are commands that are executed by Renovate after a dependency has been updated but before the commit is created. +The intention is to run any additional command line tools that would modify existing files or generate new files when a dependency changes. -This is only available on Renovate instances that have a `trustLevel` of 'high'. Each command must match at least one of the patterns defined in `allowedPostUpgradeTasks` in order to be executed. If the list of allowed tasks is empty then no tasks will be executed. +This is only available on Renovate instances that have a `trustLevel` of 'high'. +Each command must match at least one of the patterns defined in `allowedPostUpgradeTasks` in order to be executed. +If the list of allowed tasks is empty then no tasks will be executed. e.g. @@ -1286,7 +1406,10 @@ 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 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". +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". ## prFooter @@ -1302,17 +1425,26 @@ 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 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. +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 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. +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 -Sometimes Renovate needs to rate limit its creation of PRs, e.g. hourly or concurrent PR limits. In such cases it sorts/prioritizes by default based on the update type (e.g. patches raised before minor, minor before major). If you have dependencies that are more or less important than others then you can use the `prPriority` field for PR sorting. The default value is 0, so therefore setting a negative value will make dependencies sort last, while higher values sort first. +Sometimes Renovate needs to rate limit its creation of PRs, e.g. hourly or concurrent PR limits. +In such cases it sorts/prioritizes by default based on the update type (e.g. patches raised before minor, minor before major). +If you have dependencies that are more or less important than others then you can use the `prPriority` field for PR sorting. +The default value is 0, so therefore setting a negative value will make dependencies sort last, while higher values sort first. Here's an example of how you would define PR priority so that devDependencies are raised last and `react` is raised first: @@ -1337,7 +1469,8 @@ The PR title is important for some of Renovate's matching algorithms (e.g. deter ## pruneStaleBranches -Configure 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`. ## python @@ -1364,15 +1497,18 @@ Renovate's `"auto"` strategy works like this for npm: **bump** -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. +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 configure `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`. ## rebaseLabel -On supported platforms it is possible to add a label to a PR to manually request Renovate to recreate/rebase it. By default this label is `"rebase"` however you can configure it to anything you want by changing this `rebaseLabel` field. +On supported platforms it is possible to add a label to a PR to manually request Renovate to recreate/rebase it. +By default this label is `"rebase"` however you can configure it to anything you want by changing this `rebaseLabel` field. ## rebaseWhen @@ -1387,7 +1523,10 @@ Note: this field replaces the previous fields of `rebaseConflictedPrs` and `reba ## recreateClosed -By default, Renovate will detect if it has proposed an update to a project before and not propose the same one again. For example the Webpack 3.x case described above. This field lets you customise this behaviour down to a per-package level. For example we override it to `true` in the following cases where branch names and PR titles need to be reused: +By default, Renovate will detect if it has proposed an update to a project before and not propose the same one again. +For example the Webpack 3.x case described above. +This field lets you customise this behaviour down to a per-package level. +For example we override it to `true` in the following cases where branch names and PR titles need to be reused: - Package groups - When pinning versions @@ -1404,13 +1543,18 @@ Users can define custom managers for cases such as: - Proprietary file formats or conventions - Popular file formats not yet supported as a manager by Renovate -The custom manager concept is based on using Regular Expression named capture groups. For the fields `datasource`, `depName` and `currentValue`, it's mandatory to have either a named capture group matching them (e.g. `(?.*)`) or to configure it's corresponding template (e.g. `depNameTemplate`). It's not recommended to do both, due to the potential for confusion. It is recommended to also include `versioning` however if it is missing then it will default to `semver`. +The custom manager concept is based on using Regular Expression named capture groups. +For the fields `datasource`, `depName` and `currentValue`, it's mandatory to have either a named capture group matching them (e.g. `(?.*)`) or to configure it's corresponding template (e.g. `depNameTemplate`). +It's not recommended to do both, due to the potential for confusion. +It is recommended to also include `versioning` however if it is missing then it will default to `semver`. -For more details and examples, see the documentation page the for the regex manager [here](/modules/manager/regex/). For template fields, use the triple brace `{{{ }}}` notation to avoid `handlebars` escaping any special characters. +For more details and examples, see the documentation page the for the regex manager [here](/modules/manager/regex/). +For template fields, use the triple brace `{{{ }}}` notation to avoid `handlebars` escaping any special characters. ### matchStrings -`matchStrings` should each be a valid regular expression, optionally with named capture groups. Currently only a length of one `matchString` is supported. +`matchStrings` should each be a valid regular expression, optionally with named capture groups. +Currently only a length of one `matchString` is supported. Example: @@ -1424,23 +1568,29 @@ Example: ### depNameTemplate -If `depName` cannot be captured with a named capture group in `matchString` then it can be defined manually using this field. It will be compiled using `handlebars` and the regex `groups` result. +If `depName` cannot be captured with a named capture group in `matchString` then it can be defined manually using this field. +It will be compiled using `handlebars` and the regex `groups` result. ### lookupNameTemplate -`lookupName` is used for looking up dependency versions. It will be compiled using `handlebars` and the regex `groups` result. It will default to the value of `depName` if left unconfigured/undefined. +`lookupName` is used for looking up dependency versions. +It will be compiled using `handlebars` and the regex `groups` result. +It will default to the value of `depName` if left unconfigured/undefined. ### datasourceTemplate -If the `datasource` for a dependency is not captured with a named group then it can be defined in config using this field. It will be compiled using `handlebars` and the regex `groups` result. +If the `datasource` for a dependency is not captured with a named group then it can be defined in config using this field. +It will be compiled using `handlebars` and the regex `groups` result. ### versioningTemplate -If the `versioning` for a dependency is not captured with a named group then it can be defined in config using this field. It will be compiled using `handlebars` and the regex `groups` result. +If the `versioning` for a dependency is not captured with a named group then it can be defined in config using this field. +It will be compiled using `handlebars` and the regex `groups` result. ## registryUrls -Usually Renovate is able to either (a) use the default registries for a datasource, or (b) automatically detect during the manager extract phase which custom registries are in use. In case there is a need to configure them manually, it can be done using this `registryUrls` field, typically using `packageUrls` like so: +Usually Renovate is able to either (a) use the default registries for a datasource, or (b) automatically detect during the manager extract phase which custom registries are in use. +In case there is a need to configure them manually, it can be done using this `registryUrls` field, typically using `packageUrls` like so: ```json { @@ -1457,17 +1607,21 @@ The field supports multiple URLs however it is datasource-dependent on whether o ## requiredStatusChecks -This is a future feature that is partially implemented. Currently Renovate's default behaviour is to only automerge if every status check has succeeded. In future, this might be configurable to allow certain status checks to be ignored. +This is a future feature that is partially implemented. +Currently Renovate's default behaviour is to only automerge if every status check has succeeded. +In future, this might be configurable to allow certain status checks to be ignored. You can still override this to `null` today if your repository doesn't support status checks (i.e. no tests) but you still want to use Renovate anyway. ## respectLatest -Similar to `ignoreUnstable`, this option controls whether to update to versions that are greater than the version tagged as `latest` in the repository. By default, `renovate` will update to a version greater than `latest` only if the current version is itself past latest. +Similar to `ignoreUnstable`, this option controls whether to update to versions that are greater than the version tagged as `latest` in the repository. +By default, `renovate` will update to a version greater than `latest` only if the current version is itself past latest. ## reviewers -Must be valid usernames. If on GitHub and assigning a team to review, use the prefix `team:`, e.g. provide a value like `team:someteam`. +Must be valid usernames. +If on GitHub and assigning a team to review, use the prefix `team:`, e.g. provide a value like `team:someteam`. ## reviewersFromCodeOwners @@ -1489,11 +1643,14 @@ Configure this to `false` either globally, per-language, or per-package if you w ## schedule -The `schedule` option allows you to define times of week or month for Renovate updates. Running Renovate around the clock may seem too "noisy" for some projects and therefore `schedule` is a good way to reduce the noise by reducing the timeframe in which Renovate will operate on your repository. +The `schedule` option allows you to define times of week or month for Renovate updates. +Running Renovate around the clock may seem too "noisy" for some projects and therefore `schedule` is a good way to reduce the noise by reducing the timeframe in which Renovate will operate on your repository. -The default value for `schedule` is "at any time", which is functionally the same as declaring a `null` schedule. i.e. Renovate will run on the repository around the clock. +The default value for `schedule` is "at any time", which is functionally the same as declaring a `null` schedule. +i.e. Renovate will run on the repository around the clock. -The easiest way to define a schedule is to use a preset if one of them fits your requirements. See [Schedule presets](https://docs.renovatebot.com/presets-schedule/) for details and feel free to request a new one in the source repository if you think others would benefit from it too. +The easiest way to define a schedule is to use a preset if one of them fits your requirements. +See [Schedule presets](https://docs.renovatebot.com/presets-schedule/) for details and feel free to request a new one in the source repository if you think others would benefit from it too. Otherwise, here are some text schedules that are known to work: @@ -1506,7 +1663,8 @@ on friday and saturday every 3 months on the first day of the month ``` -One example might be that you don't want Renovate to run during your typical business hours, so that your build machines don't get clogged up testing `package.json` updates. You could then configure a schedule like this at the repository level: +One example might be that you don't want Renovate to run during your typical business hours, so that your build machines don't get clogged up testing `package.json` updates. +You could then configure a schedule like this at the repository level: ```json { @@ -1535,45 +1693,67 @@ Technical details: We mostly rely on the text parsing of the library [later](htt ## semanticCommitScope -By default you will see Angular-style commit prefixes like `"chore(deps):"`. If you wish to change it to something else like `"package"` then it will look like `"chore(package):"`. You can also use `parentDir` or `baseDir` to namespace your commits for monorepos e.g. `"{{parentDir}}"`. +By default you will see Angular-style commit prefixes like `"chore(deps):"`. +If you wish to change it to something else like `"package"` then it will look like `"chore(package):"`. +You can also use `parentDir` or `baseDir` to namespace your commits for monorepos e.g. `"{{parentDir}}"`. ## semanticCommitType -By default you will see Angular-style commit prefixes like `"chore(deps):"`. If you wish to change it to something else like "ci" then it will look like `"ci(deps):"`. +By default you will see Angular-style commit prefixes like `"chore(deps):"`. +If you wish to change it to something else like "ci" then it will look like `"ci(deps):"`. ## 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 configured to `true`, then the `semanticCommitScope` and `semanticCommitType` fields 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 `semanticCommitScope` and `semanticCommitType` fields 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. ## separateMajorMinor -Renovate's default behaviour is to create a separate branch/PR if both minor and major version updates exist (note that your choice of `rangeStrategy` value can influence which updates exist in the first place however). 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. +Renovate's default behaviour is to create a separate branch/PR if both minor and major version updates exist (note that your choice of `rangeStrategy` value can influence which updates exist in the first place however). +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 configured 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 -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. +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 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. +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: #### Suppress branch/PR creation for X days -If you combine `stabilityDays=3` and `prCreation="not-pending"` then Renovate will hold back from creating branches until 3 or more days have elapsed since the version was released. It's recommended that you enable `dependencyDashboard=true` so you don't lose visibility of these pending PRs. +If you combine `stabilityDays=3` and `prCreation="not-pending"` then Renovate will hold back from creating branches until 3 or more days have elapsed since the version was released. +It's recommended that you enable `dependencyDashboard=true` so you don't lose visibility of these pending PRs. #### Await X days before Automerging -If you have both `automerge` as well as `stabilityDays` enabled, it means that PRs will be created immediately but automerging will be delayed until X days have passed. This works because Renovate will add a "renovate/stability-days" pending status check to each branch/PR and that pending check will prevent the branch going green to automerge. +If you have both `automerge` as well as `stabilityDays` enabled, it means that PRs will be created immediately but automerging will be delayed until X days have passed. +This works because Renovate will add a "renovate/stability-days" pending status check to each branch/PR and that pending check will prevent the branch going green to automerge. ## supportPolicy @@ -1583,7 +1763,8 @@ Language support is limited to those listed below: ## suppressNotifications -Use this field to suppress various types of warnings and other notifications from Renovate. Example: +Use this field to suppress various types of warnings and other notifications from Renovate. +Example: ```json { @@ -1595,7 +1776,8 @@ The above config will suppress the comment which is added to a PR whenever you c ## timezone -It is only recommended to configure this field if you wish to use the `schedules` feature and want to write them in your local timezone. 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. ## unicodeEmoji @@ -1603,27 +1785,36 @@ If enabled emoji shortcodes (`:warning:`) are replaced with their unicode equiva ## unpublishSafe -It is not known by many that npm package authors and collaborators can _delete_ an npm version if it is less than 24 hours old. e.g. version 1.0.0 might exist, then version 1.1.0 is released, and then version 1.1.0 might get deleted hours later. This means that version 1.1.0 essentially "disappears" and 1.0.0 returns to being the "latest". If you have installed 1.1.0 during that time then your build is essentially broken. +It is not known by many that npm package authors and collaborators can _delete_ an npm version if it is less than 24 hours old. +e.g. version 1.0.0 might exist, then version 1.1.0 is released, and then version 1.1.0 might get deleted hours later. +This means that version 1.1.0 essentially "disappears" and 1.0.0 returns to being the "latest". +If you have installed 1.1.0 during that time then your build is essentially broken. -Enabling `unpublishSafe` will add a `renovate/unpublish-safe` status check with value pending to every branch to warn you about this possibility. It can be handy when used with the `prCreation` = `not-pending` configuration option - that way you won't get the PR raised until after a patch is 24 hours old or more. +Enabling `unpublishSafe` will add a `renovate/unpublish-safe` status check with value pending to every branch to warn you about this possibility. +It can be handy when used with the `prCreation` = `not-pending` configuration option - that way you won't get the PR raised until after a patch is 24 hours old or more. ## updateLockFiles ## 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 configured 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 configure 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`. ## versioning -Usually, each language or package manager has a specific type of "versioning". e.g. JavaScript uses npm's semver implementation, Python uses pep440, etc. At Renovate we have also implemented some of our own, such as `"docker"` to address the most common way people tag versions using Docker, and `"loose"` as a fallback that tries semver first but otherwise just does its best to sort and compare. +Usually, each language or package manager has a specific type of "versioning". e.g. JavaScript uses npm's semver implementation, Python uses pep440, etc. +At Renovate we have also implemented some of our own, such as `"docker"` to address the most common way people tag versions using Docker, and `"loose"` as a fallback that tries semver first but otherwise just does its best to sort and compare. -By exposing `versioning` to config, it allows you to override the default versioning for a package manager if you really need. In most cases it would not be recommended, but there are some cases such as Docker or Gradle where versioning is not strictly defined and you may need to specify the versioning type per-package. +By exposing `versioning` to config, it allows you to override the default versioning for a package manager if you really need. +In most cases it would not be recommended, but there are some cases such as Docker or Gradle where versioning is not strictly defined and you may need to specify the versioning type per-package. ## vulnerabilityAlerts -Use this object to customise PRs that are raised when vulnerability alerts are detected (GitHub-only). For example, to configure 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 { diff --git a/docs/usage/configuration-templates.md b/docs/usage/configuration-templates.md index 09068e4ff..33b84b951 100644 --- a/docs/usage/configuration-templates.md +++ b/docs/usage/configuration-templates.md @@ -9,39 +9,52 @@ This document describes how you can edit the branch names, commit messages, or P ## Branch Name -The branch name is very important for Renovate because it helps determine "grouping" of updates, and also makes it efficient when an existing PR needs to be updated with a newer version. Also, if you change branchPrefix and have some upgrades "ignored" (closed without merging) then you may see duplicate PRs opened with your new branch name. +The branch name is very important for Renovate because it helps determine "grouping" of updates, and also makes it efficient when an existing PR needs to be updated with a newer version. +Also, if you change branchPrefix and have some upgrades "ignored" (closed without merging) then you may see duplicate PRs opened with your new branch name. `branchName` has a default value of `{{{branchPrefix}}}{{{additionalBranchPrefix}}}{{{branchTopic}}}`. -The most common type of branch name you will see looks like this: `renovate/react-16.x`. In this example, the `branchPrefix` is the default `renovate/`, `additionalBranchPrefix` is empty, and `branchTopic` is `react-16.x`. +The most common type of branch name you will see looks like this: `renovate/react-16.x`. +In this example, the `branchPrefix` is the default `renovate/`, `additionalBranchPrefix` is empty, and `branchTopic` is `react-16.x`. -Most people can leave `branchPrefix` as `renovate/` however if you prefer to have no forward slashes then you might pick `renovate-` instead. Please note that the onboarding PR is fixed to use `renovate/configure` however. +Most people can leave `branchPrefix` as `renovate/` however if you prefer to have no forward slashes then you might pick `renovate-` instead. +Please note that the onboarding PR is fixed to use `renovate/configure` however. -`additionalBranchPrefix` is optional and by default is empty for all JavaScript dependencies. We use `docker-` for all Docker updates, so you might see branches like `renovate/docker-ubuntu-16.x`. +`additionalBranchPrefix` is optional and by default is empty for all JavaScript dependencies. +We use `docker-` for all Docker updates, so you might see branches like `renovate/docker-ubuntu-16.x`. -`branchTopic` depends on the package manager and upgrade type, so you will see a lot of variety. It is also the one you might be most likely to want to change, but be careful and consider posting your config to https://github.com/renovateapp/config-help first. +`branchTopic` depends on the package manager and upgrade type, so you will see a lot of variety. +It is also the one you might be most likely to want to change, but be careful and consider posting your config to https://github.com/renovateapp/config-help first. ## Commit Message -Renovate is designed to have just a single commit per branch, for merging convenience. As such, that commitMessage should reflect the contents of the branch and usually be the same as the PR Title. +Renovate is designed to have just a single commit per branch, for merging convenience. +As such, that commitMessage should reflect the contents of the branch and usually be the same as the PR Title. `commitMessage` has a default value of `{{commitMessagePrefix}} {{commitMessageAction}} {{commitMessageTopic}} {{commitMessageExtra}} {{commitMessageSuffix}}`, with the intention that you only edit some of those subcomponents. -`commitMessagePrefix` is usually not necessary to configure directly, and is used by Renovate if it needs to add a prefix due to Semantic Commit conventions. Do not touch it unless you know what you're doing. +`commitMessagePrefix` is usually not necessary to configure directly, and is used by Renovate if it needs to add a prefix due to Semantic Commit conventions. +Do not touch it unless you know what you're doing. -`commitMessageAction` is usually just 1 word, e.g. 'Update', 'Pin', 'Refresh', etc. It's usually also not necessary to edit, although maybe you prefer 'Upgrade' instead of 'Update'? +`commitMessageAction` is usually just 1 word, e.g. 'Update', 'Pin', 'Refresh', etc. +It's usually also not necessary to edit, although maybe you prefer 'Upgrade' instead of 'Update'? -`commitMessageTopic` is usually 2-3 words aimed to identify _what_ is being updated. e.g. it might be `dependency react` or `Docker image ubuntu`. You may want to edit this, but if you think your idea/requirement is a good one then maybe you can propose it to the project or publish it as a preset config for others with similar requirements. +`commitMessageTopic` is usually 2-3 words aimed to identify _what_ is being updated. e.g. it might be `dependency react` or `Docker image ubuntu`. +You may want to edit this, but if you think your idea/requirement is a good one then maybe you can propose it to the project or publish it as a preset config for others with similar requirements. -`commitMessageExtra` usually refers to the version being updated to. e.g. `to v16` for a major upgrade, or `to v16.0.3` for a patch update. It may also be empty in some cases, e.g. if the action/topic is `Pin Docker digests`. +`commitMessageExtra` usually refers to the version being updated to. e.g. `to v16` for a major upgrade, or `to v16.0.3` for a patch update. +It may also be empty in some cases, e.g. if the action/topic is `Pin Docker digests`. -`commitMessageSuffix` defaults to empty and is there for flexibility and future use. Maybe for `major` updates you always want the PR to end with `(MAJOR)`, for instance. +`commitMessageSuffix` defaults to empty and is there for flexibility and future use. +Maybe for `major` updates you always want the PR to end with `(MAJOR)`, for instance. -`commitBody` is used if you wish to add multi-line commit messages, such as for the `Signed-off-by` fields, or adding `[skip-ci]`, etc. It is appended to the generated `commitMessage`, separated by a newline. +`commitBody` is used if you wish to add multi-line commit messages, such as for the `Signed-off-by` fields, or adding `[skip-ci]`, etc. +It is appended to the generated `commitMessage`, separated by a newline. ## PR Title -Because commit messages should usually match with the PR title, the PR title template now defaults to `null` and inherits whatever is configured for `commitMessage`. If you have a requirement where `prTitle` should be different from `commitMessage`, then please raise a feature request for discussion. +Because commit messages should usually match with the PR title, the PR title template now defaults to `null` and inherits whatever is configured for `commitMessage`. +If you have a requirement where `prTitle` should be different from `commitMessage`, then please raise a feature request for discussion. ## PR Body diff --git a/docs/usage/configure-renovate.md b/docs/usage/configure-renovate.md index c32a99f98..2cc906ccc 100644 --- a/docs/usage/configure-renovate.md +++ b/docs/usage/configure-renovate.md @@ -11,17 +11,21 @@ Once you have enabled Renovate on a repository, you will receive a "Configure Re ## No Risk Onboarding -Conveniently, Renovate will not make any changes to your repository or raise any further Pull Requests until after you _merge_ this initial Pull Request. So if there is anything about the Pull Request that you don't like or understand, take your time to read [documentation](https://docs.renovatebot.com) or ask questions in one of our support forums and merge the PR only once you're satisfied with the result. You can edit your Renovate configuration **within this `renovate/configure` branch** and Renovate will keep updating the description in the PR to match, so you can keep doing that until you're satisfied with the results. +Conveniently, Renovate will not make any changes to your repository or raise any further Pull Requests until after you _merge_ this initial Pull Request. +So if there is anything about the Pull Request that you don't like or understand, take your time to read [documentation](https://docs.renovatebot.com) or ask questions in one of our support forums and merge the PR only once you're satisfied with the result. +You can edit your Renovate configuration **within this `renovate/configure` branch** and Renovate will keep updating the description in the PR to match, so you can keep doing that until you're satisfied with the results. ## Check for Warnings -If you have any Warnings or Errors listed, see if you need or want to make any changes to address them. If you do, then make them in your base branch (e.g. `master`) so that Renovate can recreate its Configure Renovate PR from it on its next cycle. +If you have any Warnings or Errors listed, see if you need or want to make any changes to address them. +If you do, then make them in your base branch (e.g. `master`) so that Renovate can recreate its Configure Renovate PR from it on its next cycle. ## Configuration Location The Configure Renovate PR will include a `renovate.json` file in the root directory, with suggested default settings. -If you don't want to have an additional file (`renovate.json`) in your repository then you can instead add the same settings to a `"renovate"` section in your `package.json`, if you are already using this (e.g. JavaScript project). Any settings made in `package.json` will apply to the whole project (including other, nested `package.json` files). +If you don't want to have an additional file (`renovate.json`) in your repository then you can instead add the same settings to a `"renovate"` section in your `package.json`, if you are already using this (e.g. JavaScript project). +Any settings made in `package.json` will apply to the whole project (including other, nested `package.json` files). Alternatively, if you prefer to use "dot files" then you can add the same JSON configuration to either a `.renovaterc` file or `.renovaterc.json` file instead of `renovate.json`. diff --git a/docs/usage/dependency-pinning.md b/docs/usage/dependency-pinning.md index 3583499ea..d489ee655 100644 --- a/docs/usage/dependency-pinning.md +++ b/docs/usage/dependency-pinning.md @@ -5,73 +5,108 @@ description: The pros and cons of dependency pinning for JavaScript/npm # Should you Pin your JavaScript Dependencies? -Once you start using a tool/service like Renovate, probably the biggest decision you need to make is whether to "pin" your dependencies instead of using semver ranges. The answer is "It's your choice", however we can certainly make some generalisations/recommendations to help you. Jump to the bottom conclusions if you get impatient. +Once you start using a tool/service like Renovate, probably the biggest decision you need to make is whether to "pin" your dependencies instead of using semver ranges. +The answer is "It's your choice", however we can certainly make some generalisations/recommendations to help you. +Jump to the bottom conclusions if you get impatient. ## What is Dependency Pinning? To ensure we're all talking about the same thing, it's important to define exactly what we mean by dependency "pinning". -Historically, projects use semver ranges in their `package.json`. For instance, if you run `npm install foobar` you will see an entry like `"foobar": "^1.1.0"` added to your `package.json`. Verbosely, this means "any foobar version greater than or equal to 1.1.0 but less than 2". Therefore the project will automatically use 1.1.1 if it's released, or 1.2.0, or 1.2.1, etc - meaning you will get not only patch updates but also feature (minor) releases too. +Historically, projects use semver ranges in their `package.json`. +For instance, if you run `npm install foobar` you will see an entry like `"foobar": "^1.1.0"` added to your `package.json`. +Verbosely, this means "any foobar version greater than or equal to 1.1.0 but less than 2". +Therefore the project will automatically use 1.1.1 if it's released, or 1.2.0, or 1.2.1, etc - meaning you will get not only patch updates but also feature (minor) releases too. -Another alternative is ranges like `"foobar": "~1.1.0"` which means "any foobar version greater than or equal to 1.1.0 but less than 1.2". This narrows the range to only patch updates to the 1.1 range. +Another alternative is ranges like `"foobar": "~1.1.0"` which means "any foobar version greater than or equal to 1.1.0 but less than 1.2". +This narrows the range to only patch updates to the 1.1 range. If instead you "pin" your dependencies rather than use ranges, it means you use exact entries like `"foobar": "1.1.0"` which means "use only foobar version 1.1.0 and no other". ## Why use ranges? -For projects of any type, the main reason to use ranges is so that you can "automatically" get updated releases - which may even include security fixes. By "automatically", we mean that any time you run `npm install` you will get the very latest version matching your semver - assuming you're not using a lock file, that is. +For projects of any type, the main reason to use ranges is so that you can "automatically" get updated releases - which may even include security fixes. +By "automatically", we mean that any time you run `npm install` you will get the very latest version matching your semver - assuming you're not using a lock file, that is. #### Tilde vs Caret -If you're familiar with the theory of semver, you might think that you only need to use tilde ranges (e.g. `"~1.1.0"`) to get bug fixes, rather than caret ranges (e.g. `"^1.1.0"`). This is true in theory but not in practice. The reality is that for most projects, fixes are not "backported" to previous minor releases, and minor releases themselves may include fixes. So for example release `1.2.0` may include one new feature and one fix, so if you stick with `1.1.0` then you will miss out on the fix as there will never be a `1.1.1` once `1.2.0` is already released. This is the _reality_ of most open source packages. +If you're familiar with the theory of semver, you might think that you only need to use tilde ranges (e.g. `"~1.1.0"`) to get bug fixes, rather than caret ranges (e.g. `"^1.1.0"`). +This is true in theory but not in practice. +The reality is that for most projects, fixes are not "backported" to previous minor releases, and minor releases themselves may include fixes. +So for example release `1.2.0` may include one new feature and one fix, so if you stick with `1.1.0` then you will miss out on the fix as there will never be a `1.1.1` once `1.2.0` is already released. +This is the _reality_ of most open source packages. #### Ranges for Libraries -A second reason for using ranges applies to "libraries" that are published as npm packages with the intention that they are used/`require()`'d by other packages. In this case, it is usually a bad idea to pin all your dependencies because it will introduce an unnecessarily narrow range (one release!) and cause most users of your package to bloat their `node_modules` with duplicates. +A second reason for using ranges applies to "libraries" that are published as npm packages with the intention that they are used/`require()`'d by other packages. +In this case, it is usually a bad idea to pin all your dependencies because it will introduce an unnecessarily narrow range (one release!) and cause most users of your package to bloat their `node_modules` with duplicates. -For example, you might have pinned `foobar` to version `1.1.0` and another author pinned his/her `foobar` to dependency to `1.2.2`. Any user of both your packages will end up with npm attempting to install two separate versions of `foobar`, which might not even work. Even if both projects use a service like Renovate to keep their pinned dependencies up to date with the very latest versions, it's still not a good idea - there will always be times when one package has updated/released before the other one and they will be out of sync. e.g. there might be a space of 30 minutes where your package specifies foobar `1.1.0` and the other one specifies `1.1.1` and your joint downstream users end up with a duplicate. +For example, you might have pinned `foobar` to version `1.1.0` and another author pinned his/her `foobar` to dependency to `1.2.2`. +Any user of both your packages will end up with npm attempting to install two separate versions of `foobar`, which might not even work. +Even if both projects use a service like Renovate to keep their pinned dependencies up to date with the very latest versions, it's still not a good idea - there will always be times when one package has updated/released before the other one and they will be out of sync. +e.g. there might be a space of 30 minutes where your package specifies foobar `1.1.0` and the other one specifies `1.1.1` and your joint downstream users end up with a duplicate. ## Why pin dependencies? -You mainly pin versions for certainty, and visibility. When you have a pinned version of each dependency in your `package.json`, you know exactly which version of each dependency is installed at any time. This benefits when upgrading versions as well as when rolling back in case of problems. Note: we'll cover lock files later, don't worry. +You mainly pin versions for certainty, and visibility. +When you have a pinned version of each dependency in your `package.json`, you know exactly which version of each dependency is installed at any time. +This benefits when upgrading versions as well as when rolling back in case of problems. +Note: we'll cover lock files later, don't worry. #### Upgrading pinned versions Let's say that a "faulty" version `1.2.0` of `foobar` is released and it breaks one of your tests. -If you were using default caret semver ranges, then your `master` branch is now "broken" because its `package.json` says that any version 1.x above 1.1.0 is acceptable, and npm will choose the latest (`1.2.0`). You would need to manually check and work out which dependency caused the failure (`foobar` may not have been the only dependency to have "automatically" upgraded since the last time your tests passed) and then you would need to pin the dependency yourself to stop `npm` installing `1.2.0`. +If you were using default caret semver ranges, then your `master` branch is now "broken" because its `package.json` says that any version 1.x above 1.1.0 is acceptable, and npm will choose the latest (`1.2.0`). +You would need to manually check and work out which dependency caused the failure (`foobar` may not have been the only dependency to have "automatically" upgraded since the last time your tests passed) and then you would need to pin the dependency yourself to stop `npm` installing `1.2.0`. -Consider the same situation if instead you were _pinning_ dependency versions. Your `master` would not be broken because it's pinned to `foobar@1.1.0` - instead you'd just have a Pull Request for upgrading to `foobar@1.2.0` which would fail. You'd know not to merge it and can wait for `foobar@1.2.1` or later when it's fixed. Therefore you know exactly what you're running and you know exactly what failed - you have great "visibility". +Consider the same situation if instead you were _pinning_ dependency versions. +Your `master` would not be broken because it's pinned to `foobar@1.1.0` - instead you'd just have a Pull Request for upgrading to `foobar@1.2.0` which would fail. +You'd know not to merge it and can wait for `foobar@1.2.1` or later when it's fixed. +Therefore you know exactly what you're running and you know exactly what failed - you have great "visibility". -Now consider a similar theoretical scenario where `foobar@1.2.0` is faulty but it is _not_ caught by any of your automated tests. This is more common and more dangerous. +Now consider a similar theoretical scenario where `foobar@1.2.0` is faulty but it is _not_ caught by any of your automated tests. +This is more common and more dangerous. -If you were using semver ranges then this new version of `foobar` will likely be deployed to production automatically one day, sometime after which you notice errors and realise you need to fix it. Like before, you need to manually work out which dependency caused it - assuming you guess correctly that it was a new dependency version at fault - and pin it manually by editing `package.json` one dependency at a time. +If you were using semver ranges then this new version of `foobar` will likely be deployed to production automatically one day, sometime after which you notice errors and realise you need to fix it. +Like before, you need to manually work out which dependency caused it - assuming you guess correctly that it was a new dependency version at fault - and pin it manually by editing `package.json` one dependency at a time. -Alternatively, if you were instead pinning `foobar` then you would receive a PR for `foobar@1.2.0` which awaits your approval. So first of all, you can choose to read the release notes and/or visually inspect the branch yourself before merging, hopefully saving you from pushing this faulty code to production. +Alternatively, if you were instead pinning `foobar` then you would receive a PR for `foobar@1.2.0` which awaits your approval. +So first of all, you can choose to read the release notes and/or visually inspect the branch yourself before merging, hopefully saving you from pushing this faulty code to production. -If you did not catch the fault before merging, you are still better off with a pinned version. If you discover something wrong in production, you can easily "roll back" commits in your development environment until you find which rollback fixes the problem. Then you can simply revert that commit (reversing `foobar@1.1.0` -> `foobar@1.2.0`) and push that to `master`. When the next release of `foobar` comes out (e.g. `1.2.1`) you will be prompted with a new PR and hopefully inspect it carefully this time before merge! +If you did not catch the fault before merging, you are still better off with a pinned version. +If you discover something wrong in production, you can easily "roll back" commits in your development environment until you find which rollback fixes the problem. +Then you can simply revert that commit (reversing `foobar@1.1.0` -> `foobar@1.2.0`) and push that to `master`. +When the next release of `foobar` comes out (e.g. `1.2.1`) you will be prompted with a new PR and hopefully inspect it carefully this time before merge! As you can see in the above, pinning dependencies makes your build more consistent and predictable as a developer. #### Downside of pinned dependencies - upgrade "noise" -The one major downside to your development workflow of pinning dependencies is the potential for increased "noise" in your repository. As mentioned above, you can expect to receive Pull Requests whenever there is a new version of your dependencies available. Depending on how many repositories you maintain, and how many dependencies are in each, you may find this default approach to be overwhelming (e.g. waking up to 10 new Pull Requests each day). +The one major downside to your development workflow of pinning dependencies is the potential for increased "noise" in your repository. +As mentioned above, you can expect to receive Pull Requests whenever there is a new version of your dependencies available. +Depending on how many repositories you maintain, and how many dependencies are in each, you may find this default approach to be overwhelming (e.g. waking up to 10 new Pull Requests each day). ## Reducing the "noise" of dependency updates -The increased volume of Pull Requests for upgrading dependencies may be considered by some to be undesirable "noise" in their day. To some extent this is simply a trade-off for having your dependencies pinned and predictable, however there are also ways you can reduce this noise while still gaining the majority of the benefits: +The increased volume of Pull Requests for upgrading dependencies may be considered by some to be undesirable "noise" in their day. +To some extent this is simply a trade-off for having your dependencies pinned and predictable, however there are also ways you can reduce this noise while still gaining the majority of the benefits: ##### Pull Request automerging There are some dependencies that either (a) don't have the potential to break something in production, or (b) are fully tested by your tests. -For example, it's very hard for `eslint` to break anything in production. If your build/tests pass, then you are fine. Therefore you should consider enabling automerge for all lint packages to save yourself the pointless click when you manually approve them each time. In this case you might wake up to 5/10 of your overnight Pull Requests having already merged themselves. +For example, it's very hard for `eslint` to break anything in production. If your build/tests pass, then you are fine. +Therefore you should consider enabling automerge for all lint packages to save yourself the pointless click when you manually approve them each time. +In this case you might wake up to 5/10 of your overnight Pull Requests having already merged themselves. -Another example of a good candidate for automerging might be a database driver like `node-postgres` (`pg` on npm), if you have 100% test coverage of your API. In that case if the `pg` package has a minor or patch update and passes all tests then you may as well merge it automatically if you were not going to do a manual inspection anyway. +Another example of a good candidate for automerging might be a database driver like `node-postgres` (`pg` on npm), if you have 100% test coverage of your API. +In that case if the `pg` package has a minor or patch update and passes all tests then you may as well merge it automatically if you were not going to do a manual inspection anyway. ##### Branch automerging -In the above suggestion of Pull Request automerging, you might still find it annoying if you receive GitHub Notifications for every PR that is created and merged. In that case, you could set `automergeType` to `branch`, which means Renovate will: +In the above suggestion of Pull Request automerging, you might still find it annoying if you receive GitHub Notifications for every PR that is created and merged. +In that case, you could set `automergeType` to `branch`, which means Renovate will: - Create a new branch for testing - Wait until after tests have completed @@ -82,7 +117,8 @@ With this approach, updates will be essentially "silent" - causing no notificati ##### Scheduling -Although it can feel satisfying to receive updates "immediately" when they're available, the reality is that you usually don't _need_ updates so frequently. And worse still, npm package versions that are less than 24 hours [can be unpublished](https://blog.npmjs.org/post/141905368000/changes-to-npms-unpublish-policy), which would really break your build if you've pinned to a version that no longer exists. +Although it can feel satisfying to receive updates "immediately" when they're available, the reality is that you usually don't _need_ updates so frequently. +And worse still, npm package versions that are less than 24 hours [can be unpublished](https://blog.npmjs.org/post/141905368000/changes-to-npms-unpublish-policy), which would really break your build if you've pinned to a version that no longer exists. So to reduce the interruptions of automated dependency updates, consider putting Renovate on a schedule, such as: @@ -91,11 +127,13 @@ So to reduce the interruptions of automated dependency updates, consider putting ##### 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). You can add a package rule in our Renovate configuration to group these together and you'll get just one branch combined even if multiple packages have updates available. +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). +You can add a package rule in our Renovate configuration to group these together and you'll get just one branch combined even if multiple packages have updates available. ## Pinning Dependencies and Lock Files -Since both `yarn` and `npm@5` both support lock files, it's a common question to ask "Why should I pin dependencies if I'm already using a lock file?". It's a good question! +Since both `yarn` and `npm@5` both support lock files, it's a common question to ask "Why should I pin dependencies if I'm already using a lock file?". +It's a good question! ![broken-lockfile](assets/images/broken-lockfile.jpg) @@ -117,19 +155,33 @@ The lock file has only delayed the inevitable problem, and provides much less vi If the `package.json` contains a range, and a new in-range version is released that would break the build, then essentially your `package.json` is in a state of "broken", even if the lock file is still holding things together. -The upside is that the lockfile will hold back `foobar` to `1.1.0` unless it's forced to upgrade, so the break is postponed. The downside is _how_ you will discover the break eventually. +The upside is that the lockfile will hold back `foobar` to `1.1.0` unless it's forced to upgrade, so the break is postponed. +The downside is _how_ you will discover the break eventually. -The easiest case is if for some reason you _need_ to upgrade `foobar`, e.g. for a new feature it contains, so you might run something like `yarn upgrade foobar`. Then you might either discover the break during your development or when you push your new development to CI for testing. In this case, hopefully you'll guess it's `foobar` that broke it and not your own code. +The easiest case is if for some reason you _need_ to upgrade `foobar`, e.g. for a new feature it contains, so you might run something like `yarn upgrade foobar`. +Then you might either discover the break during your development or when you push your new development to CI for testing. +In this case, hopefully you'll guess it's `foobar` that broke it and not your own code. -Alternatively, maybe someone thinks "This lockfile is probably really out of date and might be missing some essential patches" and decides to `yarn upgrade` the whole thing in one go. No doubt the diff will be full of green and red as many direct and indirect dependencies will have changed versions. Then it's pushed to CI for testing, fails, and you have to guess which of the changes caused it until you eventually narrow it down to `foobar`. This might require even manually looking through the lock file diffs line by line. Maybe dep `blahblah` also broke at the same time, to make it even harder. +Alternatively, maybe someone thinks "This lockfile is probably really out of date and might be missing some essential patches" and decides to `yarn upgrade` the whole thing in one go. +No doubt the diff will be full of green and red as many direct and indirect dependencies will have changed versions. +Then it's pushed to CI for testing, fails, and you have to guess which of the changes caused it until you eventually narrow it down to `foobar`. +This might require even manually looking through the lock file diffs line by line. +Maybe dep `blahblah` also broke at the same time, to make it even harder. -By ceding control of direct dependency versions to the lock file, you have lost the ability to _know_ when things are updated. You also may be missing out on really important patches you're not even aware of, because they're "in range" yet locked back to vulnerable or buggy versions in the lock file. +By ceding control of direct dependency versions to the lock file, you have lost the ability to _know_ when things are updated. +You also may be missing out on really important patches you're not even aware of, because they're "in range" yet locked back to vulnerable or buggy versions in the lock file. -Reconsider the same scenario if `foobar` had instead been pinned to `1.1.0` in `package.json` The (broken) upgrade to `1.2.0` would have been explicitly proposed to you via a Renovate PR, you would see the break, and know that the version is bad. Meanwhile you could be upgrading all the other essential fixes of other dependencies without worrying about `foobar`. You could even be running `yarn upgrade` regularly to be getting _indirect_ package updates in the lockfile and seeing if everything still passes. +Reconsider the same scenario if `foobar` had instead been pinned to `1.1.0` in `package.json`. +The (broken) upgrade to `1.2.0` would have been explicitly proposed to you via a Renovate PR, you would see the break, and know that the version is bad. +Meanwhile you could be upgrading all the other essential fixes of other dependencies without worrying about `foobar`. +You could even be running `yarn upgrade` regularly to be getting _indirect_ package updates in the lockfile and seeing if everything still passes. -Therefore, the lock file does not solve the same semver problems that pinning solves - but it compliments it. For this reason our usual recommendation using a lock file regardless of whether you pin dependencies or not, and pinning even if you have a lock file. +Therefore, the lock file does not solve the same semver problems that pinning solves - but it compliments it. +For this reason our usual recommendation using a lock file regardless of whether you pin dependencies or not, and pinning even if you have a lock file. -Don't forget though that our motto is "Flexible, so you don't need to be", so go ahead and configure however you want. Also, we're open to ideas for how to make lock file updates more "visible" too. e.g. are you interested in a Renovate feature where you get a lockfile-only PR any time a direct dependency gets an in-range update? +Don't forget though that our motto is "Flexible, so you don't need to be", so go ahead and configure however you want. +Also, we're open to ideas for how to make lock file updates more "visible" too. +e.g. are you interested in a Renovate feature where you get a lockfile-only PR any time a direct dependency gets an in-range update? ## What about indirect/sub-dependencies? @@ -139,11 +191,19 @@ A good argument made by [@LinusU](https://github.com/LinusU) is: > Because of this, I personally think that pinning dependencies just creates a false sense of security, and that using a lock file is superior in every way. -It is true that pinning applies only to direct dependencies, and "indirect" dependencies typically count for a lot more in total in your lockfile than direct. e.g. those 30 ones that Express relies on. +It is true that pinning applies only to direct dependencies, and "indirect" dependencies typically count for a lot more in total in your lockfile than direct. +e.g. those 30 ones that Express relies on. -Does pinning give you "increased" security? Undeniably. The question is not whether it does, but whether that increased security comes at a cost (e.g. "noise"). But Linus also points out that a _false_ sense of security is a cost too. +Does pinning give you "increased" security? +Undeniably. +The question is not whether it does, but whether that increased security comes at a cost (e.g. "noise"). +But Linus also points out that a _false_ sense of security is a cost too. -Don't forget that there is some form of transitive trust too. You need to pick your direct dependencies carefully, and which versions of them you use. Hopefully in doing that you pick dependencies partly for how well _they_ look after their own dependencies and versions (e.g. do they have good enough test coverage, do they use something like Renovate to keep updated, etc?). So the reality is that even if 90% of the entries in your lock file are indirect dependencies, those are ones you have somewhat "delegated" responsibility for to your dependencies. e.g. I'd hope that Express are even better at watching their deps for breaks than I am, to use the example above. +Don't forget that there is some form of transitive trust too. +You need to pick your direct dependencies carefully, and which versions of them you use. +Hopefully in doing that you pick dependencies partly for how well _they_ look after their own dependencies and versions (e.g. do they have good enough test coverage, do they use something like Renovate to keep updated, etc?). +So the reality is that even if 90% of the entries in your lock file are indirect dependencies, those are ones you have somewhat "delegated" responsibility for to your dependencies. +e.g. I'd hope that Express are even better at watching their deps for breaks than I am, to use the example above. But certainly "does it give a false sense of security" is not a question we can really answer quantifiably. @@ -156,10 +216,12 @@ We recommend: 3. Node.js-only libraries can consider pinning all dependencies, because application size/duplicate dependencies are not as much a concern in Node.js compared to the browser. Of course, don't do that if your library is a micro one likely to be consumed in disk-sensitive environments. 4. Use a lock file. -As noted earlier, when you pin dependencies then you will see an increase in the raw volume of dependency updates, compared to if you use ranges. If/when this starts bothering you, add Renovate rules to reduce the volume, such as scheduling updates, grouping them, or automerging "safe" ones. +As noted earlier, when you pin dependencies then you will see an increase in the raw volume of dependency updates, compared to if you use ranges. +If/when this starts bothering you, add Renovate rules to reduce the volume, such as scheduling updates, grouping them, or automerging "safe" ones. ## References -This is a "living" document and we plan to update it whenever we think of something new or someone makes a valid point we've missed or misunderstood. [GitHub Location](https://github.com/renovatebot/renovate/blob/master/website/docs/dependency-pinning.md) +This is a "living" document and we plan to update it whenever we think of something new or someone makes a valid point we've missed or misunderstood. +[GitHub Location](https://github.com/renovatebot/renovate/blob/master/website/docs/dependency-pinning.md) Updated 2018-01-19 after [excellent feedback on lockfiles](https://github.com/commitizen/cz-conventional-changelog-default-export/pull/4#issuecomment-358038966) by [@LinusU](https://github.com/LinusU) diff --git a/docs/usage/docker.md b/docs/usage/docker.md index 2161fe1b3..dd1a2ab5f 100644 --- a/docs/usage/docker.md +++ b/docs/usage/docker.md @@ -21,13 +21,18 @@ Renovate supports upgrading dependencies in various types of Docker definition f ## 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. +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`. +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 `versioning` 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 package rule: +If this behaviour does not suit a particular package you have, Renovate allows you to customize the `versioning` 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 package rule: ```json { @@ -41,7 +46,8 @@ If this behaviour does not suit a particular package you have, Renovate allows y } ``` -Another example is the official `python` image, which follows `pep440` versioning. You can configure that with another package rule: +Another example is the official `python` image, which follows `pep440` versioning. +You can configure that with another package rule: ```json { @@ -55,43 +61,60 @@ Another example is the official `python` image, which follows `pep440` versionin } ``` -If traditional versioning doesn't work, consider using Renovate's built-in `loose` `versioning`. It essentially just does a best effort sort of versions, regardless of whether they contain letters or digits. +If traditional versioning doesn't work, consider using Renovate's built-in `loose` `versioning`. +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 versionings, and which `loose` sorts incorrectly, you could see if the `regex` `versioning` 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 `versioning` for documentation/examples of `regex` versioning in action. +Finally, if you use a Docker image that follows a versioning approach not captured by one of our existing versionings, and which `loose` sorts incorrectly, you could see if the `regex` `versioning` 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 `versioning` 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: pin to digests 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. +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. -Using a Docker digest as the image's primary identifier instead of Docker tag will achieve immutability but as a human it's quite inconvenient to deal with strings like `FROM node@sha256:552348163f074034ae75643c01e0ba301af936a898d778bb4fc16062917d0430`. The good news is that, as a human you no longer need to manually update such digests once you have Renovate on the job. +Using a Docker digest as the image's primary identifier instead of Docker tag will achieve immutability but as a human it's quite inconvenient to deal with strings like `FROM node@sha256:552348163f074034ae75643c01e0ba301af936a898d778bb4fc16062917d0430`. +The good news is that, as a human you no longer need to manually update such digests once you have Renovate on the job. -Also, to retain some human-friendliness, Renovate will actually retain the tag in the `FROM` line too, e.g. `FROM node:8@sha256:552348163f074034ae75643c01e0ba301af936a898d778bb4fc16062917d0430`. Read on to see how Renovate keeps it up-to-date. +Also, to retain some human-friendliness, Renovate will actually retain the tag in the `FROM` line too, e.g. `FROM node:8@sha256:552348163f074034ae75643c01e0ba301af936a898d778bb4fc16062917d0430`. +Read on to see how Renovate keeps it up-to-date. ## Digest Updating If you have followed our advice to go from tags like `node:8` to `node:8@sha256:552348163f074034ae75643c01e0ba301af936a898d778bb4fc16062917d0430`, then you are likely to receive Renovate PRs whenever the `node:8` image is updated on Docker Hub. -Previously this would have been "invisible" to you - one day you pull code that represents `node:8.9.0` and the next day you get `node:8.9.1`. But you can never be sure, especially as Docker caches. Perhaps some of your colleagues or worst still your build machine are stuck on an older version with a security vulnerability. +Previously this would have been "invisible" to you - one day you pull code that represents `node:8.9.0` and the next day you get `node:8.9.1`. +But you can never be sure, especially as Docker caches. +Perhaps some of your colleagues or worst still your build machine are stuck on an older version with a security vulnerability. -Instead, you will now receive these updates via Pull Requests, or perhaps committed directly to your repository if you enable branch automerge for convenience. This ensures everyone on the team gets the latest versions and is in sync. +Instead, you will now receive these updates via Pull Requests, or perhaps committed directly to your repository if you enable branch automerge for convenience. +This ensures everyone on the team gets the latest versions and is in sync. ## Version Upgrading -Renovate also supports _upgrading_ versions in Docker tags, e.g. from `node:8.9.0` to `node:8.9.1` or `node:8.9` to `node:8.10`. If your tags looks like a version, Renovate will upgrade it like a version. +Renovate also supports _upgrading_ versions in Docker tags, e.g. from `node:8.9.0` to `node:8.9.1` or `node:8.9` to `node:8.10`. +If your tags looks like a version, Renovate will upgrade it like a version. Thanks to this, you may wish to change the way you tag your image dependencies to be more specific, e.g. change from `node:8` to `node:8.9.1` so that every Renovate PR will be more human friendly, e.g. you can know that you are getting a PR because `node` upgraded from `8.9.1` to `8.9.2` and not because `8.9.1` somehow changed. -Currently, Renovate will upgrade minor/patch versions (e.g. from `8.9.0` to `8.9.1`) by default, but not upgrade major versions. If you wish to enable major versions then add the preset `docker:enableMajor` to your `extends` array in your `renovate.json`. +Currently, Renovate will upgrade minor/patch versions (e.g. from `8.9.0` to `8.9.1`) by default, but not upgrade major versions. +If you wish to enable major versions then add the preset `docker:enableMajor` to your `extends` array in your `renovate.json`. -Renovate has a some Docker-specific intelligence when it comes to versions. For example: +Renovate has a some Docker-specific intelligence when it comes to versions. +For example: ## Configuring/Disabling -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 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: +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": { @@ -128,7 +151,8 @@ Add `"default:pinDigestsDisabled"` to your `extends` array. ##### Automerge digest updates -Add `"default:automergeDigest"` to your `extends` array. Also add `"default:automergeBranchPush"` if you wish for these to be committed directly to your base branch without raising a PR first. +Add `"default:automergeDigest"` to your `extends` array. +Also add `"default:automergeBranchPush"` if you wish for these to be committed directly to your base branch without raising a PR first. ##### Registry authentication @@ -146,7 +170,8 @@ module.exports = { }; ``` -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: +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 = { diff --git a/docs/usage/faq.md b/docs/usage/faq.md index f26053edb..5c2cbf780 100644 --- a/docs/usage/faq.md +++ b/docs/usage/faq.md @@ -9,8 +9,7 @@ description: Frequently Asked Questions for Renovate Configuration Renovate will: -- Look for configuration options in a configuration file (e.g. `renovate.json`) and in each - `package.json` file +- 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 - Use separate branches/PR for each dependency - Use separate branches for each _major_ version of each dependency @@ -23,10 +22,8 @@ Renovate will: ### Use an alternative branch for 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). +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). ``` { @@ -42,16 +39,14 @@ See the dedicated [Private npm module support](/private-modules/) page. ### 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. +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. -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. +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. 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.: +This can be overridden in global config. +Finally, it can be overridden on a per-repository basis too, e.g.: ``` "timezone": "America/Los_Angeles", @@ -60,10 +55,8 @@ overridden on a per-repository basis too, e.g.: The timezone must be one of the valid [IANA time zones](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". +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". Example scheduling: @@ -75,8 +68,7 @@ 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`. +This scheduling feature can be particularly 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: @@ -89,8 +81,8 @@ 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. Multiple entries in the array means "or". +Note that schedule must be in the form of an array, even if only one schedule is present. +Multiple entries in the array means "or". ### Disable renovate for certain dependency types @@ -98,8 +90,7 @@ Define a packageRules entry which has the dependency type(s) in `depTypeList` an ### Use a single branch/PR for all dependency upgrades -Add a configuration for configuration option `groupName` set to value `"all"`, -at the top level of your `renovate.json` or `package.json`. +Add a configuration for configuration option `groupName` set to value `"all"`, at the top level of your `renovate.json` or `package.json`. ### Use separate branches per dependency, but not one per major release @@ -111,12 +102,13 @@ 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. +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. ### 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 configuration option `prCreation` to `"status-success"`. +Failing branches will never get a Pull Request created until they eventually pass. ### Wait until tests have passed before creating a PR, but create the PR even if they fail @@ -150,8 +142,7 @@ e.g. ### Apply a rule, but only for packages starting with `abc` -Do the same as above, but instead of using `packageNames`, use `packagePatterns` -and a regex. e.g. +Do the same as above, but instead of using `packageNames`, use `packagePatterns` and a regex. e.g. ``` "packageRules": [ @@ -177,8 +168,7 @@ 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: +Set the `branchName`, `commitMessage`, `prTitle` or `prBody` configuration options: ``` "branchName": "vroom/{{depName}}-{{newMajor}}.x", @@ -188,26 +178,21 @@ options: ### Automatically merge passing Pull Requests -Set configuration option `autoMerge` to `true`. Nest it inside config objects `patch` or `minor` if you want it to apply to certain types only. +Set 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 behaviour 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 behaviour 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`. -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`. +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`. -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: +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: - Update patch updates daily and automerge if they pass tests - Update minor and major updates weekly -The result of this would hopefully be that you barely notice Renovate during the -week while still getting the benefits of patch updates. +The result of this would hopefully be that you barely notice Renovate during the week, while still getting the benefits of patch updates. diff --git a/docs/usage/golang.md b/docs/usage/golang.md index cb5797473..ff147053e 100644 --- a/docs/usage/golang.md +++ b/docs/usage/golang.md @@ -21,18 +21,22 @@ Renovate supports upgrading dependencies in `go.mod` files and their accompanyin ## Enabling Go Modules Updating -Go Modules updating is on by default in Renovate Bot. To install Renovate Bot itself, either enable the [Renovate App](https://github.com/apps/renovate) on GitHub, or check out [Renovate OSS](https://github.com/renovatebot/renovate) for self-hosted. +Go Modules updating is on by default in Renovate Bot. +To install Renovate Bot itself, either enable the [Renovate App](https://github.com/apps/renovate) on GitHub, or check out [Renovate OSS](https://github.com/renovatebot/renovate) for self-hosted. ## Technical Details #### Module Tidying -Go Modules tidying is not enabled by default, and so is opt-in via the [`postUpdateOptions`](https://docs.renovatebot.com/configuration-options/#postupdateoptions) config option. The reason for this is that a `go mod tidy` command may make changes to `go.mod` and `go.sum` that are completely unrelated to the updated module(s) in the PR, and so may be confusing to some users. +Go Modules tidying is not enabled by default, and so is opt-in via the [`postUpdateOptions`](https://docs.renovatebot.com/configuration-options/#postupdateoptions) config option. +The reason for this is that a `go mod tidy` command may make changes to `go.mod` and `go.sum` that are completely unrelated to the updated module(s) in the PR, and so may be confusing to some users. #### Module Vendoring -Vendoring of Go Modules is done automatically if `vendor/modules.txt` is present. Renovate will commit all files changed within the `vendor/` folder. +Vendoring of Go Modules is done automatically if `vendor/modules.txt` is present. +Renovate will commit all files changed within the `vendor/` folder. #### Go binary version -Currently, Renovate will try to keep up with the very latest version of `go`, and it is not configurable. It is planned though to support a configurable version of `go` per-repository soon. +Currently, Renovate will try to keep up with the very latest version of `go`, and it is not configurable. +It is planned though to support a configurable version of `go` per-repository soon. diff --git a/docs/usage/install-github-app.md b/docs/usage/install-github-app.md index 4122de271..ba7babd90 100644 --- a/docs/usage/install-github-app.md +++ b/docs/usage/install-github-app.md @@ -15,6 +15,7 @@ The only choice you need to make is whether to run Renovate on: ![Github App repositories](assets/images/github-app-choose-repos.png) -Renovate will silently ignore any repositories that don't have known package files, as well as any forks, so it's OK to install for all, however most people choose to select which repositories to include. Unfortunately GitHub doesn't yet offer a "select all except X,Y,Z" so instead you need to individually select all that you want if you don't choose the install into all repositories option. +Renovate will silently ignore any repositories that don't have known package files, as well as any forks, so it's OK to install for all, however most people choose to select which repositories to include. +Unfortunately GitHub doesn't yet offer a "select all except X,Y,Z" so instead you need to individually select all that you want if you don't choose the install into all repositories option. Once you're done selecting repositories for Renovate to run on, click the green Install button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. diff --git a/docs/usage/install-gitlab-app.md b/docs/usage/install-gitlab-app.md index 822df5ddf..94ad7b34a 100644 --- a/docs/usage/install-gitlab-app.md +++ b/docs/usage/install-gitlab-app.md @@ -7,7 +7,8 @@ description: How to install the Renovate GitLab App ### Overview -WhiteSource Renovate runs as the user [@renovate-bot](https://gitlab.com/renovate-bot) on [gitlab.com](https://gitlab.com). To enable the hosted WhiteSource Renovate App on your GitLab.com project, you can do any of the following: +WhiteSource Renovate runs as the user [@renovate-bot](https://gitlab.com/renovate-bot) on [gitlab.com](https://gitlab.com). +To enable the hosted WhiteSource Renovate App on your GitLab.com project, you can do any of the following: - Add [@renovate-bot](https://gitlab.com/renovate-bot) as a Developer directly to each project, or - Add [@renovate-bot](https://gitlab.com/renovate-bot) to a team that has Developer access to the project @@ -51,17 +52,20 @@ WhiteSource Renovate is free for both public and private repositories, so no pay Renovate needs a Personal Access Token configured in order to be able to fetch release notes from github.com repositories. -Although open source repositories are public, GitHub's API applies strict rate limiting to unauthenticated requests, so Renovate will not attempt to fetch unless it can detect a token. To fetch without a token would risk getting requests denied, which could in turn result in confusing inconsistencies in Pull or Merge Requests, including bodies which flip flop between release notes and none. +Although open source repositories are public, GitHub's API applies strict rate limiting to unauthenticated requests, so Renovate will not attempt to fetch unless it can detect a token. +To fetch without a token would risk getting requests denied, which could in turn result in confusing inconsistencies in Pull or Merge Requests, including bodies which flip flop between release notes and none. #### Generate a Personal Access Token Any read-only, public-only Personal Access Token for github.com will work. -While logged in, go to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new). Add a note like "renovate release notes" and then generate the token - no further permissions are required. +While logged in, go to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new). +Add a note like "renovate release notes" and then generate the token - no further permissions are required. #### Configuring the Token -Visit [https://renovatebot.com/encrypt](https://renovatebot.com/encrypt), paste your token into "Raw value", and then click "Encrypt". Configure the resulting value into your renovate config or preset like this: +Visit [https://renovatebot.com/encrypt](https://renovatebot.com/encrypt), paste your token into "Raw value", and then click "Encrypt". +Configure the resulting value into your renovate config or preset like this: ```json { @@ -95,11 +99,13 @@ User tokens are passed with API calls to Renovate's backend to verify identity b ##### Installing for all projects -Unlike on GitHub, it is not possible to have the option to install Renovate on "all repositories now and in the future". To do this would require Renovate to store the user's token and this is not something we want to do. +Unlike on GitHub, it is not possible to have the option to install Renovate on "all repositories now and in the future". +To do this would require Renovate to store the user's token and this is not something we want to do. ##### Detecting new projects -Currently there is no detection mechanism in the backend scheduler to determine when Renovate has been added to a new project, so the onboarding MR won't appear instantly. Instead, the new project should be picked up during hourly scheduled runs. +Currently there is no detection mechanism in the backend scheduler to determine when Renovate has been added to a new project, so the onboarding MR won't appear instantly. +Instead, the new project should be picked up during hourly scheduled runs. ##### Auto merging pull requests diff --git a/docs/usage/java.md b/docs/usage/java.md index ea54cf7ce..4c6b2d93e 100644 --- a/docs/usage/java.md +++ b/docs/usage/java.md @@ -5,7 +5,8 @@ description: Java versions support in Renovate # Java Dependency Updates -Renovate can update the version used in Gradle and Maven projects. This includes libraries and plugins. +Renovate can update the version used in Gradle and Maven projects. +This includes libraries and plugins. ## Gradle @@ -23,7 +24,8 @@ Renovate does not support: ### How It Works -Renovate uses a plugin to search and extract versions from projects. They are then looked up using Maven datasources and patched into PRs the usual way. +Renovate uses a plugin to search and extract versions from projects. +They are then looked up using Maven datasources and patched into PRs the usual way. ## Maven diff --git a/docs/usage/modules/datasource.md b/docs/usage/modules/datasource.md index f5fa68679..4a40a8052 100644 --- a/docs/usage/modules/datasource.md +++ b/docs/usage/modules/datasource.md @@ -1,6 +1,7 @@ # Datasources -Once Renovate's Managers are done scanning files and extracting dependencies, they will assign a `datasource` to each so that Renovate then knows how to search for new versions. You do not need to ever configure/override Datasources directly, but you may use them in `packageRules` to configure other aspects of Renovate's behavior, e.g. +Once Renovate's Managers are done scanning files and extracting dependencies, they will assign a `datasource` to each so that Renovate then knows how to search for new versions. +You do not need to ever configure/override Datasources directly, but you may use them in `packageRules` to configure other aspects of Renovate's behavior, e.g. ```json { diff --git a/docs/usage/modules/manager.md b/docs/usage/modules/manager.md index f611a1088..0fa0659ff 100644 --- a/docs/usage/modules/manager.md +++ b/docs/usage/modules/manager.md @@ -1,6 +1,7 @@ # Managers -Renovate is based around the concept of "package managers", or "managers" for short. These range from traditional package managers like npm, Bundler and Composer through to less traditional concepts like CircleCI or Travis config files. +Renovate is based around the concept of "package managers", or "managers" for short. +These range from traditional package managers like npm, Bundler and Composer through to less traditional concepts like CircleCI or Travis config files. The goal of Renovate is to detect and maintain all third party dependencies in your repositories, through the use of managers. @@ -13,11 +14,13 @@ The goal of Renovate is to detect and maintain all third party dependencies in y ### File Matching -Most managers have a default `fileMatch` array. `fileMatch` is an array of Regular Expression strings used to match against the repository file list. +Most managers have a default `fileMatch` array. +`fileMatch` is an array of Regular Expression strings used to match against the repository file list. #### Managers with no default fileMatch -Some managers have no default `fileMatch`, because they have no file naming convention that would let Renovate intelligently filter them. In such a case, the manager will be effectively disabled until you configure a `fileMatch` value, e.g. like the following: +Some managers have no default `fileMatch`, because they have no file naming convention that would let Renovate intelligently filter them. +In such a case, the manager will be effectively disabled until you configure a `fileMatch` value, e.g. like the following: ```json { @@ -41,7 +44,10 @@ If the default `fileMatch` value for a manager does not match against one of you #### Ignoring files that match the default fileMatch -Note: Renovate will _extend_ the existing `fileMatch`, meaning you don't need to include the default values like `Dockerfile` in your own array. In other words, the values are "additive". If a manager matches a file that you _don't_ want it to, ignore it using the `ignorePaths` configuration option. Also, if you ever find that Renovate is _not_ matching a file name that you're certain it should, be sure to check that you your preset config isn't the cause of it. The `config:base` preset ignores common test and example directory names, for example. +Note: Renovate will _extend_ the existing `fileMatch`, meaning you don't need to include the default values like `Dockerfile` in your own array. +In other words, the values are "additive". If a manager matches a file that you _don't_ want it to, ignore it using the `ignorePaths` configuration option. +Also, if you ever find that Renovate is _not_ matching a file name that you're certain it should, be sure to check that you your preset config isn't the cause of it. +The `config:base` preset ignores common test and example directory names, for example. ### Enabling and Disabling Managers diff --git a/docs/usage/modules/versioning.md b/docs/usage/modules/versioning.md index 461823315..eb6799062 100644 --- a/docs/usage/modules/versioning.md +++ b/docs/usage/modules/versioning.md @@ -1,10 +1,12 @@ # Versioning -Once Managers have extracted dependencies, and Datasources have located available versions, then Renovate makes use of "Versioning" schemes to perform sorting and filtering of results. This is necessary because different managers use different types of numbering/versioning, e.g. `1.0.0-beta.1` in `npm` and `1.0.0b1` in Python. +Once Managers have extracted dependencies, and Datasources have located available versions, then Renovate makes use of "Versioning" schemes to perform sorting and filtering of results. +This is necessary because different managers use different types of numbering/versioning, e.g. `1.0.0-beta.1` in `npm` and `1.0.0b1` in Python. ## Configuring Versioning -There are times when you may need to manually configure/override the `versioning` value for a particular dependency. You generally won't have a need for this in ecosystems with strict versioning enforcement like `npm`, but you might often need it for ecosystems like Docker where versioning is barely a "convention". e.g. +There are times when you may need to manually configure/override the `versioning` value for a particular dependency. +You generally won't have a need for this in ecosystems with strict versioning enforcement like `npm`, but you might often need it for ecosystems like Docker where versioning is barely a "convention". e.g. ```json { diff --git a/docs/usage/noise-reduction.md b/docs/usage/noise-reduction.md index d76671b21..a8e738dae 100644 --- a/docs/usage/noise-reduction.md +++ b/docs/usage/noise-reduction.md @@ -5,17 +5,27 @@ description: How to reduce the "noise" associated with module updates # Noise Reduction -Generally, the first reaction people have to automated dependency updates like Renovate is "oh great/feel the power of automation". The next reaction a few days or weeks later is often "this is getting overwhelming". Indeed, if you leave Renovate on its default settings of raising a PR every single time any dependency receives any update.. you will get a lot of PRs and related notifications. This document will give you some ideas of how to reduce the amount of "noise" in your repository and the Pros/Cons of each. +Generally, the first reaction people have to automated dependency updates like Renovate is "oh great/feel the power of automation". +The next reaction a few days or weeks later is often "this is getting overwhelming". +Indeed, if you leave Renovate on its default settings of raising a PR every single time any dependency receives any update.. you will get a lot of PRs and related notifications. +This document will give you some ideas of how to reduce the amount of "noise" in your repository and the Pros/Cons of each. -Of course, please keep in mind that people's definitions of "noise" may differ. For some people, it's noisy only if they get a notification or email from GitHub. For others, too many commits in their `master` branch may be "noise". In other words, your mileage may vary. Please contact the author if you have any ideas on this topic! +Of course, please keep in mind that people's definitions of "noise" may differ. +For some people, it's noisy only if they get a notification or email from GitHub. +For others, too many commits in their `master` branch may be "noise". +In other words, your mileage may vary. +Please contact the author if you have any ideas on this topic! ## Package Grouping To reduce noise, you can reduce the number of updates in total, and a good way to do that is via intelligent grouping of related packages. -As an example, our default `":app"` and `":library"` [presets](/config-presets/) include the rule `"group:monorepos"`, which means that "sibling" packages from known monorepos will always be grouped into the same branch/PR by renovate. For example, all `@angular/*` packages that are updated at the same time will be raised in a "Renovate angular monorepo packages" PR. And every package in the React monorepo will be grouped together in a React monorepo PR too. +As an example, our default `":app"` and `":library"` [presets](/config-presets/) include the rule `"group:monorepos"`, which means that "sibling" packages from known monorepos will always be grouped into the same branch/PR by renovate. +For example, all `@angular/*` packages that are updated at the same time will be raised in a "Renovate angular monorepo packages" PR. +And every package in the React monorepo will be grouped together in a React monorepo PR too. -You may wish to take this further, for example you might want to group together all packages related to `eslint`, even if they come from separate repositories/authors. In that case you might add config like this: +You may wish to take this further, for example you might want to group together all packages related to `eslint`, even if they come from separate repositories/authors. +In that case you might add config like this: ```json "packageRules": [ @@ -28,17 +38,27 @@ You may wish to take this further, for example you might want to group together By setting `packagePatterns` to "eslint", it means that any package with ESLint anywhere in its name will be grouped into a `renovate/eslint` branch and related PR. -**Caution**: Any time you group dependencies together, you naturally increase the chance that the branch will have an error ("break" your build). When you have more than one package upgrade in a PR, it's going to take you longer to work out which one broke than if they were all in separate PRs. Also, you will be held up upgrading all those dependencies until they all pass. If you weren't grouping, then you could keep upgrading all dependencies except the one that fails, instead of being held up. You will also have less flexibility about what to do when one or more in the group have a major upgrade and may break the others. +**Caution**: Any time you group dependencies together, you naturally increase the chance that the branch will have an error ("break" your build). +When you have more than one package upgrade in a PR, it's going to take you longer to work out which one broke than if they were all in separate PRs. +Also, you will be held up upgrading all those dependencies until they all pass. +If you weren't grouping, then you could keep upgrading all dependencies except the one that fails, instead of being held up. +You will also have less flexibility about what to do when one or more in the group have a major upgrade and may break the others. ## Scheduling Renovate -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. Therefore, you can expect to get PRs at any time of the day, i.e. soon after versions are published to npm. +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. +Therefore, you can expect to get PRs at any time of the day, i.e. soon after versions are published to npm. -Receiving PRs at any hour can increase the feeling of being "overwhelmed" by updates and possibly interrupt your flow during working hours, so many Renovate users also consider reducing Renovate's schedule to be outside their normal working hours, for example weeknights and weekends. This is achievable by configuring `schedule` in your Renovate config and optionally `timezone` (Renovate's default time zone is UTC, so you may find it easier to write schedules if you override `timezone` to your local one). +Receiving PRs at any hour can increase the feeling of being "overwhelmed" by updates and possibly interrupt your flow during working hours, so many Renovate users also consider reducing Renovate's schedule to be outside their normal working hours, for example weeknights and weekends. +This is achievable by configuring `schedule` in your Renovate config and optionally `timezone` (Renovate's default time zone is UTC, so you may find it easier to write schedules if you override `timezone` to your local one). -Another example of adjusting schedules to fit with your workflow might be if your company performs releases every Monday. In that case, you might schedule Renovate to run every Tuesday after midnight to pick up new dependency updates that you can test over the following week before the next release. +Another example of adjusting schedules to fit with your workflow might be if your company performs releases every Monday. +In that case, you might schedule Renovate to run every Tuesday after midnight to pick up new dependency updates that you can test over the following week before the next release. -**Caution**: You need to make sure you leave yourself and Renovate enough time in a week to actually get all your updating and merging done. There are multiple reasons why Renovate may need to "recreate" PRs after you merge another: +**Caution**: You need to make sure you leave yourself and Renovate enough time in a week to actually get all your updating and merging done. +There are multiple reasons why Renovate may need to "recreate" PRs after you merge another: 1. Conflict with `package.json` (sometimes) 2. Conflict with lock files (often) @@ -48,9 +68,12 @@ Any of the above reasons can lead to a Renovate branch being considered "stale" #### Selective scheduling -Don't think that you need to apply blanket rules to scheduling. Remember that Renovate configuration is highly flexible so you can configure `automerge` anywhere from globally (entire repo) right down to a package/upgrade type level (e.g. you could even configure a nonsensical rule that patch updates of `jquery` are for Mondays only). +Don't think that you need to apply blanket rules to scheduling. +Remember that Renovate configuration is highly flexible so you can configure `automerge` anywhere from globally (entire repo) right down to a package/upgrade type level (e.g. you could even configure a nonsensical rule that patch updates of `jquery` are for Mondays only). -Remember earlier our example of grouping all `eslint`? If you think about it.. updates to `eslint` rules don't exactly need to be applied in real time! You don't want to get too far behind, so how about we update `eslint` packages only once a month? +Remember earlier our example of grouping all `eslint`? +If you think about it.. updates to `eslint` rules don't exactly need to be applied in real time! +You don't want to get too far behind, so how about we update `eslint` packages only once a month? ```json "packageRules": [ @@ -74,21 +97,28 @@ Or perhaps at least weekly: ] ``` -If you're wondering what is supported and not, under the hood, the schedule is parsed using [later.js](https://bunkat.github.io/later/) using the `later.parse.text(scheduleString)` API. [This page](https://bunkat.github.io/later/parsers.html#text) explains the supported syntax or you can experiment on the [RunKit playground](https://npm.runkit.com/later). +If you're wondering what is supported and not, under the hood, the schedule is parsed using [later.js](https://bunkat.github.io/later/) using the `later.parse.text(scheduleString)` API. +[This page](https://bunkat.github.io/later/parsers.html#text) explains the supported syntax or you can experiment on the [RunKit playground](https://npm.runkit.com/later). ## Automerging -Automerging is a Renovate feature that can save you a lot of time/noise directly, while also benefiting grouping and scheduling. In short: it means that Renovate can merge PRs or even branches itself if they pass your tests. +Automerging is a Renovate feature that can save you a lot of time/noise directly, while also benefiting grouping and scheduling. +In short: it means that Renovate can merge PRs or even branches itself if they pass your tests. -It is recommended that you enable automerge for any types of dependency updates where you would just click Merge anyway. We all know that there are some types of updates that we (nearly) always verify manually before merging, and plenty of others that we don't bother looking at unless tests fail. Every time you click Merge on a Renovate PR without manually testing it, you should consider if you can enable automerge and save yourself the time in future. +It is recommended that you enable automerge for any types of dependency updates where you would just click Merge anyway. +We all know that there are some types of updates that we (nearly) always verify manually before merging, and plenty of others that we don't bother looking at unless tests fail. +Every time you click Merge on a Renovate PR without manually testing it, you should consider if you can enable automerge and save yourself the time in future. Automerge works particularly well for `devDependencies` and for production `dependencies` that have great test coverage. -For example, if you have `jest` or `mocha` as a dependency, and it has an upgrade with passing tests.. automerge them! If you have a linter like `eslint` or `tslint` and its update passes.. automerge them! If you have an API with 100% test coverage and `express` is updated.. automerge it! +For example, if you have `jest` or `mocha` as a dependency, and it has an upgrade with passing tests.. automerge them! +If you have a linter like `eslint` or `tslint` and its update passes.. automerge them! +If you have an API with 100% test coverage and `express` is updated.. automerge it! #### Branch automerging -Those of you familiar with GitHub might note that even if you automerge PRs, you are still going to get notifications (noise) anyway - one when the PR is created and another when it is merged. For this reason we recommend you consider setting `automergeType=branch` which will mean: +Those of you familiar with GitHub might note that even if you automerge PRs, you are still going to get notifications (noise) anyway - one when the PR is created and another when it is merged. +For this reason we recommend you consider setting `automergeType=branch` which will mean: - Renovate first creates a branch and no PR - If tests pass, Renovate pushes a commit directly to `master` without PR @@ -98,7 +128,8 @@ The result is that passing updates are essentially "silent" - the only sign of t #### Automerging and scheduling -Automerging is particularly beneficial if you have configured a schedule, because Renovate on its own may be able to automerge the majority of your updates. And this is especially so if your repository needs rebasing, e.g. because you use lock files. e.g. let's say you have dependencies `abc` and `xyz` with upgrades, and you use a `yarn.lock` file. +Automerging is particularly beneficial if you have configured a schedule, because Renovate on its own may be able to automerge the majority of your updates. +And this is especially so if your repository needs rebasing, e.g. because you use lock files. e.g. let's say you have dependencies `abc` and `xyz` with upgrades, and you use a `yarn.lock` file. - At the start of the schedule, `Renovate` will create branches for `abc` and `xyz` upgrades, including `yarn.lock` updates - After `abc` passes tests, `Renovate` will automerge it to `master` @@ -123,11 +154,13 @@ Remember our running `eslint` example? Let's automerge it if all the linting upd ] ``` -Have you come up with a rule that you think others would benefit from? How about a PR back to [renovate-config](https://github.com/singapore/renovate-config) with the above rule named `":automergeEslintWeekly"` ? +Have you come up with a rule that you think others would benefit from? +How about a PR back to [renovate-config](https://github.com/singapore/renovate-config) with the above rule named `":automergeEslintWeekly"` ? ## Lock file considerations -Using lock files greatly increases the chance that merging one PR will result in a second PR becoming conflicted with `master`. The table below highlights different noise reduction strategies and their effect on pull request and potential lock file conflicts: +Using lock files greatly increases the chance that merging one PR will result in a second PR becoming conflicted with `master`. +The table below highlights different noise reduction strategies and their effect on pull request and potential lock file conflicts: | Action | Effect on pull requests | Chance of lock file conflicts | | ------------------------------------ | ------------------------ | ----------------------------- | @@ -137,9 +170,11 @@ Using lock files greatly increases the chance that merging one PR will result in ## The Future of Noise Reduction -First of all, if you ever have any ideas about how to make Renovate less noisy, please raise or comment on issues in the [main repository](https://github.com/renovatebot/renovate). Our philosophy is: +First of all, if you ever have any ideas about how to make Renovate less noisy, please raise or comment on issues in the [main repository](https://github.com/renovatebot/renovate). +Our philosophy is: 1. Nearly everyone should probably use Renovate-like dependency update automation 2. Over time, you should "see" Renovate less and less -One of our hopes with preset configs is that a set of "sensible" configs can be maintained by the community that combine grouping, scheduling and automerging to reduce the amount of noise in repositories with little downside or increased risk. Such lists could be maintained and used somewhat like Adblock lists - kept up to date by maintainers but for the majority of users they are simply trusted/automatic/invisible. +One of our hopes with preset configs is that a set of "sensible" configs can be maintained by the community that combine grouping, scheduling and automerging to reduce the amount of noise in repositories with little downside or increased risk. +Such lists could be maintained and used somewhat like Adblock lists - kept up to date by maintainers but for the majority of users they are simply trusted/automatic/invisible. diff --git a/docs/usage/nuget.md b/docs/usage/nuget.md index d2da302a5..c67de6035 100644 --- a/docs/usage/nuget.md +++ b/docs/usage/nuget.md @@ -26,7 +26,8 @@ To convert your .NET Framework `.csproj`/`.fsproj`/`.vbproj` into an SDK-style p ## Alternate feeds -Renovate by default performs all lookups on `https://api.nuget.org/v3/index.json`, but it also supports alternative NuGet feeds. Alternative feeds can be specified either [in a `NuGet.config` file](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) within your repository (Renovate will not search outside the repository) or in Renovate configuration options: +Renovate by default performs all lookups on `https://api.nuget.org/v3/index.json`, but it also supports alternative NuGet feeds. +Alternative feeds can be specified either [in a `NuGet.config` file](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) within your repository (Renovate will not search outside the repository) or in Renovate configuration options: ```json "nuget": { @@ -38,11 +39,15 @@ Renovate by default performs all lookups on `https://api.nuget.org/v3/index.json } ``` -If this example we defined 3 NuGet feeds. Packages resolving will process feeds consequentially. It means that if package will be resolved in second feed renovate won't look in last one. +If this example we defined 3 NuGet feeds. +Packages resolving will process feeds consequentially. +It means that if package will be resolved in second feed renovate won't look in last one. ### Protocol versions -NuGet supports two protocol versions, `v2` and `v3`, which NuGet client and server need to agree on. Renovate as a NuGet client supports both versions and will use `v2` unless the configured feed URL ends with `index.json` (which mirrors the behavior of the official NuGet client). If you have `v3` feed that does not match this pattern (e.g. JFrog Artifactory) you need to help Renovate by appending `#protocolVersion=3` to the registry URL: +NuGet supports two protocol versions, `v2` and `v3`, which NuGet client and server need to agree on. +Renovate as a NuGet client supports both versions and will use `v2` unless the configured feed URL ends with `index.json` (which mirrors the behavior of the official NuGet client). +If you have `v3` feed that does not match this pattern (e.g. JFrog Artifactory) you need to help Renovate by appending `#protocolVersion=3` to the registry URL: ```json "nuget": { diff --git a/docs/usage/php.md b/docs/usage/php.md index d1d65bf75..0ec876b0e 100644 --- a/docs/usage/php.md +++ b/docs/usage/php.md @@ -36,9 +36,11 @@ If you are using a [privately hosted Composer package](https://getcomposer.org/d } ``` -This host rule is best added to the bot's `config.js` config so that it is not visible to users of the repository. If you are using the hosted WhiteSource Renovate App then you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. +This host rule is best added to the bot's `config.js` config so that it is not visible to users of the repository. +If you are using the hosted WhiteSource Renovate App then you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. -Go to [https://renovatebot.com/encrypt](https://renovatebot.com/encrypt), paste in the secret string you wish to encrypt, click _Encrypt_, then copy the encrypted result. You may encrypt your `password` only or even pass your `username` encrypted. +Go to [https://renovatebot.com/encrypt](https://renovatebot.com/encrypt), paste in the secret string you wish to encrypt, click _Encrypt_, then copy the encrypted result. +You may encrypt your `password` only or even pass your `username` encrypted. ```json { diff --git a/docs/usage/private-modules.md b/docs/usage/private-modules.md index f47e41ff0..786007abc 100644 --- a/docs/usage/private-modules.md +++ b/docs/usage/private-modules.md @@ -11,7 +11,10 @@ Private npm modules are used at two times during Renovate's process. #### 1. Module lookup -If a private npm module is listed as a dependency in a `package.json`, then Renovate will attempt to keep it up-to-date by querying the npm registry like it would for any other package. Hence, by default with no configuration a private package lookup will fail, because of lack of credentials. This means it won't be "renovated" and its version will remain unchanged in the package file unless you update it manually. These failures don't affect Renovate's ability to look up _other_ modules in the same package file. +If a private npm module is listed as a dependency in a `package.json`, then Renovate will attempt to keep it up-to-date by querying the npm registry like it would for any other package. +Hence, by default with no configuration a private package lookup will fail, because of lack of credentials. +This means it won't be "renovated" and its version will remain unchanged in the package file unless you update it manually. +These failures don't affect Renovate's ability to look up _other_ modules in the same package file. Assuming the private module lookup succeeds (solutions for that are described later in this document) then private package versions will be kept up-to-date like public package versions are. @@ -19,7 +22,10 @@ Assuming the private module lookup succeeds (solutions for that are described la If you are using a lock file (e.g. Yarn's `yarn.lock` or npm's `package-lock.json`) then Renovate needs to update that lock file whenever _any_ package listed in your package file is updated to a new version. -To do this, Renovate will run `npm install` or equivalent and save the resulting lock file. If a private module hasn't been updated, it _usually_ won't matter to npm/Yarn because they won't attempt to update its lock file entry anyway. However it's possible that the install will fail if it attempts to look up that private module for some reason, even when that private module is not the main one being updated. It's therefore better to provide Renovate with all the credentials it needs to look up private packages. +To do this, Renovate will run `npm install` or equivalent and save the resulting lock file. +If a private module hasn't been updated, it _usually_ won't matter to npm/Yarn because they won't attempt to update its lock file entry anyway. +However it's possible that the install will fail if it attempts to look up that private module for some reason, even when that private module is not the main one being updated. +It's therefore better to provide Renovate with all the credentials it needs to look up private packages. ## Supported npm authentication approaches @@ -35,13 +41,16 @@ All the various approaches are described below: ### Commit .npmrc file into repository -One approach that many projects use for private repositories is to simply check in an authenticated `.npmrc` into the repository that is then shared between all developers. Therefore anyone running `npm install` or `yarn install` from the project root will be automatically authenticated with npm without having to distribute npm logins to every developer and make sure they've run `npm login` first before installing. +One approach that many projects use for private repositories is to simply check in an authenticated `.npmrc` into the repository that is then shared between all developers. +Therefore anyone running `npm install` or `yarn install` from the project root will be automatically authenticated with npm without having to distribute npm logins to every developer and make sure they've run `npm login` first before installing. -The good news is that this works for Renovate too. If Renovate detects a `.npmrc` or `.yarnrc` file then it will use it for its install. +The good news is that this works for Renovate too. +If Renovate detects a `.npmrc` or `.yarnrc` file then it will use it for its install. ### Add npmrc string to Renovate config -The above solution maybe have a downside that all users of the repository (e.g. developers) will also use any `.npmrc` that is checked into the repository, instead of their own one in `~/.npmrc`. To avoid this, you can instead add your `.npmrc` authentication line to your Renovate config under the field `npmrc`. e.g. a `renovate.json` might look like this: +The above solution maybe have a downside that all users of the repository (e.g. developers) will also use any `.npmrc` that is checked into the repository, instead of their own one in `~/.npmrc`. +To avoid this, you can instead add your `.npmrc` authentication line to your Renovate config under the field `npmrc`. e.g. a `renovate.json` might look like this: ```json { @@ -77,7 +86,8 @@ Add the encrypted result inside an `encrypted` object like this: } ``` -If you have no `.npmrc` file then Renovate will create one for you, pointing to the default npmjs registry. If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. +If you have no `.npmrc` file then Renovate will create one for you, pointing to the default npmjs registry. +If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. ```json { @@ -98,7 +108,8 @@ Renovate will then use the following logic: Copy the entire .npmrc, replace newlines with `\n` chars, and then try encrypting it at https://renovatebot.com/encrypt -You will then get an encrypted string that you can substitute into your renovate.json instead. The result will now look something like this: +You will then get an encrypted string that you can substitute into your renovate.json instead. +The result will now look something like this: ```json { diff --git a/docs/usage/python.md b/docs/usage/python.md index b076d8a48..dac6d611f 100644 --- a/docs/usage/python.md +++ b/docs/usage/python.md @@ -13,7 +13,8 @@ Renovate supports the following Python package managers: ## Versioning Support -The [PEP440](https://www.python.org/dev/peps/pep-0440/) versioning scheme has been rewritten for JavaScript for the purposes of use in this project is published as [@renovatebot/pep440](https://github.com/renovatebot/pep440). It supports both pinned versions as well as ranges. Legacy versions (`===` prefix) are ignored. +The [PEP440](https://www.python.org/dev/peps/pep-0440/) versioning scheme has been rewritten for JavaScript for the purposes of use in this project is published as [@renovatebot/pep440](https://github.com/renovatebot/pep440). +It supports both pinned versions as well as ranges. Legacy versions (`===` prefix) are ignored. ## How It Works @@ -24,7 +25,8 @@ The [PEP440](https://www.python.org/dev/peps/pep-0440/) versioning scheme has be ## Enabling Beta -Both `pipenv` and `setup.py` are classified a "beta", so they are not enabled by default. To enable them, you need to add configuration like the following to your `renovate.json` file: +Both `pipenv` and `setup.py` are classified a "beta", so they are not enabled by default. +To enable them, you need to add configuration like the following to your `renovate.json` file: ```json { @@ -34,11 +36,14 @@ Both `pipenv` and `setup.py` are classified a "beta", so they are not enabled by } ``` -Note: if you _only_ have these package files and no other package files (like `package.json`, `Dockerfile`, etc) then Renovate won't detect them and you won't get an onboarding PR. In that case you need to add Renovate configuration manually to skip the onboarding step. +Note: if you _only_ have these package files and no other package files (like `package.json`, `Dockerfile`, etc) then Renovate won't detect them and you won't get an onboarding PR. +In that case you need to add Renovate configuration manually to skip the onboarding step. ## Alternative file names -The default file matching regex for `requirements.txt` aims to pick up the most popular conventions for file naming, but it's possible that some get missed. If you have a specific file or file pattern you want to get found by Renovate, then you can do this by adding a new pattern under the `fileMatch` field of `pip_requirements`. e.g. you could add this to your config: +The default file matching regex for `requirements.txt` aims to pick up the most popular conventions for file naming, but it's possible that some get missed. +If you have a specific file or file pattern you want to get found by Renovate, then you can do this by adding a new pattern under the `fileMatch` field of `pip_requirements`. +e.g. you could add this to your config: ```json "pip_requirements": { @@ -48,11 +53,13 @@ The default file matching regex for `requirements.txt` aims to pick up the most ## Alternate registries -Renovate will default to performing all lookups on pypi.org, but it also supports alternative index URLs. There are two ways to achieve this: +Renovate will default to performing all lookups on pypi.org, but it also supports alternative index URLs. +There are two ways to achieve this: #### index-url in `requirements.txt` -The index URL can be specified in the first line of the file, For example: +The index URL can be specified in the first line of the file. +For example: ``` --index-url http://example.com/private-pypi/ @@ -66,7 +73,8 @@ Renovate will detect any custom-configured sources in `Pipfile` and use them. #### Specify URL in configuration -The configuration option `registryUrls` can be used to configure an alternate index URL. Example: +The configuration option `registryUrls` can be used to configure an alternate index URL. +Example: ```json "python": { @@ -74,7 +82,8 @@ The configuration option `registryUrls` can be used to configure an alternate in } ``` -Note: an index-url found in the `requirements.txt` will take precedent over a registryUrl configured like the above. To override the URL found in `requirements.txt`, you need to configure it in `packageRules`, as they are applied _after_ package file extraction. +Note: an index-url found in the `requirements.txt` will take precedent over a registryUrl configured like the above. +To override the URL found in `requirements.txt`, you need to configure it in `packageRules`, as they are applied _after_ package file extraction. ## Disabling Python Support @@ -86,7 +95,8 @@ The most direct way to disable all Python support in Renovate is like this: } ``` -Alternatively, maybe you only want one package manager, such as `npm`. In that case this would enable _only_ `npm`: +Alternatively, maybe you only want one package manager, such as `npm`. +In that case this would enable _only_ `npm`: ```json "enabledManagers": ["npm"] @@ -94,4 +104,6 @@ Alternatively, maybe you only want one package manager, such as `npm`. In that c ## Future work -Feature requests are open for conda support and additional file types (e.g. `setup.cfg`). You can locate these issues by filtering on the [#python](https://github.com/renovatebot/renovate/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%23python) hashtag in the repository. Please +1 and/or add a comment to each issue that would benefit you so that we can gauge the popularity/importance of each. +Feature requests are open for conda support and additional file types (e.g. `setup.cfg`). +You can locate these issues by filtering on the [#python](https://github.com/renovatebot/renovate/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%23python) hashtag in the repository. +Please +1 and/or add a comment to each issue that would benefit you so that we can gauge the popularity/importance of each. diff --git a/docs/usage/reconfigure-renovate.md b/docs/usage/reconfigure-renovate.md index e8fef1e0f..83ca4f0cd 100644 --- a/docs/usage/reconfigure-renovate.md +++ b/docs/usage/reconfigure-renovate.md @@ -5,17 +5,22 @@ description: How to reconfigure Renovate once it's onboarded # Reconfiguring Renovate -There will likely be times when you need to change your Renovate config. There are two recommended approaches: +There will likely be times when you need to change your Renovate config. +There are two recommended approaches: ## Reconfigure via PR -If you wish to make config edits directly, it's recommended to do so via a PR and then run Renovate's config validator to verify it. The validator is named `renovate-config-validator` and installed alongside `renovate` itself if you run `npm i -g renovate` or equivalent. If it validates your new config then it should be safe to merge. +If you wish to make config edits directly, it's recommended to do so via a PR and then run Renovate's config validator to verify it. +The validator is named `renovate-config-validator` and installed alongside `renovate` itself if you run `npm i -g renovate` or equivalent. +If it validates your new config then it should be safe to merge. ## Nuke config and re-onboard -Perhaps you really liked the interactive PR and want to see it again. In that case: +Perhaps you really liked the interactive PR and want to see it again. +In that case: 1. Find and rename your original `Configure Renovate` PR (e.g. to `Configure Renovate - old`) 2. Delete your Renovate config (e.g. `renovate.json`) from your base branch -This will be enough to trick Renovate into thinking that the repository was _never_ onboarded and it will trigger a new Configure Renovate PR again. Any existing Renovate PRs in progress may be closed, however. +This will be enough to trick Renovate into thinking that the repository was _never_ onboarded and it will trigger a new Configure Renovate PR again. +Any existing Renovate PRs in progress may be closed, however. diff --git a/docs/usage/ruby.md b/docs/usage/ruby.md index 01a279584..e9924075b 100644 --- a/docs/usage/ruby.md +++ b/docs/usage/ruby.md @@ -5,7 +5,8 @@ description: Ruby Bundler support in Renovate # Automated Dependency Updates for Ruby Bundler Dependencies -Renovate supports upgrading dependencies in Bundler's `Gemfile`s and their accompanying `Gemfile.lock` files. Support is considered "alpha" stage until there have been some more real-world tests. +Renovate supports upgrading dependencies in Bundler's `Gemfile`s and their accompanying `Gemfile.lock` files. +Support is considered "alpha" stage until there have been some more real-world tests. ## How It Works @@ -17,7 +18,8 @@ Renovate supports upgrading dependencies in Bundler's `Gemfile`s and their accom ## Enabling -Either install the [Renovate App](https://github.com/apps/renovate) on GitHub, or check out [Renovate OSS](https://github.com/renovatebot/renovate) for self-hosted. Bundler support is now enabled by default in both. +Either install the [Renovate App](https://github.com/apps/renovate) on GitHub, or check out [Renovate OSS](https://github.com/renovatebot/renovate) for self-hosted. +Bundler support is now enabled by default in both. ## Future work diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index f059da4cf..9e8c31ac5 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -9,7 +9,8 @@ The below configuration options are applicable only if you are running your own ## allowedPostUpgradeCommands -A list of regular expressions that determine which commands in `postUpgradeTasks` are allowed to be executed. If this list is empty then no tasks will be executed. +A list of regular expressions that determine which commands in `postUpgradeTasks` are allowed to be executed. +If this list is empty then no tasks will be executed. e.g. @@ -21,7 +22,8 @@ e.g. ## autodiscover -Be cautious when using this option - it will run Renovate over _every_ repository that the bot account has access to. To filter this list, use `autodiscoverFilter`. +Be cautious when using this option - it will run Renovate over _every_ repository that the bot account has access to. +To filter this list, use `autodiscoverFilter`. ## autodiscoverFilter @@ -29,7 +31,8 @@ A [minimatch](https://www.npmjs.com/package/minimatch) glob-style pattern for fi ## baseDir -Configure this directory if you want to change which directory Renovate uses for storing data. If left unconfigured, it will typically be a temporary directory like `/tmp/renovate/`. +Configure this directory if you want to change which directory Renovate uses for storing data. +If left unconfigured, it will typically be a temporary directory like `/tmp/renovate/`. ## binarySource @@ -38,7 +41,9 @@ Set this to `docker` instead to use Docker-based binaries. ## cacheDir -Configure this directory if you want to change which directory Renovate uses for storing cache data. If left unconfigured, it will typically be a temporary directory like `/tmp/renovate/cache/`. If you configure this to be different to the `baseDir`, it means you can have one location for repo data and another for cache data. +Configure this directory if you want to change which directory Renovate uses for storing cache data. +If left unconfigured, it will typically be a temporary directory like `/tmp/renovate/cache/`. +If you configure this to be different to the `baseDir`, it means you can have one location for repo data and another for cache data. ## composerIgnorePlatformReqs @@ -52,11 +57,14 @@ If this is set to `ghcr.io/renovatebot` the final image for `node` would become ## dockerMapDotfiles -This is used if you want to map "dotfiles" from your host computer home directory to containers that Renovate creates, e.g. for updating lock files. Currently applicable to `.npmrc` only. +This is used if you want to map "dotfiles" from your host computer home directory to containers that Renovate creates, e.g. for updating lock files. +Currently applicable to `.npmrc` only. ## dockerUser -Override default user and group used by Docker-based binaries. UID and GID should match the user that executes renovate. See [Docker run reference](https://docs.docker.com/engine/reference/run/#user) for more information on user and group syntax. +Override default user and group used by Docker-based binaries. +UID and GID should match the user that executes renovate. +See [Docker run reference](https://docs.docker.com/engine/reference/run/#user) for more information on user and group syntax. Set this to `1001:1002` to use UID 1001 and GID 1002. ## dryRun @@ -65,13 +73,15 @@ Set this to `1001:1002` to use UID 1001 and GID 1002. ## force -This object is used as a "force override" when you need to make sure certain configuration overrides whatever is configured in the repository. For example, forcing a null (no) schedule to make sure Renovate raises PRs on a run even if the repository itself or its preset defines a schedule that's currently in active. +This object is used as a "force override" when you need to make sure certain configuration overrides whatever is configured in the repository. +For example, forcing a null (no) schedule to make sure Renovate raises PRs on a run even if the repository itself or its preset defines a schedule that's currently in active. In practice, it is implemented by converting the `force` configuration into a `packageRule` that matches all packages. ## forceCli -This is set to true by default, meaning that any settings (such as `schedule`) take maximum priority even against custom settings existing inside individual repositories. It will also override any settings in `packageRules`. +This is set to true by default, meaning that any settings (such as `schedule`) take maximum priority even against custom settings existing inside individual repositories. +It will also override any settings in `packageRules`. ## forkMode @@ -79,15 +89,20 @@ You probably have no need for this option - it is an experimental setting for th ## gitAuthor -RFC5322-compliant string if you wish to customise the Git author for commits. If you need to transition from one Git author to another, put the old gitAuthor into `RENOVATE_LEGACY_GIT_AUTHOR_EMAIL` in environment. Renovate will then check against it as well as the current Git author value before deciding if a branch has been modified. +RFC5322-compliant string if you wish to customise the Git author for commits. +If you need to transition from one Git author to another, put the old gitAuthor into `RENOVATE_LEGACY_GIT_AUTHOR_EMAIL` in environment. +Renovate will then check against it as well as the current Git author value before deciding if a branch has been modified. -**Note** It is strongly recommended that the Git author email you provide should be unique to Renovate. Otherwise, if another bot or human shares the same email and pushes to one of Renovate's branches then Renovate will mistake the branch as unmodified and potentially force push over the changes. +**Note** It is strongly recommended that the Git author email you provide should be unique to Renovate. +Otherwise, if another bot or human shares the same email and pushes to one of Renovate's branches then Renovate will mistake the branch as unmodified and potentially force push over the changes. ## gitPrivateKey -This should be an armored private key, e.g. the type you get from running `gpg --export-secret-keys --armor 92066A17F0D1707B4E96863955FEF5171C45FAE5 > private.key`. Replace the newlines with `\n` before adding the resulting single-line value to your bot's config. +This should be an armored private key, e.g. the type you get from running `gpg --export-secret-keys --armor 92066A17F0D1707B4E96863955FEF5171C45FAE5 > private.key`. +Replace the newlines with `\n` before adding the resulting single-line value to your bot's config. -It will be loaded _lazily_. Before the first commit in a repository, Renovate will: +It will be loaded _lazily_. +Before the first commit in a repository, Renovate will: - First, run `gpg import` if it hasn't been run before - Then, run `git config user.signingkey` and `git config commit.gpgsign true` @@ -96,7 +111,8 @@ The `git` commands are run locally in the cloned repo instead of globally to red ## logContext -`logContext` is included with each log entry only if `logFormat="json"` - it is not included in the pretty log output. If left as default (null), a random short ID will be selected. +`logContext` is included with each log entry only if `logFormat="json"` - it is not included in the pretty log output. +If left as default (null), a random short ID will be selected. ## logFile @@ -104,7 +120,8 @@ The `git` commands are run locally in the cloned repo instead of globally to red ## logLevel -It's recommended to run at debug level if you can, and configure it using the environment variable `LOG_LEVEL=debug`. By configuring using the environment it means that debug logging starts from the beginning of the app, while if you configure it using file config then the debug logging can only start after the file config is parsed. +It's recommended to run at debug level if you can, and configure it using the environment variable `LOG_LEVEL=debug`. +By configuring using the environment it means that debug logging starts from the beginning of the app, while if you configure it using file config then the debug logging can only start after the file config is parsed. Additionally, if you configure `LOG_FORMAT=json` in env then logging will be done in JSON format instead of "pretty" format, which is usually better if you're doing any ingestion or parsing of the logs. @@ -114,7 +131,9 @@ Set this to `false` if (a) you configure Renovate entirely on the bot side (i.e. ## onboardingBranch -Note that this setting is independent of `branchPrefix`. For example, if you configure `branchPrefix` to be `renovate-` then you'd still have the onboarding PR created with branch `renovate/configure` until you configure `onboardingBranch=renovate-configure` or similar. If you have an existing Renovate installation and you change `onboardingBranch` then it's possible that you'll get onboarding PRs for repositories that had previously closed the onboarding PR unmerged. +Note that this setting is independent of `branchPrefix`. +For example, if you configure `branchPrefix` to be `renovate-` then you'd still have the onboarding PR created with branch `renovate/configure` until you configure `onboardingBranch=renovate-configure` or similar. +If you have an existing Renovate installation and you change `onboardingBranch` then it's possible that you'll get onboarding PRs for repositories that had previously closed the onboarding PR unmerged. ## onboardingCommitMessage @@ -132,23 +151,30 @@ Similarly to `onboardingBranch`, if you have an existing Renovate installation a ## persistRepoData -Set this to true if you wish for Renovate to persist repo data between runs. The intention is that this allows Renovate to do a faster `git fetch` between runs rather than `git clone`. It also may mean that ignored directories like `node_modules` can be preserved and save time on operations like `npm install`. +Set this to true if you wish for Renovate to persist repo data between runs. +The intention is that this allows Renovate to do a faster `git fetch` between runs rather than `git clone`. +It also may mean that ignored directories like `node_modules` can be preserved and save time on operations like `npm install`. ## platform ## prCommitsPerRunLimit -Parameter to reduce CI load. CI jobs are usually triggered by these events: pull-request creation, pull-request update, automerge events. Set as an integer. Default is no limit. +Parameter to reduce CI load. +CI jobs are usually triggered by these events: pull-request creation, pull-request update, automerge events. +Set as an integer. +Default is no limit. ## printConfig -This option is useful for troubleshooting, particularly if using presets. e.g. run `renovate foo/bar --print-config > config.log` and the fully-resolved config will be included in the log file. +This option is useful for troubleshooting, particularly if using presets. +e.g. run `renovate foo/bar --print-config > config.log` and the fully-resolved config will be included in the log file. ## privateKey This private key is used to decrypt config files. -The corresponding public key can be used to create encrypted values for config files. If you want a simple UI to encrypt values you can put the public key in a HTML page similar to . +The corresponding public key can be used to create encrypted values for config files. +If you want a simple UI to encrypt values you can put the public key in a HTML page similar to . To create the key pair with openssl use the following commands: @@ -165,13 +191,17 @@ Override this object if you wish to change the URLs that Renovate links to, e.g. ## redisUrl -If this value is set then Renovate will use Redis for its global cache instead of the local file system. The global cache is used to store lookup results (e.g. dependency versions and release notes) between repositories and runs. Example url: `redis://localhost`. +If this value is set then Renovate will use Redis for its global cache instead of the local file system. +The global cache is used to store lookup results (e.g. dependency versions and release notes) between repositories and runs. +Example url: `redis://localhost`. ## repositories ## repositoryCache -Set this to `"enabled"` to have Renovate maintain a JSON file cache per-repository to speed up extractions. Set to `"reset"` if you ever need to bypass the cache and have it overwritten. JSON files will be stored inside the `cacheDir` beside the existing file-based package cache. +Set this to `"enabled"` to have Renovate maintain a JSON file cache per-repository to speed up extractions. +Set to `"reset"` if you ever need to bypass the cache and have it overwritten. +JSON files will be stored inside the `cacheDir` beside the existing file-based package cache. Warning: this is an experimental feature and may be modified or removed in a future non-major release. @@ -179,7 +209,9 @@ Warning: this is an experimental feature and may be modified or removed in a fut ## skipInstalls -By default, Renovate will use the most efficient approach to updating package files and lock files, which in most cases skips the need to perform a full module install by the bot. If this is set to false, then a full install of modules will be done. This is currently applicable to `npm` and `lerna`/`npm` only, and only used in cases where bugs in `npm` result in incorrect lock files being updated. +By default, Renovate will use the most efficient approach to updating package files and lock files, which in most cases skips the need to perform a full module install by the bot. +If this is set to false, then a full install of modules will be done. +This is currently applicable to `npm` and `lerna`/`npm` only, and only used in cases where bugs in `npm` result in incorrect lock files being updated. ## token diff --git a/docs/usage/self-hosting.md b/docs/usage/self-hosting.md index f2514cc1c..f55bf0580 100644 --- a/docs/usage/self-hosting.md +++ b/docs/usage/self-hosting.md @@ -18,7 +18,9 @@ The same goes for any other third party binary tool that may be needed, such as #### Docker -Renovate is available for Docker via an automated build [renovate/renovate](https://hub.docker.com/r/renovate/renovate/). It builds `latest` based on the `master` branch and all semver tags are published too. All the following are valid: +Renovate is available for Docker via an automated build [renovate/renovate](https://hub.docker.com/r/renovate/renovate/). +It builds `latest` based on the `master` branch and all semver tags are published too. +All the following are valid: ```sh $ docker run --rm renovate/renovate @@ -29,7 +31,8 @@ $ docker run --rm renovate/renovate:19 (Please look up what the latest actual tags are though, do not use the above literally). -If you wish to configure Renovate using a `config.js` file then map it to `/usr/src/app/config.js` using Docker volumes. For example: +If you wish to configure Renovate using a `config.js` file then map it to `/usr/src/app/config.js` using Docker volumes. +For example: ```sh $ docker run --rm -v "/path/to/your/config.js:/usr/src/app/config.js" renovate/renovate @@ -37,7 +40,9 @@ $ docker run --rm -v "/path/to/your/config.js:/usr/src/app/config.js" renovate/r #### Kubernetes -Renovate's official Docker image is compatible with Kubernetes. The following is an example manifest of running Renovate against a GitHub Enterprise server. First the Kubernetes manifest: +Renovate's official Docker image is compatible with Kubernetes. +The following is an example manifest of running Renovate against a GitHub Enterprise server. +First the Kubernetes manifest: ```yaml apiVersion: batch/v1beta1 @@ -147,11 +152,13 @@ Self-hosted Renovate can be configured using any of the following (or a combinat - CLI params - Environment params -Note that some Renovate configuration options are _only_ available for self-hosting, and so can only be configured using one of the above methods. These are described in the [Self-hosted Configuration](./self-hosted-configuration.md) doc. +Note that some Renovate configuration options are _only_ available for self-hosting, and so can only be configured using one of the above methods. +These are described in the [Self-hosted Configuration](./self-hosted-configuration.md) doc. ## Authentication -Regardless of platform, you need to select a user account for `renovate` to assume the identity of, and generate a Personal Access Token. It is recommended to be `@renovate-bot` if you are using a self-hosted server with free choice of usernames. +Regardless of platform, you need to select a user account for `renovate` to assume the identity of, and generate a Personal Access Token. +It is recommended to be `@renovate-bot` if you are using a self-hosted server with free choice of usernames. It is also recommended that you configure `config.gitAuthor` with the same identity as your Renovate user, e.g. like `"gitAuthor": "Renovate Bot "`. #### GitHub Enterprise @@ -193,7 +200,10 @@ Don't forget to configure `platform=gitea` somewhere in config. ## GitHub.com token for release notes -If you are running on any platform except github.com, it's important to also configure the environment variable `GITHUB_COM_TOKEN` containing a personal access token for github.com. This account can actually be _any_ account on GitHub, and needs only read-only access. It's used when fetching release notes for repositories in order to increase the hourly API limit. It's also OK to configure the same as a host rule instead, if you prefer that. +If you are running on any platform except github.com, it's important to also configure the environment variable `GITHUB_COM_TOKEN` containing a personal access token for github.com. +This account can actually be _any_ account on GitHub, and needs only read-only access. +It's used when fetching release notes for repositories in order to increase the hourly API limit. +It's also OK to configure the same as a host rule instead, if you prefer that. **Note:** If you're using renovate in a project where dependencies are loaded from github.com (such as Go m=Modules hosted on GitHub) it is highly recommended to add a token as you will run in the rate limit from the github.com API, which will lead to renovate closing and reopening PRs because it could not get reliable info on updated dependencies. @@ -213,7 +223,9 @@ If you wish to override the cache location specifically then configure a value f The following example uses the Renovate CLI tool, which can be installed by running `npm i -g renovate`. -If running your own Renovate bot then you will need a user account that Renovate will run as. It's recommended to use a dedicated account for the bot, e.g. name it `renovate-bot` if on your own instance. Create and save a Personal Access Token for this account. +If running your own Renovate bot then you will need a user account that Renovate will run as. +It's recommended to use a dedicated account for the bot, e.g. name it `renovate-bot` if on your own instance. +Create and save a Personal Access Token for this account. Create a Renovate config file, e.g. here is an example: @@ -230,7 +242,8 @@ module.exports = { }; ``` -Here change the `logFile` and `repositories` to something appropriate. Also replace `gitlab-token` value with the one created during the previous step. +Here change the `logFile` and `repositories` to something appropriate. +Also replace `gitlab-token` value with the one created during the previous step. If running against GitHub Enterprise, change the above `gitlab` values to the equivalent GitHub ones. @@ -250,7 +263,8 @@ export GITHUB_COM_TOKEN="**github-token**" # Delete this if using github.com renovate ``` -Note: the GitHub.com token in env is necessary in order to retrieve Release Notes that are usually hosted on github.com. You don't need to add it if you are already running the bot against github.com, but you do need to add it if you're using GitHub Enterprise, GitLab, Azure DevOps, or Bitbucket. +Note: the GitHub.com token in env is necessary in order to retrieve Release Notes that are usually hosted on github.com. +You don't need to add it if you are already running the bot against github.com, but you do need to add it if you're using GitHub Enterprise, GitLab, Azure DevOps, or Bitbucket. You should save and test out this script manually first, and add it to cron once you've verified it. @@ -290,8 +304,8 @@ metadata: namespace: ``` -Then you just need to add Git author, and mount volumes -The final configuration should look like something like this : +Then you just need to add Git author, and mount volumes. +The final configuration should look like something like this: ```yml --- @@ -360,4 +374,5 @@ spec: ## Logging -It's recommended to configure `LOG_LEVEL=debug` and `LOG_FORMAT=json` in environment if you are ingesting/parsing logs into another system. Debug logging is usually necessary for any debugging, while JSON format will mean that the output is parseable. +It's recommended to configure `LOG_LEVEL=debug` and `LOG_FORMAT=json` in environment if you are ingesting/parsing logs into another system. +Debug logging is usually necessary for any debugging, while JSON format will mean that the output is parseable. diff --git a/docs/usage/semantic-commits.md b/docs/usage/semantic-commits.md index 72c3fa4b6..930f86922 100644 --- a/docs/usage/semantic-commits.md +++ b/docs/usage/semantic-commits.md @@ -5,7 +5,8 @@ description: Configuring Renovate to use Semantic Commits # Semantic Commit Messages -Renovate attempts to autodetect if your repository uses "semantic" commit message prefixes, and adds them if so. To do so, it looks at the 10 most recent commit messages in the base branch and uses [conventional-commits-detector](https://github.com/conventional-changelog/conventional-commits-detector) to determine convention commit type. +Renovate attempts to autodetect if your repository uses "semantic" commit message prefixes, and adds them if so. +To do so, it looks at the 10 most recent commit messages in the base branch and uses [conventional-commits-detector](https://github.com/conventional-changelog/conventional-commits-detector) to determine convention commit type. Currently, Renovate ignores commit conventions apart from "angular". @@ -22,10 +23,13 @@ If you wish to manually override Renovate's semantic commit detection, then you ## Changing the Semantic Commit Type -If you wish to say use "chore" for every PR, then you can add `":semanticCommitTypeAll(chore)"` to your `extends` array. Or if you wish to use `ci` then you would add `":semanticCommitTypeAll(ci)"` instead. This second case would mean your PR titles and commit messages will start with "ci(deps):". +If you wish to say use "chore" for every PR, then you can add `":semanticCommitTypeAll(chore)"` to your `extends` array. +Or if you wish to use `ci` then you would add `":semanticCommitTypeAll(ci)"` instead. +This second case would mean your PR titles and commit messages will start with "ci(deps):". ## Changing the Semantic Commit Scope -If you don't like "deps" then this can also be configured. For example, to set it to "package" you should add the preset `":semanticCommitScope(package)"` to your `extends` array. +If you don't like "deps" then this can also be configured. +For example, to set it to "package" you should add the preset `":semanticCommitScope(package)"` to your `extends` array. If you wish to _remove_ the semantic commit scope (e.g. use prefix `chore:` instead of `chore(deps):`) then you should add the preset `":semanticCommitScopeDisabled"` to your `extends` array. diff --git a/docs/usage/setup-azure-devops.md b/docs/usage/setup-azure-devops.md index b5afe8126..ea8a4ae0d 100644 --- a/docs/usage/setup-azure-devops.md +++ b/docs/usage/setup-azure-devops.md @@ -78,4 +78,5 @@ jobs: npx --userconfig .npmrc renovate ``` -1. Additionally, you can add `renovate.json` with renovate configurations in the root of the repo. [Read more about configurations options](https://docs.renovatebot.com/configuration-options/). +1. Additionally, you can add `renovate.json` with renovate configurations in the root of the repo. + [Read more about configurations options](https://docs.renovatebot.com/configuration-options/). diff --git a/docs/usage/templates.md b/docs/usage/templates.md index 383759511..e4f9445de 100644 --- a/docs/usage/templates.md +++ b/docs/usage/templates.md @@ -7,9 +7,11 @@ description: In order to provide flexible configuration, Renovate supports using "templates" for certain fields like `branchName`. -Renovate's templates use [handlebars](https://handlebarsjs.com/) under the hood. You can recognize templates when you see strings like `{{depName}}` in configuration fields. +Renovate's templates use [handlebars](https://handlebarsjs.com/) under the hood. +You can recognize templates when you see strings like `{{depName}}` in configuration fields. -Below you can find lists of fields/values that you can use in templates. Some are configuration options passed through, while others are generated as part of Renovate's run. +Below you can find lists of fields/values that you can use in templates. +Some are configuration options passed through, while others are generated as part of Renovate's run. ## Exposed Config Options diff --git a/docs/usage/updating-rebasing.md b/docs/usage/updating-rebasing.md index 40e66046c..5a8a14ebf 100644 --- a/docs/usage/updating-rebasing.md +++ b/docs/usage/updating-rebasing.md @@ -7,15 +7,21 @@ description: How Renovate Updates and Rebases Branches There are many cases where Renovate will need to update a branch/PR after its initial creation, and this document will attempt to describe them. -Note: Renovate doesn't technically do "rebasing" in the Git sense. Instead, it manually recreates the same commit based off of the latest commit in base branch. +Note: Renovate doesn't technically do "rebasing" in the Git sense. +Instead, it manually recreates the same commit based off of the latest commit in base branch. ## If you have made edits -First of all, here is the one time when Renovate _won't_ update branches. If you have edited a Renovate branch directly (e.g. to make a code fix to allow tests to pass again) then Renovate will stop all updates of that branch. It is up to you to either finish the job and merge the PR, or rename it and close it so that Renovate can take back over again. +First of all, here is the one time when Renovate _won't_ update branches. +If you have edited a Renovate branch directly (e.g. to make a code fix to allow tests to pass again) then Renovate will stop all updates of that branch. +It is up to you to either finish the job and merge the PR, or rename it and close it so that Renovate can take back over again. ## Rebasing Conflicted PRs -If new commits to the base branch - such as merging another Renovate PR - result in an open Renovate PR having merge conflicts, then Renovate will recreate ("rebase") any conflicted PRs. This applies both to commits to dependency files such as `package.json` as well as lock files such as `yarn.lock`. You should not ever need to resolve such conflicts manually. You can disable this functionality by configuring `"rebaseWhen": "never"` (not recommended); +If new commits to the base branch - such as merging another Renovate PR - result in an open Renovate PR having merge conflicts, then Renovate will recreate ("rebase") any conflicted PRs. +This applies both to commits to dependency files such as `package.json` as well as lock files such as `yarn.lock`. +You should not ever need to resolve such conflicts manually. +You can disable this functionality by configuring `"rebaseWhen": "never"` (not recommended); ## Rebasing Out-of-date Branches @@ -28,16 +34,19 @@ In that case Renovate PRs will be continuously rebased off the repository's base ## Newer Dependency Versions -If an existing PR is open to upgrade dependency "foo" to v1.1.0 and then v1.1.1 is released, then Renovate will regenerate the branch again. This way: +If an existing PR is open to upgrade dependency "foo" to v1.1.0 and then v1.1.1 is released, then Renovate will regenerate the branch again. +This way: - Each Renovate branch will always have 1 and only 1 commit - The newest version will be based off the latest base branch commit at the time ## Manual rebasing -It is possible to manually request that Renovate rebase a PR by ticking a rebase/retry checkbox on GitHub or GitLab, or by adding the label "rebase" to a Renovate PR. This label name is also configurable via the `rebaseLabel` config option too. +It is possible to manually request that Renovate rebase a PR by ticking a rebase/retry checkbox on GitHub or GitLab, or by adding the label "rebase" to a Renovate PR. +This label name is also configurable via the `rebaseLabel` config option too. -If you apply this label then Renovate will regenerate its commit for the branch, even if the branch has been modified. Therefore it is useful in situations such as: +If you apply this label then Renovate will regenerate its commit for the branch, even if the branch has been modified. +Therefore it is useful in situations such as: - If a branch is stale but you don't have `rebaseWhen=behind-base-branch` enabled - If a branch has been edited and you wish to discard the edits and have Renovate create it again diff --git a/readme.md b/readme.md index 9b60635e6..f3eaa564b 100644 --- a/readme.md +++ b/readme.md @@ -36,14 +36,23 @@ Renovate was released in 2017 and already is widely used in the developer commun ## Using Renovate -The easiest way to use Renovate if you are hosted on GitHub.com or GitLab.com is to install the hosted Renovate app. On Azure DevOps you can install Renovate as an extension from the marketplace. +The easiest way to use Renovate if you are hosted on GitHub.com or GitLab.com is to install the hosted Renovate app. +On Azure DevOps you can install Renovate as an extension from the marketplace. -For GitHub, go to [https://github.com/apps/renovate](https://github.com/apps/renovate) to install -it now. A GitHub Marketplace plan is required only for private repositories. [More details on the GitHub App installation](https://docs.renovatebot.com/install-github-app/). +For GitHub, go to [https://github.com/apps/renovate](https://github.com/apps/renovate) to install it now. +A GitHub Marketplace plan is required only for private repositories. +[More details on the GitHub App installation](https://docs.renovatebot.com/install-github-app/). -For GitLab, log into [app.renovatebot.com/dashboard](https://app.renovatebot.com/dashboard) for a convenient way to add Renovate Bot to your project. Currently the GitLab app is free for both public and private repositories. [More details on the GitLab App installation](https://docs.renovatebot.com/install-gitlab-app/). +For GitLab, log into [app.renovatebot.com/dashboard](https://app.renovatebot.com/dashboard) for a convenient way to add Renovate Bot to your project. +Currently the GitLab app is free for both public and private repositories. +[More details on the GitLab App installation](https://docs.renovatebot.com/install-gitlab-app/). -For Azure DevOps, visit the Visual Studio Marketplace and install the [Renovate Me](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me) extension in your organisation. From there you can create a pipeline with the `RenovateMe` task. [More details on how to configure the pipeline](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me). Note: This extension is created and maintained personally by a Renovate developer/user so support requests relating to the extension itself cannot be answered directly in the main Renovate repository. Alternatively, you can create custom pipeline with with a `yml` definition that will trigger `npx renovate`. [More details on how to configure the pipeline](https://docs.renovatebot.com/setup-azure-devops/). +For Azure DevOps, visit the Visual Studio Marketplace and install the [Renovate Me](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me) extension in your organisation. +From there you can create a pipeline with the `RenovateMe` task. +[More details on how to configure the pipeline](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me). +Note: This extension is created and maintained personally by a Renovate developer/user so support requests relating to the extension itself cannot be answered directly in the main Renovate repository. +Alternatively, you can create custom pipeline with with a `yml` definition that will trigger `npx renovate`. +[More details on how to configure the pipeline](https://docs.renovatebot.com/setup-azure-devops/). ## Configuration @@ -67,4 +76,5 @@ If you would like to contribute to Renovate or get a local copy running for some ## Security / Disclosure -If you discover any important bug with Renovate that may pose a security problem, please disclose it confidentially to renovate-disclosure@whitesourcesoftware.com first, so that it can be assessed and hopefully fixed prior to being exploited. Please do not raise GitHub issues for security-related doubts or problems. +If you discover any important bug with Renovate that may pose a security problem, please disclose it confidentially to renovate-disclosure@whitesourcesoftware.com first, so that it can be assessed and hopefully fixed prior to being exploited. +Please do not raise GitHub issues for security-related doubts or problems.