From 88f8664d3fa25d3582534be95cb4c8673debc906 Mon Sep 17 00:00:00 2001 From: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> Date: Thu, 28 Dec 2023 05:34:45 +0100 Subject: [PATCH 1/9] docs: Proofreading + general improvements Signed-off-by: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> --- docs/development/adding-a-package-manager.md | 4 +- docs/development/best-practices.md | 4 +- docs/development/branches-commits.md | 6 +- docs/development/configuration.md | 2 +- .../creating-editing-renovate-presets.md | 12 +- docs/development/design-decisions.md | 16 +- docs/development/help-us-help-you.md | 4 +- docs/development/issue-labeling.md | 6 +- docs/development/local-development.md | 38 ++- docs/development/minimal-reproductions.md | 16 +- docs/development/remote-development.md | 2 +- docs/development/triage-guide.md | 24 +- docs/development/zod.md | 2 +- docs/usage/bazel.md | 20 +- docs/usage/bot-comparison.md | 6 +- docs/usage/config-presets.md | 30 +-- docs/usage/config-validation.md | 10 +- docs/usage/configuration-options.md | 221 +++++++++--------- docs/usage/configuration-templates.md | 4 +- docs/usage/contributing-to-renovate.md | 22 +- docs/usage/dependency-pinning.md | 40 ++-- docs/usage/docker.md | 30 +-- docs/usage/examples/self-hosting.md | 12 +- docs/usage/faq.md | 12 +- .../getting-started/installing-onboarding.md | 24 +- .../usage/getting-started/private-packages.md | 32 +-- docs/usage/getting-started/running.md | 22 +- docs/usage/getting-started/use-cases.md | 28 +-- docs/usage/gitlab-bot-security.md | 6 +- docs/usage/golang.md | 24 +- docs/usage/key-concepts/automerge.md | 10 +- docs/usage/key-concepts/changelogs.md | 20 +- docs/usage/key-concepts/how-renovate-works.md | 6 +- docs/usage/key-concepts/presets.md | 2 +- docs/usage/key-concepts/pull-requests.md | 12 +- docs/usage/key-concepts/scheduling.md | 6 +- docs/usage/known-limitations.md | 2 +- docs/usage/merge-confidence.md | 2 +- docs/usage/modules/manager/index.md | 2 +- docs/usage/noise-reduction.md | 18 +- docs/usage/nuget.md | 10 +- docs/usage/php.md | 12 +- docs/usage/python.md | 10 +- docs/usage/reading-list.md | 2 +- docs/usage/ruby.md | 6 +- docs/usage/rust.md | 8 +- docs/usage/security-and-permissions.md | 6 +- docs/usage/self-hosted-configuration.md | 60 ++--- docs/usage/self-hosted-experimental.md | 2 +- docs/usage/troubleshooting.md | 12 +- docs/usage/updating-rebasing.md | 10 +- docs/usage/upgrade-best-practices.md | 22 +- 52 files changed, 458 insertions(+), 461 deletions(-) diff --git a/docs/development/adding-a-package-manager.md b/docs/development/adding-a-package-manager.md index 790c257057ef3b..a21a9db4e2c2a2 100644 --- a/docs/development/adding-a-package-manager.md +++ b/docs/development/adding-a-package-manager.md @@ -16,7 +16,7 @@ Common application logic for Renovate, not specific to particular managers, usua The manager's `index.ts` file supports the following values or functions: | Value/function | Optional | Async | -| ----------------------------- | -------- | ----- | +|-------------------------------|----------|-------| | `bumpPackageVersion` | yes | | | `extractPackageFile` | | yes | | `extractAllPackageFiles` | yes | yes | @@ -42,7 +42,7 @@ It takes as arguments the file's content and optionally the file's full file pat The function returns an array of detected or extracted dependencies, including the: - dependency name -- dependency type (dependencies, devDependencies, etc) +- dependency type (dependencies, devDependencies, etc.) - currentValue - versioning used (like SemVer, PEP 440) diff --git a/docs/development/best-practices.md b/docs/development/best-practices.md index b10928dd02ea10..5f23796b3b48f5 100644 --- a/docs/development/best-practices.md +++ b/docs/development/best-practices.md @@ -158,11 +158,11 @@ For `WARN`, `ERROR` and `FATAL log messages use logger metadata. Also use logger metadata the result is a complex metadata object needing a multiple-line pretty stringification. For `INFO` log messages inline the metadata into the log message. -Also inline the metadata if the metadata object is complex. +Also, inline the metadata if the metadata object is complex. `WARN`, `ERROR` and `FATAL` messages are often used in metrics or error catching services. These log messages should have a consistent `msg` component, so they can be automatically grouped or associated. -Metadata that's seperate from its message is hard for humans to read. +Metadata that's separate from its message is hard for humans to read. Try to combine the metadata into the message, unless it's too complex to do so. Good: diff --git a/docs/development/branches-commits.md b/docs/development/branches-commits.md index 71642988b82ffa..1ec1eedc74a58c 100644 --- a/docs/development/branches-commits.md +++ b/docs/development/branches-commits.md @@ -14,7 +14,7 @@ Renovate always creates one commit per branch, even when updating multiple files This keeps Renovate's branches neat, so we can use the following logic: | Last commit in branch made by | Behavior | -| ----------------------------- | ----------------------------------------------------------- | +|-------------------------------|-------------------------------------------------------------| | Renovate | Assume branch is clean | | Someone or something else | Assume branch edited by user, do not push to branch anymore | @@ -25,5 +25,5 @@ This means we let Renovate force-push a single new commit whenever it needs to. For example: 1. Renovate creates a `renovate/jest` branch to update the Jest package to `1.0.1` -1. Renovate later finds a newer `1.1.0` version -1. Renovate force-pushes a new commit for the `1.1.0` update into its `renovate/jest` branch +2. Renovate later finds a newer `1.1.0` version +3. Renovate force-pushes a new commit for the `1.1.0` update into its `renovate/jest` branch diff --git a/docs/development/configuration.md b/docs/development/configuration.md index a238d412964bea..a9cc9578603000 100644 --- a/docs/development/configuration.md +++ b/docs/development/configuration.md @@ -24,7 +24,7 @@ If you need an alternate location or name, set it in the environment variable `R For example `RENOVATE_CONFIG_FILE=myconfig.js` or `RENOVATE_CONFIG_FILE=myconfig.json` and not `RENOVATE_CONFIG_FILE=myconfig`. If none is provided, or the file type is invalid, Renovate will fail. -If you are in an ESM repo (`"type": "module"` in `package.json`) then you must use a `.cjs` extension and set `RENOVATE_CONFIG_FILE`. +If you're in an ESM repo (`"type": "module"` in `package.json`) then you must use a `.cjs` extension and set `RENOVATE_CONFIG_FILE`. For example `RENOVATE_CONFIG_FILE=myconfig.cjs`. Using a configuration file gives you very granular configuration options. diff --git a/docs/development/creating-editing-renovate-presets.md b/docs/development/creating-editing-renovate-presets.md index 1d4e59ad8f87bf..1eb402c7940745 100644 --- a/docs/development/creating-editing-renovate-presets.md +++ b/docs/development/creating-editing-renovate-presets.md @@ -8,7 +8,7 @@ Follow the rules below to increase the chance that your pull request gets merged ## General rules 1. Avoid creating presets for problems which can be fixed upstream -1. The internal preset should be helpful for a significant number of Renovate users +2. The internal preset should be helpful for a significant number of Renovate users ### Specific rules @@ -27,20 +27,20 @@ We have multiple kinds of `group:` presets, with different rules. ##### Rules for `group:*` presets 1. Finally, any other `group:*` presets can be added if they are beneficial to a wide number of users -1. They don't need to be added to `group:recommended`, meaning that users will "opt in" to them one by one and not get them automatically from `config:recommended`, which includes `group:monorepo` and `group:recommended` +2. They don't need to be added to `group:recommended`, meaning that users will "opt in" to them one by one and not get them automatically from `config:recommended`, which includes `group:monorepo` and `group:recommended` #### Replacement presets Rules: 1. Replacement PRs should ideally propose a replacement only once the user is on a compatible version, by specifying a compatible `matchCurrentVersion` constraint -1. If no compatible replacement upgrade is possible, it's acceptable to propose an incompatible one (e.g. a major version upgrade) -1. Replacements should update the user to the first recommended version of the new dependency and not include any new changes - whether breaking or not - if they can be avoided +2. If no compatible replacement upgrade is possible, it's acceptable to propose an incompatible one (e.g. a major version upgrade) +3. Replacements should update the user to the first recommended version of the new dependency and not include any new changes - whether breaking or not - if they can be avoided #### Monorepo presets Rules: 1. The primary use case of monorepo presets is finding packages from the same origin source repository which should be updated together -1. Packages from the same repository which are developed and versioned independently do not need to be grouped as a monorepo, but in many cases we still do -1. Packages from separate repositories but which are released together and dependent on each other may also be added to the "monorepo" definitions even if not strictly true +2. Packages from the same repository which are developed and versioned independently do not need to be grouped as a monorepo, but in many cases we still do +3. Packages from separate repositories but which are released together and dependent on each other may also be added to the "monorepo" definitions even if not strictly true diff --git a/docs/development/design-decisions.md b/docs/development/design-decisions.md index 1e420b232ed7e8..a95dde37c1f4bb 100644 --- a/docs/development/design-decisions.md +++ b/docs/development/design-decisions.md @@ -32,10 +32,10 @@ This means that specific configuration options always override more general conf From most specific to least specific: 1. Update type (e.g. `major`, `minor`, `patch`) -1. Package (e.g. `lodash`, `django`) -1. Manager (e.g. `npm`, `pypi`) -1. Repository config -1. Global configuration +2. Package (e.g. `lodash`, `django`) +3. Manager (e.g. `npm`, `pypi`) +4. Repository config +5. Global configuration ## Automatic discovery of package file locations @@ -49,7 +49,7 @@ You could limit Renovate to only update the `package.json` in the root of the re By default, `renovate` will maintain separate branches for each dependency. So if 20 dependencies need updating, there will be at least 20 branches/PRs. -Although this may seem undesirable, it's even less desirable if all 20 were in the same Pull Request and it's very difficult to work out which upgrade caused the test failure. +Although this may seem undesirable, it's even less desirable if all 20 were in the same Pull Request, and it's very difficult to work out which upgrade caused the test failure. But you can override the default templates for branch name to get 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. @@ -83,7 +83,7 @@ Note: You can configure the branch names by using the string template `branchNam By default, the script does not create a new PR if it finds a previously-closed PR with the same branch name and PR title (assuming the PR title has a version in it). This allows users to close unwelcome upgrade PRs and not worry about them being recreated every run. -## Rebasing Unmergeable Pull Requests +## Rebasing unmergeable Pull Requests With the default behavior of one branch per dependency, it's often the case that a PR gets merge conflicts after an adjacent dependency update is merged. On most platforms you can use a web interface to resolve merge conflicts, but you're still resolving the conflicts manually, which is annoying. @@ -107,6 +107,6 @@ Alternatively, consider using a Configuration File. Renovate uses the following convention for log levels: -- logger.error should only be used for problems that are likely to be a Renovate bug or require Renovate improvements. These are the types of errors that Renovate administrators should be alerted to immediately -- logger.warn should be used for problems that might be a Renovate problem so should be checked periodically in batches +- `logger.error` should only be used for problems that are likely to be a Renovate bug or require Renovate improvements. These are the types of errors that Renovate administrators should be alerted to immediately +- `logger.warn` should be used for problems that might be a Renovate problem so should be checked periodically in batches - For _user_ problems (e.g. configuration errors), these should not warn or error on the server side and instead use logger.info diff --git a/docs/development/help-us-help-you.md b/docs/development/help-us-help-you.md index 9aaea3862a838d..6b3e1df408df43 100644 --- a/docs/development/help-us-help-you.md +++ b/docs/development/help-us-help-you.md @@ -6,7 +6,7 @@ Please follow these points whenever interacting in this repo. ## Be positive and polite This project is open source, and has the work of a lot of contributors who are proud of it. -Please avoid unnecessary criticism, especially if you are new to the project or have not contributed anything. +Please avoid unnecessary criticism, especially if you're new to the project or have not contributed anything. You are welcome to make it better, and do not need to criticize the works of others first. ## Be considerate of the time of people helping you @@ -77,5 +77,5 @@ Don't raise a bug report unless it's definitely a bug. "I don't like this" or "I didn't expect this to happen" is not the same thing as a bug. Many unjustified bug reports are filed because people they think it will get them more attention. -Instead, you may be wasting maintainer time because we have to reclassify your invalid bug report or convert it to a discussion, and you are much less likely to get the attention you're hoping for. +Instead, you may be wasting maintainer time because we have to reclassify your invalid bug report or convert it to a discussion, and you're much less likely to get the attention you're hoping for. If in doubt, start a discussion instead. diff --git a/docs/development/issue-labeling.md b/docs/development/issue-labeling.md index e294b2745eddf0..3e0ac21a13ac5b 100644 --- a/docs/development/issue-labeling.md +++ b/docs/development/issue-labeling.md @@ -185,7 +185,7 @@ Add a label `duplicate` to issues/PRs that are a duplicate of an earlier issue/P Add a label `good first issue` to issues that are small, easy to fix, and do-able for a newcomer. This label is sometimes picked up by tools or websites that try to encourage people to contribute to open source. -Add the label `help wanted` to indicate that we need the original poster or someone else to do some work or it is unlikely to get done. +Add the label `help wanted` to indicate that we need the original poster or someone else to do some work, or it is unlikely to get done. Add a label `auto:bad-vibes` to any discussion containing rude comments such as excessive criticism or ungratefulness. @@ -198,8 +198,8 @@ Add a label `auto:format-code` to any Discussion which needs code formatting. Add a label `auto:logs` to indicate that there's a problem with the logs, and the contributor needs to do one of these things: 1. Provide logs (if there are none yet) -1. Provide more logs (in case current logs are insufficient) -1. Format their logs properly +2. Provide more logs (in case current logs are insufficient) +3. Format their logs properly Add a label `auto:needs-details` to discussions which need more details to move forward. diff --git a/docs/development/local-development.md b/docs/development/local-development.md index 9dadbf02a693f8..0ad7c6aa9b8b21 100644 --- a/docs/development/local-development.md +++ b/docs/development/local-development.md @@ -52,7 +52,7 @@ If you already installed a part, skip the corresponding step. #### VS Code Dev Containers -If you are using [VS Code](https://code.visualstudio.com/) you can skip installing [the prerequisites](#prerequisites) and work in a [development container](https://code.visualstudio.com/docs/devcontainers/containers) instead. +If you're using [VS Code](https://code.visualstudio.com/) you can skip installing [the prerequisites](#prerequisites) and work in a [development container](https://code.visualstudio.com/docs/devcontainers/containers) instead. - Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [check its system requirements](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers#system-requirements) - Open the repository folder in VS Code @@ -96,18 +96,18 @@ The Renovate project uses the [pnpm](https://github.com/pnpm/pnpm) package manag To ensure everything is working properly on your end, you must: 1. Install all dependencies with `pnpm install` -1. Make a build with `pnpm build`, which should pass with no errors -1. Verify all tests pass and have 100% test coverage, by running `pnpm test` -1. Verify the installation by running `pnpm start`. You must see this error: `You must configure a GitHub personal access token` +2. Make a build with `pnpm build`, which should pass with no errors +3. Verify all tests pass and have 100% test coverage, by running `pnpm test` +4. Verify the installation by running `pnpm start`. You must see this error: `You must configure a GitHub personal access token` -Do not worry about the token error for now, as you will be given instructions on how to configure the token a little later down in this document. +Do not worry about the token error for now, as you'll be given instructions on how to configure the token a little later down in this document. You only need to do these steps once. Before you submit a pull request you should: 1. Install newer dependencies with `pnpm install` -1. Run the tests with `pnpm test` +2. Run the tests with `pnpm test` ## Platform Account Setup @@ -132,9 +132,9 @@ 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`. +To make sure everything is working, create a test repo in your account, e.g. like `https://github.com//testrepo1`. Now, add a file called `.nvmrc` with the content `8.13.0`. -Now run against the test repo you created, e.g. `pnpm start r4harry/testrepo1`. +Now run against the test repo you created, e.g. `pnpm start /testrepo1`. If your token is set up correctly, you should find that Renovate created a "Configure Renovate" PR in the `testrepo1`. If this is working then in future you can create other test repos to verify your code changes against. @@ -151,7 +151,7 @@ Refactor PRs should ideally not change or remove tests (adding tests is OK). Run the Jest unit tests with the `pnpm jest` command. You can also run a subset of the Jest tests using file matching, e.g. `pnpm jest composer` or `pnpm jest workers/repository/update/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. +If you get a test failure due to a "snapshot" mismatch, and you're sure that you need to update the snapshot, then you can append `-u` to the end. e.g. `pnpm jest composer -u` would update the saved snapshots for _all_ tests in `**/composer/**`. ### Coverage @@ -215,9 +215,9 @@ You can debug Renovate with Chrome's inspect tool. Here's an example: 1. Open `chrome://inspect` in Chrome, then select "Open dedicated DevTools for Node" -1. Add a `debugger;` statement somewhere in the source code where you want to start debugging -1. Run Renovate using `pnpm debug ...` instead of `pnpm start ...` -1. Select "Resume script execution" in Chrome DevTools and wait for your break point to be triggered +2. Add a `debugger;` statement somewhere in the source code where you want to start debugging +3. Run Renovate using `pnpm debug ...` instead of `pnpm start ...` +4. Select "Resume script execution" in Chrome DevTools and wait for your break point to be triggered ### VS Code @@ -227,14 +227,12 @@ Here's an example: 1. In the configuration file, e.g. `config.js` in the root directory of the project, add `token` with your Personal Access Token 2. In the same configuration file, add `repositories` with the repository you want to test against. The file `config.js` would look something like this: -```javascript -module.exports = { - token: 'xxxxxxxx', - repositories: ['r4harry/testrepo1'], -}; -``` - - + ```javascript + module.exports = { + token: 'xxxxxxxx', + repositories: ['r4harry/testrepo1'], + }; + ``` 3. Set a breakpoint somewhere in the source code and launch the application in debug mode with selected configuration as `debug` 4. Wait for your breakpoint to be triggered diff --git a/docs/development/minimal-reproductions.md b/docs/development/minimal-reproductions.md index ac31a936b0dbe6..cdaf56b12f53bf 100644 --- a/docs/development/minimal-reproductions.md +++ b/docs/development/minimal-reproductions.md @@ -45,12 +45,12 @@ There are two ways to create a minimal reproduction: General steps: 1. Create your minimal reproduction repository on GitHub, only use GitLab or Bitbucket if really needed -1. Use the fewest number of repository files and dependencies -1. Reduce the Renovate config to a minimum -1. Remove private or secret information -1. Create a `readme.md` file that explains the current behavior and expected behavior -1. Set the repository visibility to `public` -1. Give us the link to the repository +2. Use the fewest number of repository files and dependencies +3. Reduce the Renovate config to a minimum +4. Remove private or secret information +5. Create a `readme.md` file that explains the current behavior and expected behavior +6. Set the repository visibility to `public` +7. Give us the link to the repository ### Why we won't use your production repository to debug @@ -85,11 +85,11 @@ After a while, issues without a reproduction may be closed unfixed. ### "I already described what you need in the issue" Thank you for describing your issue in detail. -But we still need a minimal reproduction in a repository, and we'd like you to be the one to make sure it matches both your description as well as expected behavior. +But we still need a minimal reproduction in a repository, and we'd like you to be the one to make sure it matches both your description and expected behavior. ### Forcing Renovate to create a lot of pending updates -Put a old version of a frequently updated dependency in your repository. +Put an old version of a frequently updated dependency in your repository. Set a high `minimumReleaseAge` for that dependency, for example: ```json diff --git a/docs/development/remote-development.md b/docs/development/remote-development.md index d3f6c4ca0f3683..956a3ca77e59d3 100644 --- a/docs/development/remote-development.md +++ b/docs/development/remote-development.md @@ -29,7 +29,7 @@ You'll use the same code editor and have the same config as all other developers - Waiting for the remote container to start - If your internet is down you can't work -- If Codespaces is down you can't work +- If GitHub Codespaces is down you can't work ## GitHub Codespaces diff --git a/docs/development/triage-guide.md b/docs/development/triage-guide.md index 12b33d82d9c94f..ddf90b304d00cf 100644 --- a/docs/development/triage-guide.md +++ b/docs/development/triage-guide.md @@ -13,20 +13,20 @@ The general triage workflow is similar for bug reports and feature requests, but Take the following steps on an incoming bug report: 1. Determine if this is a valid bug report at all, close and optionally delete obvious spam. -1. If poster is asking a configuration question, or has not made a convincing case that it's really a bug, then convert to a "Ask a question" discussion, add either a response or at least a note that it's been converted. -1. Determine if this is a duplicate of an open issue/discussion, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. -1. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. -1. Check if the _relevant_ logs are provided. If not apply the `auto:logs` label. +2. If poster is asking a configuration question, or has not made a convincing case that it's really a bug, then convert to an "Ask a question" discussion, add either a response or at least a note that it's been converted. +3. Determine if this is a duplicate of an open issue/discussion, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. +4. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. +5. Check if the _relevant_ logs are provided. If not apply the `auto:logs` label. ### Triaging feature requests workflow Take the following steps on an incoming feature request: 1. Determine if this is a valid feature request at all, close and optionally delete obvious spam. -1. If poster is asking a configuration question, or has not made a convincing case that it's really a feature request, then convert to a "Ask a question" discussion, add either a response or at least a note that it's been converted. -1. Determine if this is a duplicate of an open issue, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. -1. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. -1. Make a best-effort judgement if this is a reasonable feature to put into Renovate. If in doubt, let the core maintainers decide. +2. If poster is asking a configuration question, or has not made a convincing case that it's really a feature request, then convert to an "Ask a question" discussion, add either a response or at least a note that it's been converted. +3. Determine if this is a duplicate of an open issue, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. +4. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. +5. Make a best-effort judgement if this is a reasonable feature to put into Renovate. If in doubt, let the core maintainers decide. ## Creating new issues from discussions @@ -40,7 +40,7 @@ In short: users create discussions, and when it's clear what we need to do, the ## What a triagist is allowed to do -If you've been given triage rights, you are allowed to do the following things: +If you've been given triage rights, you're allowed to do the following things: - Apply labels to issues/discussions - Close, reopen, and assign all issues and pull requests @@ -100,8 +100,8 @@ You can assign whoever makes sense. If you see an issue/discussion that's an obvious duplicate: 1. Attach a `duplicate` label -1. Use the "Duplicate of" functionality [GitHub docs, about duplicate issues and pull requests](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-duplicate-issues-and-pull-requests) -1. Close the issue/discussion +2. Use the "Duplicate of" functionality [GitHub docs, about duplicate issues and pull requests](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-duplicate-issues-and-pull-requests) +3. Close the issue/discussion Follow the same workflow to mark duplicate PRs. @@ -116,7 +116,7 @@ Ideally warn the user with an `auto:bad-vibes` label first, and then use the `au ### Going from `status:requirements` to actionable issue -One of the most important non-code contributions people can do is help features and fixes go from `status:requirements` to a actionable issue. +One of the most important non-code contributions people can do is help features and fixes go from `status:requirements` to an actionable issue. We use the label `status:requirements` to mean "more information or research is needed before someone could start coding this". It can sometimes be an oversight of the maintainers, but more often it's because there are requirements or edge cases to consider and the user hasn't got an opinion or time to think about them and contribute enough. diff --git a/docs/development/zod.md b/docs/development/zod.md index 265e8c93f664d3..70890b233f1d4a 100644 --- a/docs/development/zod.md +++ b/docs/development/zod.md @@ -100,7 +100,7 @@ const Box = z.object({ red: z.number(), green: z.number(), blue: z.number(), - }) + }), weight: z.number(), }); diff --git a/docs/usage/bazel.md b/docs/usage/bazel.md index 4a95e19c55e2e1..469bd4db672605 100644 --- a/docs/usage/bazel.md +++ b/docs/usage/bazel.md @@ -10,9 +10,9 @@ Renovate upgrades dependencies in Bazel `WORKSPACE` files and `MODULE.bazel` fil ## How it works 1. Bazel support is enabled automatically -1. Renovate searches the repository for any `WORKSPACE` and `MODULE.bazel` files -1. Renovate extracts the dependencies it finds from the files (see below for the supported dependency declarations) -1. Renovate updates old dependencies to the latest version +2. Renovate searches the repository for any `WORKSPACE` and `MODULE.bazel` files +3. Renovate extracts the dependencies it finds from the files (see below for the supported dependency declarations) +4. Renovate updates old dependencies to the latest version ## Bazel module (`MODULE.bazel`) support @@ -20,13 +20,13 @@ Renovate upgrades dependencies in Bazel `WORKSPACE` files and `MODULE.bazel` fil Renovate searches [Bazel registries](https://bazel.build/external/registry) to find new Bazel module versions. You customize the registries your Bazel workspace uses by including [`--registry`](https://bazel.build/reference/command-line-reference#flag--registry) entries in your [`.bazelrc` files](https://bazel.build/run/bazelrc). -Renovate checks the workspace's `.bazelrc` files for custom registry entries. +Renovate checks the `.bazelrc` files within the workspace for custom registry entries. If no registries are found, Renovate defaults to the [Bazel Central Registry](https://bcr.bazel.build/). Here are some important points about Renovate's Bazel registry searches. Renovate: -- uses _all_ `--registry` values found in a workspace's `.bazelrc` file +- uses _all_ `--registry` values found in the `.bazelrc` file within the workspace - uses any files that are transitively imported by a `.bazelrc` file - only uses `--registry` values that are not associated with [a configuration](https://bazel.build/run/bazelrc#config) - queries the registries in the order that they are found in the `.bazelrc` file @@ -48,7 +48,7 @@ build --registry=https://example.com/custom_registry The final registry list is: 1. `` -1. `` +2. `` #### Example: registry entries using Bazel configuration @@ -165,8 +165,8 @@ For example, `_http_archive` is treated the same as `http_archive`. Renovate updates any `git_repository` declaration that has the following: 1. `name` -1. `remote` matching `https://github.com//.git` -1. `tag` using a valid SemVer +2. `remote` matching `https://github.com//.git` +3. `tag` using a valid SemVer e.g.: @@ -185,8 +185,8 @@ Renovate uses the list of **tags** on the remote repository (GitHub) to detect a Renovate updates any `http_archive` or `http_file` declaration that has the following: 1. `name` -1. `url` matching `https://github.com///releases/download//.tar.gz` -1. `sha256` +2. `url` matching `https://github.com///releases/download//.tar.gz` +3. `sha256` e.g.: diff --git a/docs/usage/bot-comparison.md b/docs/usage/bot-comparison.md index 227542e02c7946..f296b0fc2dea98 100644 --- a/docs/usage/bot-comparison.md +++ b/docs/usage/bot-comparison.md @@ -8,7 +8,7 @@ If you see anything wrong on this page, please let us know by creating a [Discus ## Table of features | Feature | Renovate | Dependabot | -| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Dependency Dashboard | Yes | No | | Grouped updates | Yes, use community-provided groups, or create your own | Yes, create [`groups`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups) manually | | Upgrades common monorepo packages at once | Yes | No | @@ -68,7 +68,7 @@ If you're an advanced user, you may use the [`dependabot-core` repository](https ### Show changelogs | Feature | Renovate | Dependabot | -| ------------------------------------- | ---------------------------- | ------------------------------- | +|---------------------------------------|------------------------------|---------------------------------| | Link to GitHub release | Yes, to specific release tag | Yes, to "releases landing page" | | Link to GitHub's comparing changes UI | Yes | Yes | | Release notes | Yes | Yes | @@ -153,7 +153,7 @@ You can self-host Dependabot on other platforms than GitHub but none are officia If you want to customize Dependabot, or self-host on another platform, you can use [`dependabot-core`](https://github.com/dependabot/dependabot-core). Quote from the `dependabot-core` readme: -> It [`dependabot-core`] currently supports opening Pull Requests against repositories hosted on GitHub, Github Enterprise, Azure DevOps, GitLab, BitBucket, and AWS CodeCommit. +> It [`dependabot-core`] currently supports opening Pull Requests against repositories hosted on GitHub, GitHub Enterprise, Azure DevOps, GitLab, BitBucket, and AWS CodeCommit. #### `dependabot-script` diff --git a/docs/usage/config-presets.md b/docs/usage/config-presets.md index 54dad726f10e56..fe73205c20a941 100644 --- a/docs/usage/config-presets.md +++ b/docs/usage/config-presets.md @@ -43,7 +43,7 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c ### GitHub | name | example use | preset | resolves as | filename | Git tag | -| ------------------------------------------- | -------------------------------- | --------- | ---------------------------- | --------------- | -------------- | +|---------------------------------------------|----------------------------------|-----------|------------------------------|-----------------|----------------| | GitHub default | `github>abc/foo` | `default` | `https://github.com/abc/foo` | `default.json` | Default branch | | GitHub with preset name | `github>abc/foo:xyz` | `xyz` | `https://github.com/abc/foo` | `xyz.json` | Default branch | | GitHub with preset name (JSON5) | `github>abc/foo:xyz.json5` | `xyz` | `https://github.com/abc/foo` | `xyz.json5` | Default branch | @@ -51,36 +51,36 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c | GitHub default with a tag | `github>abc/foo#1.2.3` | `default` | `https://github.com/abc/foo` | `default.json` | `1.2.3` | | GitHub with preset name with a tag | `github>abc/foo:xyz#1.2.3` | `xyz` | `https://github.com/abc/foo` | `xyz.json` | `1.2.3` | | GitHub with preset name and path with a tag | `github>abc/foo//path/xyz#1.2.3` | `xyz` | `https://github.com/abc/foo` | `path/xyz.json` | `1.2.3` | -| GitHub with subpreset name and tag | `github>abc/foo:xyz/sub#1.2.3` | `sub` | `https://github.com/abc/foo` | `xyz.json` | `1.2.3` | +| GitHub with sub-preset name and tag | `github>abc/foo:xyz/sub#1.2.3` | `sub` | `https://github.com/abc/foo` | `xyz.json` | `1.2.3` | ### GitLab | name | example use | preset | resolves as | filename | Git tag | -| ------------------------------------------- | -------------------------------- | --------- | ---------------------------- | --------------- | -------------- | +|---------------------------------------------|----------------------------------|-----------|------------------------------|-----------------|----------------| | GitLab default | `gitlab>abc/foo` | `default` | `https://gitlab.com/abc/foo` | `default.json` | Default branch | | GitLab with preset name | `gitlab>abc/foo:xyz` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json` | Default branch | | GitLab with preset name (JSON5) | `gitlab>abc/foo:xyz.json5` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json5` | Default branch | | GitLab default with a tag | `gitlab>abc/foo#1.2.3` | `default` | `https://gitlab.com/abc/foo` | `default.json` | `1.2.3` | | GitLab with preset name with a tag | `gitlab>abc/foo:xyz#1.2.3` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.2.3` | | GitLab with preset name and path with a tag | `gitlab>abc/foo//path/xyz#1.2.3` | `xyz` | `https://gitlab.com/abc/foo` | `path/xyz.json` | `1.2.3` | -| GitLab with subpreset name and tag | `gitlab>abc/foo:xyz/sub#1.2.3` | `sub` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.2.3` | +| GitLab with sub-preset name and tag | `gitlab>abc/foo:xyz/sub#1.2.3` | `sub` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.2.3` | ### Gitea | name | example use | preset | resolves as | filename | Git tag | -| ------------------------------------------ | ------------------------------- | --------- | --------------------------- | --------------- | -------------- | +|--------------------------------------------|---------------------------------|-----------|-----------------------------|-----------------|----------------| | Gitea default | `gitea>abc/foo` | `default` | `https://gitea.com/abc/foo` | `default.json` | Default branch | | Gitea with preset name | `gitea>abc/foo:xyz` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json` | Default branch | | Gitea with preset name (JSON5) | `gitea>abc/foo:xyz.json5` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json5` | Default branch | | Gitea default with a tag | `gitea>abc/foo#1.2.3` | `default` | `https://gitea.com/abc/foo` | `default.json` | `1.2.3` | | Gitea with preset name with a tag | `gitea>abc/foo:xyz#1.2.3` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json` | `1.2.3` | | Gitea with preset name and path with a tag | `gitea>abc/foo//path/xyz#1.2.3` | `xyz` | `https://gitea.com/abc/foo` | `path/xyz.json` | `1.2.3` | -| Gitea with subpreset name and tag | `gitea>abc/foo:xyz/sub#1.2.3` | `sub` | `https://gitea.com/abc/foo` | `xyz.json` | `1.2.3` | +| Gitea with sub-preset name and tag | `gitea>abc/foo:xyz/sub#1.2.3` | `sub` | `https://gitea.com/abc/foo` | `xyz.json` | `1.2.3` | ### Self-hosted Git | name | example use | preset | resolves as | filename | Git tag | -| ------------------------------------------ | ------------------------------- | --------- | ------------------------------------ | --------------- | -------------- | +|--------------------------------------------|---------------------------------|-----------|--------------------------------------|-----------------|----------------| | Local default | `local>abc/foo` | `default` | `https://github.company.com/abc/foo` | `default.json` | Default branch | | Local with preset path | `local>abc/foo:xyz` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json` | Default branch | | Local with preset path (JSON5) | `local>abc/foo:xyz.json5` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json5` | Default branch | @@ -88,11 +88,11 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c | Local default with a tag | `local>abc/foo#1.2.3` | `default` | `https://github.company.com/abc/foo` | `default.json` | `1.2.3` | | Local with preset name with a tag | `local>abc/foo:xyz#1.2.3` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json` | `1.2.3` | | Local with preset name and path with a tag | `local>abc/foo//path/xyz#1.2.3` | `xyz` | `https://github.company.com/abc/foo` | `path/xyz.json` | `1.2.3` | -| Local with subpreset name and tag | `local>abc/foo:xyz/sub#1.2.3` | `sub` | `https://github.company.com/abc/foo` | `xyz.json` | `1.2.3` | +| Local with sub-preset name and tag | `local>abc/foo:xyz/sub#1.2.3` | `sub` | `https://github.company.com/abc/foo` | `xyz.json` | `1.2.3` | !!! tip - You can't combine the path and sub-preset syntaxes. + You can't combine the path and sub-preset syntax. This means that anything in the form `provider>owner/repo//path/to/file:subsubpreset` is not supported. One workaround is to use distinct files instead of sub-presets. @@ -112,7 +112,7 @@ It mostly uses Renovate config defaults but adds a few smart customizations such ## How to Use Preset Configs By default, Renovate App's onboarding PR suggests the `["config:recommended]"` preset. -If you're self hosting, and want to use the `config:recommended` preset, then you must add `"onboardingConfig": { "extends": ["config:recommended"] }` to your bot's config. +If you're self-hosting, and want to use the `config:recommended` preset, then you must add `"onboardingConfig": { "extends": ["config:recommended"] }` to your bot's config. Read the [Full Config Presets](./presets-config.md) page to learn more about our `config:` presets. @@ -137,7 +137,7 @@ You put `schedule:nonOfficeHours` in the `extends` array of your `renovate.json` ## Preset Parameters -If you browse the "default" presets, you will see some that have parameters, e.g.: +If you browse the "default" presets, you'll see some that have parameters, e.g.: ```json { @@ -163,7 +163,7 @@ Here is how you would use these in your Renovate config: In short, the number of `{{argx}}` parameters 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. +If you find that you're 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, see [Contributing to presets](#contributing-to-presets). ## GitHub-hosted Presets @@ -172,7 +172,7 @@ To host your preset config on GitHub: - Create a new repository. Normally you'd call it `renovate-config` but it can be named anything - Add configuration files to this new repo for any presets you want to share. For the default preset, `default.json` will be checked. For named presets, `.json` will be loaded. For example, loading preset `library` would load `library.json`. No other files are necessary. -- In other repos, reference it in an extends array like "github>owner/name", for example: +- In other repos, reference it in an extends array like `github>owner/name`, for example: ```json { @@ -215,11 +215,11 @@ Please consider contributing it to the [Renovate repository](https://github.com/ Create a [discussion](https://github.com/renovatebot/renovate/discussions) to propose your preset to the Renovate maintainers. The maintainers can also help improve the preset, and let you know where to put it in the code. -If you are proposing a "monorepo" preset addition then it's OK to raise a PR directly as that can be more efficient than a GitHub Discussion. +If you're proposing a "monorepo" preset addition then it's OK to raise a PR directly as that can be more efficient than a GitHub Discussion. ## Group/Organization level presets -Whenever repository onboarding happens, Renovate checks for a a default config to extend. +Whenever repository onboarding happens, Renovate checks for a default config to extend. Renovate will check for a repository called `renovate-config` with a `default.json` file in the parent user/group/org of the repository. On platforms that support nested groups (e.g. GitLab), Renovate will check for this repository at each level of grouping, from nearest to furthest, and use the first one it finds. On all platforms, it will then look for a repository named like `.{{platform}}` (e.g. `.github`) with a `renovate-config.json`, under the same top-level user/group/org. diff --git a/docs/usage/config-validation.md b/docs/usage/config-validation.md index f6b6f36a362f11..6179d6120111a4 100644 --- a/docs/usage/config-validation.md +++ b/docs/usage/config-validation.md @@ -56,12 +56,12 @@ Renovate can validate configuration changes in Pull Requests when you use a spec Follow these steps to validate your configuration: 1. Create a new Git branch that matches the `{{branchPrefix}}reconfigure` pattern. For example, if you're using the default prefix `renovate/`, your branch name must be `renovate/reconfigure`. -1. Commit your updated Renovate config file to this branch, and push it to your Git hosting platform. +2. Commit your updated Renovate config file to this branch, and push it to your Git hosting platform. The next time Renovate runs on that repo it will: 1. Search for a branch that matches the special reconfigure pattern. -1. Check for a config file in the reconfigure branch. Renovate can even find a renamed configuration file (compared to the config file in the default branch). -1. Add a passing or failing status to the branch, depending on the outcome of the config validation run. -1. If there's an _open_ pull request with validation errors from the _reconfigure_ branch then Renovate comments in the PR with details. -1. Validate each commit the next time Renovate runs on the repository, until the PR is merged. +2. Check for a config file in the reconfigure branch. Renovate can even find a renamed configuration file (compared to the config file in the default branch). +3. Add a passing or failing status to the branch, depending on the outcome of the config validation run. +4. If there's an _open_ pull request with validation errors from the _reconfigure_ branch then Renovate comments in the PR with details. +5. Validate each commit the next time Renovate runs on the repository, until the PR is merged. diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index f93316f3c55efb..821ccd168675c7 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -11,15 +11,15 @@ Any config you define applies to the whole repository (e.g. if you have a monore You can store your Renovate configuration file in one of these locations: 1. `renovate.json` -1. `renovate.json5` -1. `.github/renovate.json` -1. `.github/renovate.json5` -1. `.gitlab/renovate.json` -1. `.gitlab/renovate.json5` -1. `.renovaterc` -1. `.renovaterc.json` -1. `.renovaterc.json5` -1. `package.json` _(within a `"renovate"` section)_ +2. `renovate.json5` +3. `.github/renovate.json` +4. `.github/renovate.json5` +5. `.gitlab/renovate.json` +6. `.gitlab/renovate.json5` +7. `.renovaterc` +8. `.renovaterc.json` +9. `.renovaterc.json5` +10. `package.json` _(within a `"renovate"` section)_ !!! warning @@ -207,11 +207,11 @@ So for example you could choose to automerge all (passing) `devDependencies` onl **Automerge and GitHub branch protection rules** -You must select at least one status check in the _Require status checks to pass before merging_ section of your branch protection rules on GitHub, if you match all three conditions: +You must select at least one status check in the _"Require status checks to pass before merging"_ section of your branch protection rules on GitHub, if you match all three conditions: - `automerge=true` - `platformAutomerge=true`, Renovate defaults to `true` -- You use GitHub's _Require status checks to pass before merging_ branch protection rule +- You use GitHub's _"Require status checks to pass before merging"_ branch protection rule If you don't select any status check, and you use platform automerge, then GitHub might automerge PRs with failing tests! @@ -352,14 +352,14 @@ Example config: !!! warning - Leaving PRs/branches as unlimited or as a high number increases the time it takes for Renovate to process a repository. + Leaving PRs/branches as unlimited or as a high number, increases the time it takes for Renovate to process a repository. If you find that Renovate is too slow when rebasing out-of-date branches, decrease the `branchConcurrentLimit`. If you have too many concurrent branches which rebase themselves each run, Renovate can take a lot of time to rebase. Solutions: - Decrease the concurrent branch limit (note: this won't go and delete any existing, so won't have an effect until you either merge or close existing ones manually) -- Remove automerge and/or automatic rebasing (set `rebaseWhen` to `conflicted`). However if you have branch protection saying PRs must be up to date then it's not ideal to remove automatic rebasing +- Remove automerge and/or automatic rebasing (set `rebaseWhen` to `conflicted`). However, if you have branch protection saying PRs must be up-to-date then it's not ideal to remove automatic rebasing ## branchName @@ -375,7 +375,7 @@ If you truly need to configure this then it probably means either: ## branchNameStrict -If `true`, Renovate removes special characters when slugifying the branch name: +If `true`, Renovate removes special characters when slugify-ing the branch name: - all special characters are removed - only alphabetic characters are allowed @@ -406,12 +406,11 @@ Instead, set the old `branchPrefix` value as `branchPrefixOld` to allow Renovate ## 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 is an advanced field, and it's recommended you seek a config review before applying it. ## bumpVersion -Currently this setting supports `helmv3`, `npm`, `nuget`, `maven`, `pep621` and `sbt` only, so raise a feature request if you have a use for it with other package managers. -Currently this setting supports `helmv3`, `npm`, `nuget`, `maven`, `pep621`, `poetry` and `sbt` only, so raise a feature request if you have a use for it with other package managers. +Currently, this setting supports `helmv3`, `npm`, `nuget`, `maven`, `pep621`, `poetry` and `sbt` only, so raise a feature request if you have a use for it with other package managers. Its purpose is if you want Renovate to update the `version` field within your package file 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. @@ -442,9 +441,9 @@ For example, To add `[skip ci]` to every commit you could configure: } ``` -Another example would be if you want to configure a DCO signoff to each commit. +Another example would be if you want to configure a DCO sign-off to each commit. -If you want Renovate to signoff its commits, add the [`:gitSignOff` preset](./presets-default.md#gitsignoff) to your `extends` array: +If you want Renovate to sign off its commits, add the [`:gitSignOff` preset](./presets-default.md#gitsignoff) to your `extends` array: ```json { @@ -459,7 +458,7 @@ If you want Renovate to signoff its commits, add the [`:gitSignOff` preset](./pr !!! warning We deprecated editing the `commitMessage` directly, and we recommend you stop using this config option. - Instead use config options like `commitMessageAction`, `commitMessageExtra`, and so on, to create the commit message you want. + Instead, use config options like `commitMessageAction`, `commitMessageExtra`, and so on, to create the commit message you want. ## commitMessageAction @@ -537,7 +536,7 @@ If enabled, all issues created by Renovate are set as confidential, even in a pu !!! note The Dependency Dashboard issue will also be confidential. - By default issues created by Renovate are visible to all users. + By default, issues created by Renovate are visible to all users. !!! note @@ -574,13 +573,13 @@ After we changed the [`baseBranches`](#basebranches) feature, the Renovate confi !!! note When you close a config migration PR, Renovate ignores it forever. - This also means that Renovate won't create a config migration PR in future. + This also means that Renovate won't create a config migration PR in the future. If you closed the PR by accident, find the closed PR and re-name the PR title to get a new PR. ## configWarningReuseIssue -Renovate's default behavior 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. +Renovate's default behavior is to reuse/reopen a single Config Warning issue in each repository 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 @@ -623,10 +622,10 @@ Renovate supports two options: - `none`: No release filtering (all releases allowed) - `strict`: If the release's constraints match the package file constraints, then it's included -More advanced filtering options may come in future. +More advanced filtering options may come in the future. There must be a `constraints` object in your Renovate config, or constraints detected from package files, for this to work. -This feature is limited to the folllowing datasources: +This feature is limited to the following datasources: - `jenkins-plugins` - `npm` @@ -646,13 +645,13 @@ When `constraintsFiltering=strict`, the following logic applies: Here are some examples: -| Your repo engines.node | Dependency release engines.node | Result | -| ------------------------ | ------------------------------- | -------- | -| `18` | `16 \|\| 18` | allowed | -| `^18.10.0` | `>=18` | allowed | -| `^16.10.0 \|\| >=18.0.0` | `>= 16.0.0` | allowed | -| `>=16` | `16 \|\| 18` | filtered | -| `16` | `^16.10.0` | filtered | +| Your repo `engines.node` | Dependency release `engines.node` | Result | +|--------------------------|-----------------------------------|----------| +| `18` | `16 \|\| 18` | allowed | +| `^18.10.0` | `>=18` | allowed | +| `^16.10.0 \|\| >=18.0.0` | `>= 16.0.0` | allowed | +| `>=16` | `16 \|\| 18` | filtered | +| `16` | `^16.10.0` | filtered | When using with `npm`, we recommend you: @@ -675,7 +674,7 @@ You can define custom managers to handle: - Proprietary file formats or conventions - Popular file formats not yet supported as a manager by Renovate -Currently we only have one custom manager. +Currently, we only have one custom manager. The `regex` manager which is based on using Regular Expression named capture groups. You must have a named capture group matching (e.g. `(?.*)`) _or_ configure its corresponding template (e.g. `depNameTemplate`) for these fields: @@ -763,8 +762,8 @@ As example the following configuration will update all three lines in the Docker ```dockerfile title="Dockerfile" FROM amd64/ubuntu:18.04 -ENV GRADLE_VERSION=6.2 # gradle-version/gradle&versioning=maven -ENV NODE_VERSION=10.19.0 # github-tags/nodejs/node&versioning=node +ENV GRADLE_VERSION=6.2 # gradle-version/gradle&versioning=maven +ENV NODE_VERSION=10.19.0 # github-tags/nodejs/node&versioning=node ``` #### recursive @@ -963,7 +962,7 @@ Supported fields: This field is used to build a `registryUrl` for the dependency. It is not needed if either: -- The dependency can be found with the default `registryUrls` of the datasource (e.g. npmjs registry if the datasource is `npm`), or +- The dependency can be found with the default `registryUrls` of the datasource (e.g. the `npmjs.org` registry if the datasource is `npm`), or - The matching groups you specified as part of the matching already include a `registryUrl` group As this is a template it can be dynamically set. E.g. add the `packageName` as part of the URL: @@ -1186,7 +1185,7 @@ Example: } ``` -To enable custom managers you will need to add `custom.` prefix before their names +To enable custom managers you'll need to add `custom.` prefix before their names Example: @@ -1201,9 +1200,9 @@ For the full list of available managers, see the [Supported Managers](modules/ma ## encrypted Before you put any secrets in your repository configuration, encrypt the secrets. -You can encrypt secrets using either a HTML page, or the CLI. +You can encrypt secrets using either our webpage, or the CLI. -To encrypt secrets for the Mend Renovate App for github.com with a HTML page, go to [app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt) and complete the form. +To encrypt secrets for the Mend Renovate App for github.com using our webpage, go to [app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt) and complete the form. If you're self-hosting Renovate, you may download and edit the form, to use your own PGP public key. You can also encrypt secrets from the CLI, using the `curl`, `echo`, `jq`, `gpg`, `grep` and `tr` CLI programs. @@ -1265,7 +1264,7 @@ Learn how to use presets by reading the [Key concepts, Presets](./key-concepts/p Only use this config option when the raw version strings from the datasource do not match the expected format that you need in your package file. You must define a "named capture group" called `version` like in the examples below. -For example, to extract only the major.minor precision from a GitHub release, the following would work: +For example, to extract only the `major.minor` precision from a GitHub release, the following would work: ```json { @@ -1325,7 +1324,7 @@ Renovate can fetch changelogs when they are hosted on one of these platforms: - GitHub (.com and Enterprise Server) - GitLab (.com and CE/EE) -If you are running on any platform except `github.com`, you need to [configure a Personal Access Token](./getting-started/running.md#githubcom-token-for-release-notes) to allow Renovate to fetch changelogs notes from `github.com`. +If you're running on any platform except `github.com`, you need to [configure a Personal Access Token](./getting-started/running.md#githubcom-token-for-changelogs) to allow Renovate to fetch changelogs notes from `github.com`. !!! note @@ -1344,7 +1343,7 @@ Here Renovate looks for _any_ `go.mod` file. In this case you can probably keep using that default `fileMatch`. 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 have 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. +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 have 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 `['(^|/|\\.)([Dd]ocker|[Cc]ontainer)file$', '(^|/)([Dd]ocker|[Cc]ontainer)file[^/]*$']`. @@ -1372,7 +1371,7 @@ For now, you can only use this option on the GitLab platform. For `followTag` to work, the datasource must support distribution streams or tags, like for example npm does. -The main usecase is to follow a pre-release tag of a dependency, say TypeScripts's `"insiders"` build: +The main usecase is to follow a pre-release tag of a dependency, say TypeScript's `"insiders"` build: ```json { @@ -1475,7 +1474,7 @@ Example: ## gitLabIgnoreApprovals Ignore the default project level approval(s), so that Renovate bot can automerge its merge requests, without needing approval(s). -Under the hood, it creates a MR-level approval rule where `approvals_required` is set to `0`. +Under the hood, it creates an MR-level approval rule where `approvals_required` is set to `0`. This option works only when `automerge=true`, `automergeType=pr` or `automergeType=branch`, and `platformAutomerge=true`. Also, approval rules overriding should not be [prevented in GitLab settings](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/settings.html#prevent-editing-approval-rules-in-merge-requests). @@ -1576,8 +1575,8 @@ Example for configuring `docker` auth: If multiple `hostRules` match a request, then they will be applied in the following order/priority: 1. rules with only `hostType` specified -1. rules with only `matchHost` specified (sorted by `matchHost` length if multiple match) -1. rules with both `matchHost` and `hostType` specified (sorted by `matchHost` length if multiple match) +2. rules with only `matchHost` specified (sorted by `matchHost` length if multiple match) +3. rules with both `matchHost` and `hostType` specified (sorted by `matchHost` length if multiple match) To disable requests to a particular host, you can configure a rule like: @@ -1645,7 +1644,7 @@ For example to also skip 404 responses then configure the following: ### 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. +By default, Renovate will only abort for known public hosts, which has the downside that transient errors for other hosts can cause auto-closing of PRs. To abort Renovate runs for HTTP failures from _any_ host: @@ -1747,7 +1746,7 @@ Example config: ``` Use an exact host for `matchHost` and not a domain (e.g. `api.github.com` as shown above and not `github.com`). -Do not combine with `hostType` in the same rule or it won't work. +Do not combine with `hostType` in the same rule, or it won't work. ### maxRequestsPerSecond @@ -1848,14 +1847,14 @@ For example, using this option could be used whenever authentication using Git f Supported artifactAuth and hostType combinations: | artifactAuth | hostTypes | -| ------------ | ------------------------------------------- | +|--------------|---------------------------------------------| | `composer` | `gitlab`, `packagist`, `github`, `git-tags` | ### matchHost This can be a base URL (e.g. `https://api.github.com`) or a hostname like `github.com` or `api.github.com`. If the value starts with `http(s)` then it will only match against URLs which start with the full base URL. -Otherwise, it will be matched by checking if the URL's hostname matches the `matchHost` directly or ends with it. +Otherwise, it will be matched by checking if the hostname of the URL matches the `matchHost` directly or ends with it. When checking the end of the hostname, a single dot is prefixed to the value of `matchHost`, if one is not already present, to ensure it can only match against whole domain segments. The `matchHost` URL must be the same as the `registryUrl` set in `.npmrc`, or you'll get authentication issues when the artifacts are updated when yarn or npm runs. @@ -1925,7 +1924,7 @@ If for some reason you wish to _force_ deprecated updates with Renovate, you can ## 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: +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 { @@ -1949,7 +1948,7 @@ The above is the same as if you wrote this package rule: ## ignorePaths Renovate will extract dependencies from every file it finds in a repository, unless that file is explicitly ignored. -With this setting you can selectively ignore package files that would normally be "autodiscovered" and updated by Renovate. +With this setting you can selectively ignore package files that would normally be auto-discovered and updated by Renovate. For instance if you have a project with an `"examples/"` directory you wish to ignore: @@ -1960,7 +1959,7 @@ For instance if you have a project with an `"examples/"` directory you wish to i ``` Renovate's default ignore is `node_modules` and `bower_components` only. -If you are extending from the popular `config:recommended` preset then it adds ignore patterns for `vendor`, `examples`, `test(s)` and `fixtures` directories too. +If you're extending from the popular `config:recommended` preset then it adds ignore patterns for `vendor`, `examples`, `test(s)` and `fixtures` directories too. ## ignorePlugins @@ -1969,14 +1968,14 @@ Applicable for Composer only for now. ## ignorePrAuthor -This is usually needed if someone needs to migrate bot accounts, including from the Mend Renovate App to self-hosted. +This is usually needed if someone needs to migrate bot accounts, including from the Mend Renovate App to the self-hosted variant. If `ignorePrAuthor` is configured to true, it means Renovate will fetch the entire list of repository PRs instead of optimizing to fetch only those PRs which it created itself. -You should only want to enable this if you are changing the bot account (e.g. from `@old-bot` to `@new-bot`) and want `@new-bot` to find and update any existing PRs created by `@old-bot`. +You should only want to enable this if you're changing the bot account (e.g. from `@old-bot` to `@new-bot`) and want `@new-bot` to find and update any existing PRs created by `@old-bot`. It's recommended to revert this setting once that transition period is over and all old PRs are resolved. ## ignorePresets -Use this if you are extending a complex preset but don't want to use every "sub preset" that it includes. +Use this if you're extending a complex preset but don't want to use every "sub preset" that it includes. For example, consider this config: ```json @@ -2007,7 +2006,7 @@ Applicable for npm and Composer only for now. Set this to `true` if running scri ## ignoreTests -Currently Renovate's default behavior is to only automerge if every status check has succeeded. +Currently, Renovate's default behavior is to only automerge if every status check has succeeded. Setting this option to `true` means that Renovate will ignore _all_ status checks. You can set this if you don't have any status checks but still want Renovate to automerge PRs. @@ -2016,7 +2015,7 @@ Beware: configuring Renovate to automerge without any tests can lead to broken b ## 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. +Renovate will also not "jump" unstable versions automatically, e.g. if you're 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. @@ -2026,7 +2025,7 @@ Also check out the `followTag` configuration option above if you wish Renovate t If you wish for Renovate to process only select paths in the repository, use `includePaths`. Alternatively, if you need to _exclude_ certain paths in the repository then consider `ignorePaths` instead. -If you are more interested in including only certain package managers (e.g. `npm`), then consider `enabledManagers` instead. +If you're more interested in including only certain package managers (e.g. `npm`), then consider `enabledManagers` instead. ## internalChecksAsSuccess @@ -2041,7 +2040,7 @@ Change this setting to `true` if you want to use internal Renovate checks toward ## internalChecksFilter This setting determines whether Renovate controls when and how filtering of internal checks are performed, particularly when multiple versions of the same update type are available. -Currently this applies to the `minimumReleaseAge` check only. +Currently, this applies to the `minimumReleaseAge` check only. - `none`: No filtering will be performed, and the highest release will be used regardless of whether it's pending or not - `strict`: All pending releases will be filtered. PRs will be skipped unless a non-pending version is available @@ -2055,7 +2054,7 @@ We recommend that you use the `strict` mode, and enable the `dependencyDashboard By default, Renovate won't add any labels to PRs. If you want Renovate to add labels to PRs it creates 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. +However, you can also fully override them on a per-package basis. Consider this example: @@ -2137,7 +2136,7 @@ If this is set _and_ an update has a release timestamp header, then Renovate wil Note: Renovate will wait for the set duration to pass for each **separate** version. Renovate does not wait until the package has seen no releases for x time-duration(`minimumReleaseAge`). `minimumReleaseAge` is not intended to help with slowing down fast releasing project updates. -If you want to slow down PRs for a specific package, setup a custom schedule for that package. +If you want to slow down PRs for a specific package, set up a custom schedule for that package. Read [our selective-scheduling help](./noise-reduction.md#selective-scheduling) to learn how to set the schedule. If the time since the release is less than the set `minimumReleaseAge` a "pending" status check is added to the branch. @@ -2191,7 +2190,7 @@ Add to this object if you wish to define rules that apply only to minor updates. ## npmToken See [Private npm module support](./getting-started/private-packages.md) for details on how this is used. -Typically you would encrypt it and put it inside the `encrypted` object. +Typically, you would encrypt it and put it inside the `encrypted` object. ## npmrc @@ -2201,7 +2200,7 @@ See [Private npm module support](./getting-started/private-packages.md) for deta This option exists to provide flexibility about whether `npmrc` strings in config should override `.npmrc` files in the repo, or be merged with them. In some situations you need the ability to force override `.npmrc` contents in a repo (`npmrcMerge=false`) while in others you might want to simply supplement the settings already in the `.npmrc` (`npmrcMerge=true`). -A use case for the latter is if you are a Renovate bot admin and wish to provide a default token for `npmjs.org` without removing any other `.npmrc` settings which individual repositories have configured (such as scopes/registries). +A use case for the latter is if you're a Renovate bot admin and wish to provide a default token for `npmjs.org` without removing any other `.npmrc` settings which individual repositories have configured (such as scopes/registries). If `false` (default), it means that defining `config.npmrc` will result in any `.npmrc` file in the repo being overridden and its values ignored. If configured to `true`, it means that any `.npmrc` file in the repo will have `config.npmrc` prepended to it before running `npm`. @@ -2211,7 +2210,7 @@ If configured to `true`, it means that any `.npmrc` file in the repo will have ` Renovate integrates with [OSV](https://osv.dev/), an open-source vulnerability database, to check if extracted dependencies have known vulnerabilities. Set `osvVulnerabilityAlerts` to `true` to get pull requests with vulnerability fixes (once they are available). -You will only get OSV-based vulnerability alerts for _direct_ dependencies. +You'll only get OSV-based vulnerability alerts for _direct_ dependencies. Renovate only queries the OSV database for dependencies that use one of these datasources: - [`crate`](./modules/datasource/crate/index.md) @@ -2260,7 +2259,7 @@ For Maven dependencies, the package name is ``, e.g. `"match Note how the above uses `matchPackageNames` instead of `matchPackagePatterns` because it is an exact match package name. This is the equivalent of defining `"matchPackagePatterns": ["^aws\-sdk$"]`. -However you can mix together both `matchPackageNames` and `matchPackagePatterns` in the same package rule and the rule will be applied if _either_ match. +However, you can mix together both `matchPackageNames` and `matchPackagePatterns` in the same package rule and the rule will be applied if _either_ match. Example: ```json @@ -2278,7 +2277,7 @@ Example: The above rule will group together the `neutrino` package and any package matching `@neutrino/*`. File name matches are convenient to use if you wish to apply configuration rules to certain package or lock 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: +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 { @@ -2292,7 +2291,7 @@ For example, if you have an `examples` directory and you want all updates to tho ``` If you wish to limit Renovate to apply configuration rules to certain files in the root repository directory, you have to use `matchFileNames` with a `minimatch` pattern (which can include an exact file name match). -For example you have multiple `package.json` and want to use `dependencyDashboardApproval` only on the root `package.json`: +For example, you have multiple `package.json` and want to use `dependencyDashboardApproval` only on the root `package.json`: ```json { @@ -2364,7 +2363,7 @@ Use the syntax `!/ /` like the following: ### matchDepTypes Use this field if you want to limit a `packageRule` to certain `depType` values. -Invalid if used outside of a `packageRule`. +Invalid if used outside a `packageRule`. ### excludeDepNames @@ -2977,7 +2976,7 @@ It falls back to Renovate-based automerge if the platform-native automerge is no You can also fine-tune the behavior by setting `packageRules` if you want to use it selectively (e.g. per-package). Note that the outcome of `rebaseWhen=auto` can differ when `platformAutomerge=true`. -Normally when you set `rebaseWhen=auto` Renovate rebases any branch that's behind the base branch automatically, and some people rely on that. +Normally when you set `rebaseWhen=auto` Renovate will rebase any branch that's behind the base branch automatically, and some people rely on that. This behavior is no longer guaranteed when `platformAutomerge` is `true` because the platform might automerge a branch which is not up-to-date. For example, GitHub might automerge a Renovate branch even if it's behind the base branch at the time. @@ -2998,7 +2997,7 @@ This way Renovate can use GitHub's [Commit signing support for bots and other Gi Table with options: | Name | Description | -| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | `bundlerConservative` | Enable conservative mode for `bundler` (Ruby dependencies). This will only update the immediate dependency in the lockfile instead of all subdependencies. | | `gomodMassage` | Enable massaging `replace` directives before calling `go` commands. | | `gomodTidy` | Run `go mod tidy` after Go module updates. This is implicitly enabled for major module updates when `gomodUpdateImportPaths` is enabled. | @@ -3156,7 +3155,7 @@ This setting tells Renovate _when_ to create PRs: - `immediate` (default): Renovate creates PRs immediately after creating the corresponding branch - `not-pending`: Renovate waits until status checks have completed (passed or failed) before raising the PR -- `status-success`: Renovate only creates PRs if/when the the test pass +- `status-success`: Renovate only creates PRs if/when the test pass - `approval`: Renovate creates branches for updates immediately, but creates the PR _after_ getting Dependency Dashboard approval When prCreation is set to `immediate`, you'll get a Pull Request and possible associated notification right away when a new update is available. @@ -3193,10 +3192,10 @@ Slowing Renovate down can be handy when you're onboarding a repository with a lo What may happen if you don't set a `prHourlyLimit`: 1. Renovate creates an Onboarding PR -1. You merge the onboarding PR to activate Renovate -1. Renovate creates a "Pin Dependencies" PR (if needed) -1. You merge the "Pin Dependencies" PR -1. Renovate creates every single upgrade PR needed, which can be a lot +2. You merge the onboarding PR to activate Renovate +3. Renovate creates a "Pin Dependencies" PR (if needed) +4. You merge the "Pin Dependencies" PR +5. Renovate creates every single upgrade PR needed, which can be a lot The above may cause: @@ -3216,7 +3215,7 @@ Now you can merge the PRs at a do-able rate, once the tests pass. ## 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. +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. This is why we configured an upper limit for how long we wait until creating a PR. @@ -3226,15 +3225,15 @@ This is why we configured an upper limit for how long we wait until creating a P ## prPriority Sometimes Renovate needs to rate limit its creation of PRs, e.g. hourly or concurrent PR limits. -By default, Renovate sorts/prioritizes based on the update type, going from smallest update to biggest update. +By default, Renovate sorts/prioritizes based on the update type, going from the smallest update to the biggest update. Renovate creates update PRs in this order: 1. `pinDigest` -1. `pin` -1. `digest` -1. `patch` -1. `minor` -1. `major` +2. `pin` +3. `digest` +4. `patch` +5. `minor` +6. `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 setting a negative value will make dependencies sort last, while higher values sort first. @@ -3280,7 +3279,7 @@ Set `pruneBranchAfterAutomerge` to `false` to keep the branch after automerging. ## pruneStaleBranches -Configure to `false` to disable deleting orphan branches and autoclosing PRs. +Configure to `false` to disable deleting orphan branches and auto-closing of PRs. Defaults to `true`. ## rangeStrategy @@ -3298,11 +3297,11 @@ Behavior: Renovate's `"auto"` strategy works like this for npm: 1. Widen `peerDependencies` -1. If an existing range already ends with an "or" operator like `"^1.0.0 || ^2.0.0"`, then Renovate widens it into `"^1.0.0 || ^2.0.0 || ^3.0.0"` -1. Otherwise, if the update is outside the existing range, Renovate replaces the range. So `"^2.0.0"` is replaced by `"^3.0.0"` -1. Finally, if the update is in-range, Renovate will update the lockfile with the new exact version. +2. If an existing range already ends with an "or" operator like `"^1.0.0 || ^2.0.0"`, then Renovate widens it into `"^1.0.0 || ^2.0.0 || ^3.0.0"` +3. Otherwise, if the update is outside the existing range, Renovate replaces the range. So `"^2.0.0"` is replaced by `"^3.0.0"` +4. Finally, if the update is in-range, Renovate will update the lockfile with the new exact version. -By default, Renovate assumes that if you are using ranges then it's because you want them to be wide/open. +By default, Renovate assumes that if you're using ranges then it's because you want them to be wide/open. 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. @@ -3318,13 +3317,13 @@ Using the `in-range-only` strategy may result in you being multiple releases beh ## 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"` but you can configure it to anything you want by changing this `rebaseLabel` field. +By default, this label is `"rebase"` but you can configure it to anything you want by changing this `rebaseLabel` field. ## rebaseWhen Possible values and meanings: -- `auto`: Renovate will autodetect the best setting. It will use `behind-base-branch` if configured to automerge or repository has been set to require PRs to be up to date. Otherwise, `conflicted` will be used instead +- `auto`: Renovate will autodetect the best setting. It will use `behind-base-branch` if configured to automerge or repository has been set to require PRs to be up-to-date. Otherwise, `conflicted` will be used instead - `never`: Renovate will never rebase the branch or update it unless manually requested - `conflicted`: Renovate will rebase only if the branch is conflicted - `behind-base-branch`: Renovate will rebase whenever the branch falls 1 or more commit behind its base branch @@ -3345,7 +3344,7 @@ This feature used to be called `recreateClosed`. By default, Renovate detects if it proposed an update to a project before, and will not propose the same update again. For example the Webpack 3.x case described in the [`separateMajorMinor`](#separatemajorminor) documentation. You can use `recreateWhen` to customize this behavior down to a per-package level. -For example we override it to `always` in the following cases where branch names and PR titles must be reused: +For example, we override it to `always` in the following cases where branch names and PR titles must be reused: - Package groups - When pinning versions @@ -3404,7 +3403,7 @@ In case there is a need to configure them manually, it can be done using this `r } ``` -The field supports multiple URLs but it is datasource-dependent on whether only the first is used or multiple. +The field supports multiple URLs, but it is datasource-dependent on whether only the first is used or multiple. ## replacement @@ -3537,18 +3536,18 @@ Renovate does not support scheduled minutes or "at an exact time" granularity. ## semanticCommitScope -By default you will see Angular-style commit prefixes like `"chore(deps):"`. +By default, you'll 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):"`. +By default, you'll 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. +If you're using a semantic prefix for your commits, then you'll 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 `enabled`, then the `semanticCommitScope` and `semanticCommitType` fields will be used for each commit message and PR title. @@ -3563,7 +3562,7 @@ If instead you applied the 3.0.0 update then Renovate would clean up the unneede It is recommended that you leave this option 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. +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 get 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 the base branch once it's tested. After that, Renovate will resume providing you updates to 3.x again! @@ -3576,13 +3575,13 @@ If you want to enforce grouped package updates, you need to set this option to ` ## 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`. +E.g., if you're 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 configure this option to `true`. ## separateMultipleMajor Configure this to `true` if you wish to get one PR for every separate major version upgrade of a dependency. -e.g. if you are on webpack@v1 currently then default behavior is a PR for upgrading to webpack@v3 and not for webpack@v2. +E.g. if you're on webpack@v1 currently then default behavior 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. ## statusCheckNames @@ -3656,14 +3655,14 @@ To opt in to letting Renovate update internal package versions normally, set thi ## 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 `rebaseWhen=behind-base-branch` and the base branch is updated so you want Renovate PRs to be rebased. +However, there are cases where updates might be desirable - e.g. if you have configured `prCreation=not-pending`, or you have `rebaseWhen=behind-base-branch` and the base 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`. +If you wish to disable all updates outside scheduled hours then configure this field to `false`. ## updatePinnedDependencies -By default, Renovate will try to update all detected dependencies, regardless of whether they are defined using pinned single versions (e.g. `1.2.3`) or constraints/ranges (e.g. (`^1.2.3`). +By default, Renovate will try to update all detected dependencies, regardless of whether they are defined using pinned single versions (e.g. `1.2.3`) or constraints/ranges (e.g. `^1.2.3`). You can set this option to `false` if you wish to disable updating for pinned (single version) dependencies specifically. ## useBaseBranchConfig @@ -3739,13 +3738,13 @@ When combined, `extractVersion` is applied to datasource results first, and then ## versioning Usually, each language or package manager has a specific type of "versioning": -JavaScript uses npm's SemVer implementation, Python uses pep440, etc. +JavaScript uses the npm SemVer implementation, Python uses pep440, etc. Renovate also uses custom versioning, like `"docker"` to address the most common way people tag versions using Docker, and `"loose"` as a fallback that tries SemVer first. -Otherwise Renovate does its best to sort and compare. +Otherwise, Renovate does its best to sort and compare. By exposing `versioning` to config, you can override the default versioning for a package manager if needed. -We do not recommend overriding the default versioning, 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. +We do not recommend overriding the default versioning, 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. Renovate supports 4-part versions (1.2.3.4) in full for the NuGet package manager. Other managers can use the `"loose"` versioning fallback: the first 3 parts are used as the version, all trailing parts are used for alphanumeric sorting. @@ -3757,11 +3756,11 @@ For this to work, you must enable the [Dependency graph](https://docs.github.com Follow these steps: 1. While logged in to GitHub, navigate to your repository -1. Select the "Settings" tab -1. Select "Code security and analysis" in the sidebar -1. Enable the "Dependency graph" -1. Enable "Dependabot alerts" -1. If you're running Renovate in app mode: make sure the app has `read` permissions for "Dependabot alerts". +2. Select the "Settings" tab +3. Select "Code security and analysis" in the sidebar +4. Enable the "Dependency graph" +5. Enable "Dependabot alerts" +6. If you're running Renovate in app mode: make sure the app has `read` permissions for "Dependabot alerts". If you're the account administrator, browse to the app (for example [the Mend Renovate App](https://github.com/apps/renovate)), select "Configure", and then scroll down to the "Permissions" section and make sure that `read` access to "Dependabot alerts" is mentioned Once the above conditions are met, and you got one or more vulnerability alerts from GitHub for this repository, then Renovate tries to raise fix PRs. diff --git a/docs/usage/configuration-templates.md b/docs/usage/configuration-templates.md index c995e940791d0c..c650510983d4bd 100644 --- a/docs/usage/configuration-templates.md +++ b/docs/usage/configuration-templates.md @@ -14,7 +14,7 @@ If you change the `branchPrefix` while you have ignored some upgrades (closed PR `branchName` default value is `{{{branchPrefix}}}{{{additionalBranchPrefix}}}{{{branchTopic}}}`. -The most common branch name you will see looks like this: `renovate/react-18.x`. +The most common branch name you'll see looks like this: `renovate/react-18.x`. In this example, the `branchPrefix` is the default `renovate/`, `additionalBranchPrefix` is empty, and `branchTopic` is `react-18.x`. Most users will be happy with the default `branchPrefix` of `renovate/`, but you can change this if you don't like the default. @@ -23,7 +23,7 @@ The onboarding PR will always use `renovate/configure`. `additionalBranchPrefix` is optional and by default is empty. -`branchTopic` depends on the package manager and upgrade type, so you will see a lot of variety. +`branchTopic` depends on the package manager and upgrade type, so you'll see a lot of variety. This is probably a setting you want to change yourself. Be careful, and consider creating a new "config help" post at the [discussions tab in the Renovate repository](https://github.com/renovatebot/renovate/discussions) to get help from the Renovate team with your config. diff --git a/docs/usage/contributing-to-renovate.md b/docs/usage/contributing-to-renovate.md index cd4090b16814f6..fe2820ef0aca38 100644 --- a/docs/usage/contributing-to-renovate.md +++ b/docs/usage/contributing-to-renovate.md @@ -8,8 +8,8 @@ The [`docs/development/` directory of the `renovatebot/renovate` repository](htt ### Read this first 1. [Contributing guide](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) -1. [Best practices](https://github.com/renovatebot/renovate/blob/main/docs/development/best-practices.md) -1. [Local Development](https://github.com/renovatebot/renovate/blob/main/docs/development/local-development.md) or [Remote Development](https://github.com/renovatebot/renovate/blob/main/docs/development/remote-development.md) +2. [Best practices](https://github.com/renovatebot/renovate/blob/main/docs/development/best-practices.md) +3. [Local Development](https://github.com/renovatebot/renovate/blob/main/docs/development/local-development.md) or [Remote Development](https://github.com/renovatebot/renovate/blob/main/docs/development/remote-development.md) ### Creating/editing Renovate preset @@ -22,11 +22,11 @@ The [`docs/development/` directory of the `renovatebot/renovate` repository](htt ### Background information 1. [Design Decisions](https://github.com/renovatebot/renovate/blob/main/docs/development/design-decisions.md) -1. [Zod schema guideline](https://github.com/renovatebot/renovate/blob/main/docs/development/zod.md) -1. [Branches and commits behavior](https://github.com/renovatebot/renovate/blob/main/docs/development/branches-commits.md) -1. [Configuration](https://github.com/renovatebot/renovate/blob/main/docs/development/configuration.md) -1. [Static Data](https://github.com/renovatebot/renovate/blob/main/docs/development/static-data.md) -1. [How to bump Renovate to next NodeJS LTS release](https://github.com/renovatebot/renovate/blob/main/docs/development/bump-node-major.md) +2. [Zod schema guideline](https://github.com/renovatebot/renovate/blob/main/docs/development/zod.md) +3. [Branches and commits behavior](https://github.com/renovatebot/renovate/blob/main/docs/development/branches-commits.md) +4. [Configuration](https://github.com/renovatebot/renovate/blob/main/docs/development/configuration.md) +5. [Static Data](https://github.com/renovatebot/renovate/blob/main/docs/development/static-data.md) +6. [How to bump Renovate to next NodeJS LTS release](https://github.com/renovatebot/renovate/blob/main/docs/development/bump-node-major.md) ## I want to write documentation @@ -37,11 +37,11 @@ Read the [Contributing guide](https://github.com/renovatebot/renovate/blob/main/ Start by reading: 1. [Contributing guide](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) -1. [Triage guide](https://github.com/renovatebot/renovate/blob/main/docs/development/triage-guide.md) -1. [Issue labeling](https://github.com/renovatebot/renovate/blob/main/docs/development/issue-labeling.md) +2. [Triage guide](https://github.com/renovatebot/renovate/blob/main/docs/development/triage-guide.md) +3. [Issue labeling](https://github.com/renovatebot/renovate/blob/main/docs/development/issue-labeling.md) You may need to direct a Renovate user to one of these pages: 1. [About minimal reproductions](https://github.com/renovatebot/renovate/blob/main/docs/development/minimal-reproductions.md) -1. [New package manager questionnaire](https://github.com/renovatebot/renovate/blob/main/docs/development/new-package-manager-template.md) -1. [Help Us Help You](https://github.com/renovatebot/renovate/blob/main/docs/development/help-us-help-you.md) +2. [New package manager questionnaire](https://github.com/renovatebot/renovate/blob/main/docs/development/new-package-manager-template.md) +3. [Help Us Help You](https://github.com/renovatebot/renovate/blob/main/docs/development/help-us-help-you.md) diff --git a/docs/usage/dependency-pinning.md b/docs/usage/dependency-pinning.md index 185d136c22202f..63a9ea3f22f70f 100644 --- a/docs/usage/dependency-pinning.md +++ b/docs/usage/dependency-pinning.md @@ -15,9 +15,9 @@ If you don't want to read the in-depth discussion, you can skip ahead to our rec 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`. +For instance, if you run `npm install foobar` you'll 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". -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. +The project will automatically use `1.1.1` if it's released, or `1.2.0`, or `1.2.1`, etc. - meaning you'll 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. @@ -27,14 +27,14 @@ If instead you "pin" your dependencies rather than use ranges, it means you use ## 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. +By "automatically", we mean that any time you run `npm install` you'll 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. +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'll 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 @@ -44,7 +44,7 @@ In this case, it is usually a bad idea to pin all your dependencies because it w For example, you might have pinned `foobar` to version `1.1.0` and another author pinned his/her `foobar` dependency to `1.2.2`. Any user of both your packages will end up with npm trying 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. +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? @@ -59,7 +59,7 @@ This benefits when upgrading versions as well as when rolling back in case of pr ### Upgrading pinned versions -Let's say that a "faulty" version `1.2.0` of `foobar` is released and it breaks one of your tests. +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 `main` 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`. @@ -67,9 +67,9 @@ You would need to manually check and work out which dependency caused the failur Consider the same situation if instead you were _pinning_ dependency versions. Your `main` branch would not be broken because it's pinned to `foobar@1.1.0` - instead you'd 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. -By pinning dependencies you know exactly what you're running and you know exactly what failed. +By pinning dependencies you know exactly what you're running, and you know exactly what failed. -Now consider a similar theoretical scenario where `foobar@1.2.0` is faulty but it is _not_ caught by any of your automated tests. +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. @@ -78,10 +78,10 @@ Like before, you need to manually work out which dependency caused it - assuming Alternatively, if you were instead pinning `foobar` then you would get a PR for `foobar@1.2.0` which awaits your approval. So first of all, you can choose to read the changelogs 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 did not catch the fault before merging, you're 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 `main`. -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! +When the next release of `foobar` comes out (e.g. `1.2.1`) you'll 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. @@ -101,7 +101,7 @@ To some extent this is simply a trade-off for having your dependencies pinned an 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. +If your build/tests pass, then you're fine. Consider enabling automerge for all lint packages to save yourself the work of manually approving the update each time. In this case you might wake up to 5/10 of your overnight Pull Requests having already merged themselves. @@ -118,7 +118,7 @@ In that case, you could set `automergeType` to `branch`, which means Renovate wi - Push the commit directly to `main` if tests pass, or - Raise a PR only if tests failed -With this approach, updates will be essentially "silent" - causing no notifications - but you will be able to see each commit on `main` of course. +With this approach, updates will be essentially "silent" - causing no notifications - but you'll be able to see each commit on `main` of course. ### Scheduling @@ -135,7 +135,7 @@ To learn all about controlling Renovate's schedule, read the [key concepts, sche ### 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 one branch combined even if multiple packages have updates available. +You can add a package rule in our Renovate configuration to group these together, and you'll get one branch combined even if multiple packages have updates available. ## Pinning Dependencies and Lock Files @@ -156,14 +156,14 @@ To reuse an earlier example, this means that you could have `foobar@^1.1.0` in y If a lock file gets out of sync with its `package.json`, it can no longer be guaranteed to lock anything, and the `package.json` will be the source of truth for installs. -The lock file has only delayed the inevitable problem, and provides much less visibility than `package.json`, because it's not designed to be human readable and is quite dense. +The lock file has only delayed the inevitable problem, and provides much less visibility than `package.json`, because it's not designed to be human-readable and is quite dense. ![all-dead](assets/images/all-dead.jpg){ loading=lazy } If the `package.json` has 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 downside is _how_ you'll discover the break eventually. The easiest case is if for some reason you _need_ to upgrade `foobar`, e.g. for a new feature it has, 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. @@ -180,7 +180,7 @@ You also may be missing out on really important patches you're not even aware of 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`. +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. So the lock file does not solve the same SemVer problems that pinning solves - but it compliments it. @@ -194,7 +194,7 @@ e.g. are you interested in a Renovate feature where you get a lockfile-only PR a A good argument made by [@LinusU](https://github.com/LinusU) is: -> Pinning will only protect you against breakage in a, in many cases, small percentage of your packages. If you for example have installed Express and pinned it, you will only protect yourself against a bad Express release, it will not help with the 30 dependencies that Express has. +> In many cases, pinning will only protect you against breakage in a small percentage of your packages. If you for example have installed Express and pinned it, you'll only protect yourself against a bad Express release, it will not help with the 30 dependencies that Express has. > > 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. @@ -208,7 +208,7 @@ 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?). +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 dependencies for breaks than I am, to use the example above. @@ -223,11 +223,11 @@ 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. +As noted earlier, when you pin dependencies then you'll 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. +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. 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 958a4d00370a1d..2171f8ce59fa7f 100644 --- a/docs/usage/docker.md +++ b/docs/usage/docker.md @@ -16,20 +16,20 @@ Renovate supports upgrading dependencies in various types of Docker definition f ## How It Works 1. Renovate searches in each repository for any files matching each manager's configured `fileMatch` pattern(s) -1. Matching files are parsed, Renovate checks if the file(s) has any Docker image references (e.g. `FROM` lines in a `Dockerfile`) -1. If the image tag in use "looks" like a version (e.g. `myimage:1`, `myimage:1.1`, `myimage:1.1.0`, `myimage:1-onbuild`) then Renovate checks the Docker registry for upgrades (e.g. from `myimage:1.1.0` to `myimage:1.2.0`) +2. Matching files are parsed, Renovate checks if the file(s) has any Docker image references (e.g. `FROM` lines in a `Dockerfile`) +3. If the image tag in use "looks" like a version (e.g. `myimage:1`, `myimage:1.1`, `myimage:1.1.0`, `myimage:1-onbuild`) then Renovate checks the Docker registry for upgrades (e.g. from `myimage:1.1.0` to `myimage:1.2.0`) ## Preservation of Version Precision By default, Renovate preserves the precision level specified in the Docker images. For example, if the existing image is pinned at `myimage:1.1` then Renovate only proposes upgrades to `myimage:1.2` or `myimage:1.3`. -This means that you will not get upgrades to a more specific versions like `myimage:1.2.0` or `myimage:1.3.0`. +This means that you'll not get upgrades to a more specific versions like `myimage:1.2.0` or `myimage:1.3.0`. Renovate does not yet support "pinning" an imprecise version to a precise version, e.g. from `myimage:1.2` to `myimage:1.2.0`, but it's a feature we'd like to work on 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. `1.2.0-alpine`. -By default Renovate assumes suffixes indicate compatibility, for this reason Renovate will not _change_ any suffixes. +By default, Renovate assumes suffixes indicate compatibility, for this reason Renovate will not _change_ any suffixes. Renovate will update `1.2.0-alpine` to `1.2.1-alpine` but never updates to `1.2.1` or `1.2.1-stretch` as that would change the suffix. If this behavior does not suit a particular package you have, Renovate allows you to customize the `versioning` scheme it uses. @@ -91,13 +91,13 @@ When pinning a digest, Renovate retains the Docker tag in the `FROM` line for re ## Digest Updating -If you follow our advice to replace a tag like `node:14` with a pinned digest like `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you will get Renovate PRs whenever the `node:14` image is updated on Docker Hub. +If you follow our advice to replace a tag like `node:14` with a pinned digest like `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you'll get Renovate PRs whenever the `node:14` image is updated on Docker Hub. Previously this update would have been "invisible" to you - one day you pull code that represents `node:14.15.0` and the next day you pull code that represents `node:14.15.1`. But you can never be sure, especially as Docker caches. Maybe some of your colleagues, or worse still your build machine, are stuck on an older version with a security vulnerability. -By pinning to a digest instead, you will get these updates via Pull Requests, or even committed directly to your repository if you enable branch automerge for convenience. +By pinning to a digest instead, you'll get these updates via Pull Requests, or even committed directly to your repository if you enable branch automerge for convenience. This makes sure everyone on your team uses the latest versions. ## Version Upgrading @@ -276,8 +276,8 @@ Google Artifact Registry supports `_json_key_base64` and a base64 encoded servic If all your dependencies are on the Google Artifact Registry, you can base64 encode and use the service account directly: 1. Download your JSON service account and store it on your machine. Make sure that the service account has `read` (and only `read`) permissions to your artifacts -1. Base64 encode the service account credentials by running `cat service-account.json | base64` -1. Add the encoded service account to your configuration file +2. Base64 encode the service account credentials by running `cat service-account.json | base64` +3. Add the encoded service account to your configuration file 1. If you want to add it to your self-hosted configuration file: @@ -293,7 +293,7 @@ If all your dependencies are on the Google Artifact Registry, you can base64 enc } ``` - 1. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: + 2. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: ```json { @@ -312,7 +312,7 @@ If all your dependencies are on the Google Artifact Registry, you can base64 enc If you have dependencies on Google Container Registry (and Artifact Registry) you need to use `_json_key` and a slightly different encoding: 1. Download your JSON service account and store it on your machine. Make sure that the service account has `read` (and only `read`) permissions to your artifacts -1. Open the file and prefix the content with `_json_key:`. The file should look like this: +2. Open the file and prefix the content with `_json_key:`. The file should look like this: ``` _json_key:{ @@ -329,8 +329,8 @@ If you have dependencies on Google Container Registry (and Artifact Registry) yo } ``` -1. Base64 encode the prefixed service account credentials by running `cat prefixed-service-account.json | base64` -1. Add the prefixed and encoded service account to your configuration file +3. Base64 encode the prefixed service account credentials by running `cat prefixed-service-account.json | base64` +4. Add the prefixed and encoded service account to your configuration file 1. If you want to add it to your self-hosted configuration file: @@ -346,7 +346,7 @@ If you have dependencies on Google Container Registry (and Artifact Registry) yo } ``` - 1. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: + 2. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: ```json { @@ -364,12 +364,12 @@ If you have dependencies on Google Container Registry (and Artifact Registry) yo ##### Using short-lived access tokens -Assume you are running GitLab CI in the Google Cloud, and you are storing your Docker images in the Google Container Registry (GCR). +Assume you're running GitLab CI in the Google Cloud, and you're storing your Docker images in the Google Container Registry (GCR). Access to the GCR uses Bearer token based authentication. This token can be obtained by running `gcloud auth print-access-token`, which requires the Google Cloud SDK to be installed. -The token expires after 60 minutes so you cannot store it in a variable for subsequent builds (like you can with `RENOVATE_TOKEN`). +The token expires after 60 minutes, so you cannot store it in a variable for subsequent builds (like you can with `RENOVATE_TOKEN`). When running Renovate in this context the Google access token must be retrieved and injected into the `hostRules` configuration just before Renovate is started. diff --git a/docs/usage/examples/self-hosting.md b/docs/usage/examples/self-hosting.md index 2d5311451725f9..30f30c3ed93acc 100644 --- a/docs/usage/examples/self-hosting.md +++ b/docs/usage/examples/self-hosting.md @@ -158,7 +158,7 @@ spec: Do you know how to get `daniel-shuy/renovate` version `3` working? Then please open a pull request to update the docs and close [Renovate issue #13428](https://github.com/renovatebot/renovate/issues/13428). -If you are using CircleCI, you can use the third-party [daniel-shuy/renovate](https://circleci.com/developer/orbs/orb/daniel-shuy/renovate) orb to run a self-hosted instance of Renovate on CircleCI. +If you're using CircleCI, you can use the third-party [daniel-shuy/renovate](https://circleci.com/developer/orbs/orb/daniel-shuy/renovate) orb to run a self-hosted instance of Renovate on CircleCI. By default, the orb looks for the self-hosted configuration file in the project root, but you can specify another path to the configuration file with the `config_file_path` parameter. @@ -230,7 +230,7 @@ If you want to override the cache directory then set your own value for `cacheDi The following example uses the Renovate CLI tool, which you can install by running `npm i -g renovate`. -If running your own Renovate bot then you will need a user account that Renovate will run as. +If running your own Renovate bot then you'll need a user account that Renovate will run as. We recommend you create and use a dedicated account for the bot, e.g. name it `renovate-bot` if on your own instance. Create and save a PAT for this account. @@ -275,13 +275,13 @@ Only add the script to `cron` after you checked it works. !!! note The GitHub.com token as an environment variable is needed to fetch changelogs 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 Server, GitLab, Azure DevOps, or Bitbucket. + You don't need to add it if you're already running the bot against github.com, but you do need to add it if you're using GitHub Enterprise Server, GitLab, Azure DevOps, or Bitbucket. ## Kubernetes for GitLab, using Git over SSH This section describes how to use a Git binary with SSH for GitLab, to avoid API shortcomings. -You need to first create a SSH key, then add the public part to GitLab (see this [guide](https://docs.gitlab.com/ee/ssh/)). +You first need to create an SSH key, then add the public part to GitLab (see this [guide](https://docs.gitlab.com/ee/ssh/)). Then, you need to create the secret to add the SSH key, and the following config to your container: @@ -393,7 +393,7 @@ When you use `LOG_LEVEL=debug` and `LOG_FORMAT=json`, Renovate uses numbers in t The logging level output is controlled by the Bunyan logging library. | Level | Meaning | -| ----: | ------- | +|------:|---------| | 10 | trace | | 20 | debug | | 30 | info | @@ -416,7 +416,7 @@ This means Renovate can safely connect to systems using that certificate or cert Helper programs like Git and npm use the system trust store. For those programs to trust a self-signed certificate you must add it to the systems trust store. -On Ubuntu/Debian and many Linux-based systems, this can be done by copying the self-signed certificate (e.g. `self-signed-certificate.crt`) to `/usr/local/share/ca-certificates/` and running [`update-ca-certificates`](https://manpages.ubuntu.com/manpages/xenial/man8/update-ca-certificates.8.html) to update the system trust store afterwards. +On Ubuntu/Debian and many Linux-based systems, this can be done by copying the self-signed certificate (e.g. `self-signed-certificate.crt`) to `/usr/local/share/ca-certificates/` and running [`update-ca-certificates`](https://manpages.ubuntu.com/manpages/xenial/man8/update-ca-certificates.8.html) to update the system trust store afterward. ### Renovate Docker image diff --git a/docs/usage/faq.md b/docs/usage/faq.md index 940aa16db1b5fb..d32a918b74be26 100644 --- a/docs/usage/faq.md +++ b/docs/usage/faq.md @@ -10,7 +10,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 -- Find and process all package files (e.g. `package.json`, `composer.json`, `Dockerfile`, etc) in each repository +- Find and process all package files (e.g. `package.json`, `composer.json`, `Dockerfile`, etc.) in each repository - Use separate branches/PR for each dependency - Use separate branches for each _major_ version of each dependency - Pin devDependencies to a single version, rather than use ranges @@ -27,7 +27,7 @@ The Renovate team only fixes bugs in an older version if: - some critical bug needs to be fixed and the new major is blocked If you're using the Mend Renovate App, you don't need to do anything, as the Renovate maintainers update it regularly. -If you're self hosting Renovate, use the latest release if possible. +If you're self-hosting Renovate, use the latest release if possible. ## When is the Mend Renovate App updated with new Renovate versions? @@ -39,7 +39,7 @@ Major releases of Renovate are held back until the maintainers are reasonably ce ## Renovate core features not supported on all platforms | Feature | Platforms which lack feature | See Renovate issue(s) | -| --------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | +|-----------------------|------------------------------------------------------------|--------------------------------------------------------------| | Dependency Dashboard | Azure, Bitbucket, Bitbucket Server | [#9592](https://github.com/renovatebot/renovate/issues/9592) | | The Mend Renovate App | Azure, Bitbucket, Bitbucket Server, Forgejo, Gitea, GitLab | | @@ -48,7 +48,7 @@ Major releases of Renovate are held back until the maintainers are reasonably ce Some major platform features are not supported at all by Renovate. | Feature name | Platform | See Renovate issue(s) | -| --------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-----------------------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Jira issues | Bitbucket | [#20568](https://github.com/renovatebot/renovate/issues/20568) | | Jira issues | Bitbucket Server | [#3796](https://github.com/renovatebot/renovate/issues/3796) | | Merge trains | GitLab | [#5573](https://github.com/renovatebot/renovate/issues/5573) | @@ -67,7 +67,7 @@ We replaced `master` with `main` in our documentation where possible. A branch name has no special meaning within the Git program, it's only a name. The base branch could be called `trunk` or `mainline` or `prod`, and Git would work just as well. -## What if I need to .. ? +## What if I need to ... ? ### Troubleshoot Renovate @@ -106,7 +106,7 @@ The basic idea is that you create a new `packageRules` entry and describe what k ``` You may even configure Renovate bot to ask for approval for _all_ updates. -The `dependencyDashboardApproval` config option is outside of a `packageRules` array, and so applies to all updates: +The `dependencyDashboardApproval` config option is outside a `packageRules` array, and so applies to all updates: ```json { diff --git a/docs/usage/getting-started/installing-onboarding.md b/docs/usage/getting-started/installing-onboarding.md index 75ccffebc1246f..4d8d43c7841e97 100644 --- a/docs/usage/getting-started/installing-onboarding.md +++ b/docs/usage/getting-started/installing-onboarding.md @@ -4,7 +4,7 @@ Renovate administrators can configure Renovate to either "autodiscover" installed repositories, or configure a fixed list of repository names to operate on. -If the administrator has configured a fixed list of repositories then the only way to "install" Renovate on a extra repository is for it to be manually added for the next run or restart. +If the administrator has configured a fixed list of repositories then the only way to "install" Renovate on an extra repository is for it to be manually added for the next run or restart. Otherwise, the process for adding new repositories to a Renovate installation can vary: @@ -15,7 +15,7 @@ Otherwise, the process for adding new repositories to a Renovate installation ca Follow these steps to install and enable the Mend Renovate App: -First, navigate to [https://github.com/apps/renovate](https://github.com/apps/renovate) and select the Install button: +First, navigate to [https://github.com/apps/renovate](https://github.com/apps/renovate) and select the "Install" button: ![The Mend Renovate App Install button](../assets/images/github-app-install.png){ loading=lazy } @@ -27,11 +27,11 @@ Renovate will ignore any repositories that don't have known package files, as we That said, most people run Renovate on selected repositories. Unfortunately GitHub doesn't offer a "select all except X, Y, Z" option, so you must select each repository where you want Renovate to run. -Once you're done selecting repositories for Renovate to run on, select the green Install button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. +Once you're done selecting repositories for Renovate to run on, select the green "Install" button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. !!! note - If you are using the Mend Renovate App then it has a custom behavior for forked repositories. + If you're using the Mend Renovate App then it has a custom behavior for forked repositories. If you choose "All repositories" when installing then forked repositories will be skipped by default, while if you choose "Select repositories" then they will be processed by Renovate even if they're a fork. ### Hosted GitLab.com App @@ -53,7 +53,7 @@ You can also set the line endings in your repository by adding `* text=auto eol= ## Repository onboarding -Once you have enabled Renovate on a repository, you will get a "Configure Renovate" Pull Request looking something like this: +Once you have enabled Renovate on a repository, you'll get a "Configure Renovate" Pull Request looking something like this: ![Onboarding](../assets/images/onboarding.png){ loading=lazy } @@ -92,7 +92,7 @@ If you don't want a `renovate.json` file in your repository you can use one of t You can add the same settings to a `"renovate"` section in your `package.json` file instead. The `package.json` file must be located at the root of your repository. -This is handy if you are already using a `package.json` file anyway, e.g. when you're working on a JavaScript project. +This is handy if you're already using a `package.json` file anyway, e.g. when you're working on a JavaScript project. The configuration in your `package.json` will apply to the whole project (this includes other, nested `package.json` files). ### Customized defaults @@ -131,10 +131,10 @@ There are two recommended approaches: If you want to make config edits directly, follow these steps: 1. Create a new Git branch to work on -1. Install or update the `renovate` package globally (`npm i -g renovate` or `yarn global add renovate`) to get the `renovate-config-validator` program -1. Edit your Renovate configuration file -1. [Validate your config](../config-validation.md) -1. If the improved config passes the validation, merge the branch into your mainline branch +2. Install or update the `renovate` package globally (`npm i -g renovate` or `yarn global add renovate`) to get the `renovate-config-validator` program +3. Edit your Renovate configuration file +4. [Validate your config](../config-validation.md) +5. If the improved config passes the validation, merge the branch into your mainline branch ### Nuke config and re-onboard @@ -143,8 +143,8 @@ You can follow the steps below to nuke the config and get a new PR. Any existing Renovate PRs will be closed after you've completed these steps. 1. Find your original `Configure Renovate` PR -1. Rename the original PR to something else, e.g. `Configure Renovate - old` -1. Remove the current Renovate configuration file (e.g. `renovate.json`) from your mainline branch +2. Rename the original PR to something else, e.g. `Configure Renovate - old` +3. Remove the current Renovate configuration file (e.g. `renovate.json`) from your mainline branch Following these steps will trick Renovate into thinking that your repository was _never_ onboarded, and will trigger a new "Configure Renovate" PR. If you're using the Mend Renovate App and you don't get a new onboarding PR within a few hours, then please create a Discussions post to request staff trigger it manually. diff --git a/docs/usage/getting-started/private-packages.md b/docs/usage/getting-started/private-packages.md index 4f0761bd1d36bf..d97c09d769511d 100644 --- a/docs/usage/getting-started/private-packages.md +++ b/docs/usage/getting-started/private-packages.md @@ -10,11 +10,11 @@ First, a quick note on terminology: ## When does Renovate need credentials? -By default, the only credentials Renovate has are those for the "platform", i.e. GitHub, GitLab, etc. +By default, the only credentials Renovate has, are those for the "platform", i.e. GitHub, GitLab, etc. If the token used has sufficient permissions, this will enable Renovate to lookup dependencies located in alternative repositories on the same host or any hosted on any embedded package registry on the same host. It's also quite common to need to look up packages on other protected hosts, including npmjs, Docker Hub, or private registries like Nexus or Artifactory. -Any time you need Renovate to access such registries with credentials then you will need to provision them as part of your config. +Any time you need Renovate to access such registries with credentials then you'll need to provision them as part of your config. There are four times in Renovate's behavior when it may need credentials: @@ -31,8 +31,8 @@ There are four times in Renovate's behavior when it may need credentials: Renovate supports config presets, including those which are private. -Although npm presets were the first type supported, they are now deprecated and it is recommend that all users migrate to git-hosted "local" presets instead. -However if you do still use them, private modules should work if you configure `hostRules` (recommended) or `npmrc` including token credentials in your bot global config. +Although npm presets were the first type supported, they are now deprecated, and it is recommended that all users migrate to git-hosted "local" presets instead. +However, if you do still use them, private modules should work if you configure `hostRules` (recommended) or `npmrc` including token credentials in your bot global config. It is strongly recommended not to use private modules on a private registry and a warning will be logged if that is found. Credentials stored on disk (e.g. in `~/.npmrc`) are no longer supported. @@ -57,14 +57,14 @@ Configuring Renovate with credentials requires `hostRules`. Each host rule consists of a `hostType` value and/or a way to match against hosts using `matchHost`. `hostType` is not particularly important at this step unless you have different credentials for the same host, but it is sometimes useful in later steps so is good to include if you can. -It can be either a "platform" name (e.g. `github`, `azure`, etc) or a "datasource" name (e.g. `npm`, `maven`, `github-tags`, etc). +It can be either a "platform" name (e.g. `github`, `azure`, etc.) or a "datasource" name (e.g. `npm`, `maven`, `github-tags`, etc.). If you want to apply credentials only for a nested path within a host then write `matchHost` as a base URL like `https://registry.company.com/nested/path/`. If the same credentials apply to all paths on a host and not on any subdomains of it then configure `matchHost` with a protocol like `https://registry.company.com`. Finally, to apply credentials to all hosts within the domain, use a `matchHost` value with no `https://` prefix, e.g. `company.com` or `registry.company.com`, both of which would apply to a host like `beta.registry.company.com`. In addition to the above options to match against a host, you need to add the credentials. -Typically they are either `token`, or `username` + `password`. +Typically, they are either `token`, or `username` + `password`. Other credential terms are not supported yet. ```json title="Example host rules" @@ -151,7 +151,7 @@ When it comes to open source, most packages host their source on `github.com` in GitHub greatly rate limits unauthenticated API requests, so you need to configure credentials for `github.com` or the bot will get rate limited quickly. It can be confusing for people who host their own source code privately to be asked to configure a `github.com` token but without it changelogs for most open source packages will be blocked. -Currently the preferred way to configure `github.com` credentials for self-hosted Renovate is: +Currently, the preferred way to configure `github.com` credentials for self-hosted Renovate is: - Create a read-only Personal Access Token (PAT) for a `github.com` account. This can be any GitHub account, but we recommend you create an "empty" account for this purpose. - Add the PAT to Renovate using the environment variable `GITHUB_COM_TOKEN` @@ -228,8 +228,8 @@ If you need to configure per-repository credentials then you can also configure The recommended approaches in order of preference are: 1. **Self-hosted hostRules**: Configure a hostRules entry in the bot's `config.js` with the `hostType`, `matchHost` and `token` specified -1. **The Mend Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config -1. **The Mend Renovate App with a private registry**: Add an plaintext `npmrc` plus an encrypted `npmToken` in config +2. **The Mend Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config +3. **The Mend Renovate App with a private registry**: Add a plaintext `npmrc` plus an encrypted `npmToken` in config These approaches are described in full below. @@ -280,11 +280,11 @@ You can add an `.npmrc` authentication line to your Renovate config under the fi If configured like this, Renovate will use this to authenticate with npm and will ignore any `.npmrc` files(s) it finds checked into the repository. If you wish for the values in your `config.npmrc` to be _merged_ (prepended) with any values found in repos then also set `config.npmrcMerge=true`. -This merge approach is similar to how `npm` itself behaves if `.npmrc` is found in both the user home directory as well as a project. +This merge approach is similar to how `npm` itself behaves if a `.npmrc`-file is found in both the user home directory and a project. #### Add npmToken to Renovate config -If you are using the main npmjs registry then you can configure only the `npmToken` instead: +If you're using the main npm registry then you only need to configure the `npmToken` instead: ```json { @@ -323,14 +323,14 @@ If instead you use an alternative registry or need an `.npmrc` file for some oth Renovate will then use the following logic: 1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry -1. If an `npmrc` string is present and has a `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token -1. If an `npmrc` string is present but doesn't have a `${NPM_TOKEN}` then the file will have `_authToken=` appended to it +2. If an `npmrc` string is present and has a `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token +3. If an `npmrc` string is present but doesn't have a `${NPM_TOKEN}` then the file will have `_authToken=` appended to it #### Encrypted entire .npmrc file into config Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at . -You will then get an encrypted string that you can substitute into your `renovate.json` instead. +You'll then get an encrypted string that you can substitute into your `renovate.json` instead. The end-result looks like this: ```json @@ -512,13 +512,13 @@ For example: ## Encryption and the Mend Renovate App Many users use [the Mend Renovate App](https://github.com/apps/renovate), which is hosted by Mend. -If you are a user of this app, and have private modules, then the following is applicable. +If you're a user of this app, and have private modules, then the following is applicable. ### Private presets with public repositories If you have a preset in a private repo but reference ("extend") it from a public repository then it won't work. This is because public repositories are provided with a token scoped to only that particular repository, and not for all repositories within the organization. -This is a security measure so that if a the token is accidentally leaked publicly, the damage is limited to the public repository it leaked to and not to every repository within the organization. +This is a security measure so that if the token is accidentally leaked publicly, the damage is limited to the public repository it leaked to and not to every repository within the organization. The solution to this is that you should break your presets into public and private ones, and reference only the public ones from public repositories. diff --git a/docs/usage/getting-started/running.md b/docs/usage/getting-started/running.md index 5abf351cd7ebed..d4693d60b366b6 100644 --- a/docs/usage/getting-started/running.md +++ b/docs/usage/getting-started/running.md @@ -28,7 +28,7 @@ If you're running Renovate Community Edition or Renovate Enterprise Edition, ref Renovate's Open Source CLI is built and distributed as the npm package `renovate`. You can run this package in any Node.js environment - even via `npx` - and it will process all the repositories it is configured with, before exiting. -When installing Renovate via npm you are responsible for installing any third-party tools or languages like Ruby, Python, Composer, Bundler, Poetry, etc. +When installing Renovate via npm you're responsible for installing any third-party tools or languages like Ruby, Python, Composer, Bundler, Poetry, etc. The `renovate` npm package is compatible with all of Renovate's supported platforms. @@ -45,7 +45,7 @@ In general, you can run Renovate natively on Windows as long as you have all too There are two Docker image flavors: - The default image, which installs required tools at runtime (default for `latest` tag), -- The `-full` image, which comes with latest or very recent versions of every tool pre-installed +- The `-full` image, which comes with latest or very recent versions of every tool preinstalled ##### The default image (formerly `slim`) @@ -64,12 +64,12 @@ Read the [`binarySource` config option docs](../self-hosted-configuration.md#bin ##### The full image The `-full` image comes with most package managers that Renovate supports, but not _all_ package managers. -Update your Docker images regularly to keep the pre-installed tools up-to-date. +Update your Docker images regularly to keep the preinstalled tools up-to-date. The full image is for users who don't want to download or install things at runtime. This image has some downsides, because it: -- Comes pre-installed with _one_ version of each language/manager - usually the latest +- Comes preinstalled with _one_ version of each language/manager - usually the latest - Weighs several gigabytes #### GitHub Action @@ -136,7 +136,7 @@ If you use Forking Renovate, you'll miss out on these features of the regular Re After deciding on a Renovate distribution, you need to decide where and how to run it. For the GitHub Action and GitLab Runner approaches, they will naturally run on their respective CI infrastructure. -For the npm package approach or Docker images, you will need some form of VM or container infrastructure to run Renovate on. +For the npm package approach or Docker images, you'll need some form of VM or container infrastructure to run Renovate on. In all the above cases you must make sure that some form of cron-like capability exists to schedule when Renovate runs. We recommend that you run Renovate hourly, if possible. @@ -151,16 +151,16 @@ Renovate's server-side/admin config is referred to as its "global" config, and c - environment variables, or - CLI parameters -By default Renovate checks if a file named `config.js` is present. +By default, Renovate checks if a file named `config.js` is present. Any other (`*.js`, `*.json`, `*.json5`, `*.yaml` or `*.yml`) file is supported, when you reference it with the `RENOVATE_CONFIG_FILE` environment variable (for example: `RENOVATE_CONFIG_FILE=config.yaml`). Some config is global-only, meaning that either it is only applicable to the bot administrator or it can only be controlled by the administrator and not repository users. Those are documented in [Self-hosted Configuration](../self-hosted-configuration.md). -Your bot's global config can include both global as well as non-global configuration options, while user/repo config can only include non-global options. +Your bot's global config can include both global and non-global configuration options, while user/repo config can only include non-global options. We recommend that you keep as much of the non-global config as possible in repository config files. This way the Renovate end users can see as much of the bot's configuration as possible. -If you are configuring Renovate using environment variables, there are two possibilities: +If you're configuring Renovate using environment variables, there are two possibilities: - Upper-cased, camel-cased, `RENOVATE_`-prefixed single config options like `RENOVATE_TOKEN=abc123` or `RENOVATE_GIT_AUTHOR=a@b.com` - Set `RENOVATE_CONFIG` to a [stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) version of the full JSON config, for example: `RENOVATE_CONFIG='{"token":"abc123","gitAuthor":"a@b.com"}'` @@ -200,7 +200,7 @@ We also recommend you configure `config.gitAuthor` with the same identity as you #### Docs -Read the platform-specific docs to learn how to setup authentication on your platform: +Read the platform-specific docs to learn how to set up authentication on your platform: - [Azure DevOps](../modules/platform/azure/index.md) - [Bitbucket Cloud](../modules/platform/bitbucket/index.md) @@ -211,7 +211,7 @@ Read the platform-specific docs to learn how to setup authentication on your pla ### GitHub.com token for changelogs -If you are running on any platform except github.com, you should also set the environment variable `GITHUB_COM_TOKEN` and put the Personal Access Token for github.com in it. +If you're running on any platform except github.com, you should also set the environment variable `GITHUB_COM_TOKEN` and put the Personal Access Token for github.com in it. This account can be _any_ account on GitHub, and needs only `read-only` access. It's used when fetching changelogs 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. @@ -219,7 +219,7 @@ 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 modules hosted on GitHub), we highly recommend that you add a `github.com` PAT (classic). - Otherwise you will exceed the rate limit for the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies. + Otherwise, you'll exceed the rate limit for the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies. ### Self-hosting examples diff --git a/docs/usage/getting-started/use-cases.md b/docs/usage/getting-started/use-cases.md index ffcdd260bc181e..3b624d9981c4fb 100644 --- a/docs/usage/getting-started/use-cases.md +++ b/docs/usage/getting-started/use-cases.md @@ -22,8 +22,8 @@ Example package files include: Renovate: 1. Scans your repositories to find package files and their dependencies -1. Checks if any newer versions exist -1. Raises Pull Requests for available updates +2. Checks if any newer versions exist +3. Raises Pull Requests for available updates The Pull Requests patch the package files directly, and include changelogs for the newer versions (if they are available). @@ -43,11 +43,11 @@ This is why Renovate lets the package manager do the lock file update. A simplified example: 1. The repository has a `package.json` and `package-lock.json` with version `1.0.0` of a dependency -1. Renovate sees that version `1.1.0` is available -1. Renovate patches the `package.json` to change the dependency's version from `1.0.0` to `1.1.0` -1. Renovate runs `npm install` to let `npm` update the `package-lock.json` -1. Renovate commits the `package.json` and `package-lock.json` -1. Renovate creates the PR +2. Renovate sees that version `1.1.0` is available +3. Renovate patches the `package.json` to change the dependency's version from `1.0.0` to `1.1.0` +4. Renovate runs `npm install` to let `npm` update the `package-lock.json` +5. Renovate commits the `package.json` and `package-lock.json` +6. Renovate creates the PR ### Custom dependency extraction @@ -63,7 +63,7 @@ You configure the custom manager by telling it: - Which file pattern(s) to match - How to find the dependency name and version from within the file -- Which datasource (e.g. Docker registry, npm registry, etc) to use to look up new versions +- Which datasource (e.g. Docker registry, npm registry, etc.) to use to look up new versions The end result is that Renovate can keep dependencies in custom file formats up-to-date as long as the dependency datasource is known to Renovate. @@ -136,14 +136,14 @@ We use these Renovate features to automerge an internal dependency: We split our work over two repositories: 1. The [`renovatebot/renovate`](https://github.com/renovatebot/renovate) repository, which has the Renovate code, and most of the Markdown documentation files -1. The [`renovatebot/renovatebot.github.io`](https://github.com/renovatebot/renovatebot.github.io) repository, which has a submodule link to the `renovatebot/renovate` repository +2. The [`renovatebot/renovatebot.github.io`](https://github.com/renovatebot/renovatebot.github.io) repository, which has a submodule link to the `renovatebot/renovate` repository ##### Update process 1. We edit our documentation files on the main Renovate repository `renovatebot/renovate` -1. Renovate sees the change(s) to the `renovatebot/renovate` Git submodule, and creates an update branch on the _documentation build_ repository -1. If the tests pass Renovate automerges the update branch into the `main` branch. -1. A GitHub Actions workflow runs on `main` to build the documentation site and push the build live on our GitHub Pages domain +2. Renovate sees the change(s) to the `renovatebot/renovate` Git submodule, and creates an update branch on the _documentation build_ repository +3. If the tests pass Renovate automerges the update branch into the `main` branch. +4. A GitHub Actions workflow runs on `main` to build the documentation site and push the build live on our GitHub Pages domain ##### Benefits @@ -152,7 +152,7 @@ The way we've set things up means we avoid: - reviewing PRs - manually merging PRs -In fact we don't even get the update PR anymore! +In fact, we don't even get the update PR anymore! ## Advanced configuration @@ -189,7 +189,7 @@ If you want to get an update ahead of schedule, or want to retry a previously cl ### Dependency Dashboard Approval -If you enable the Dependency Dashboard you can opt-in to a different workflow for some, or even all of your packages. +If you enable the Dependency Dashboard you can opt in to a different workflow for some, or even all of your packages. We call this the "Dependency Dashboard Approval" workflow. Here's how it works: diff --git a/docs/usage/gitlab-bot-security.md b/docs/usage/gitlab-bot-security.md index 1fd31351cc129c..ea9b7e575d184a 100644 --- a/docs/usage/gitlab-bot-security.md +++ b/docs/usage/gitlab-bot-security.md @@ -13,7 +13,7 @@ Make sure you understand GitLab's security model, before you run a "bot" service ## `CI_JOB_TOKEN` permissions The concept of `CI_JOB_TOKEN` permissions was [overhauled in GitLab release 8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/), jobs now run with the permissions of the user account which _triggered_ the pipeline. -For security reasons the token was limited to read-only permissions and a limited set of API endpoints, but it’s been extended to allow [write access to the GitLab Package Registry](https://docs.gitlab.com/ee/api/index.html#gitlab-ci-job-token). +For security reasons the token was limited to read-only permissions and a limited set of API endpoints, but it’s been extended to allow [write-access to the GitLab Package Registry](https://docs.gitlab.com/ee/api/index.html#gitlab-ci-job-token). Any pipeline triggered by a user account thus has permissions to: - read any repository which that account has access to @@ -25,12 +25,12 @@ Because that project could maliciously steal repository data, publish fake relea ## Risks of hosting a Renovate GitLab app/bot/service With GitLab's current security model, we find the risks of running a _public_ bot service like Renovate are too high. -Therefore we stopped hosting Renovate on GitLab, and are waiting for a better security model. +Therefore, we stopped hosting Renovate on GitLab, and are waiting for a better security model. You should remember that when accounts are invited into projects or groups on GitLab, acceptance happens automatically. This was a useful feature to leverage for a shared service. -If you are running a self-hosted Renovate service, we recommend you: +If you're running a self-hosted Renovate service, we recommend you: - Run a shared service only within projects which have shared visibility/security within the users, or which have a low risk that a user would try to gain access to a private project they don't otherwise have access to - If running with `autodiscover`, also configure a value for `autodiscoverFilter` so that the bot can't be invited to projects or groups you don't intend diff --git a/docs/usage/golang.md b/docs/usage/golang.md index b4a6554406b036..58419ea4145fca 100644 --- a/docs/usage/golang.md +++ b/docs/usage/golang.md @@ -19,15 +19,15 @@ To learn what these variables do, read the [Go Modules Reference about the`GOPRO ## How It Works 1. Renovate searches in each repository for any `go.mod` files -1. Renovate extracts existing dependencies from `require` statements -1. Renovate resolves the dependency's source repository and checks for SemVer tags if found. Otherwise commits and `v0.0.0-....` syntax will be used -1. If Renovate finds an update, Renovate will update `go.mod` to the new value -1. Renovate runs `go get` to update the `go.sum` files (you can configure which directory are included using the `goGetDirs` option) -1. If the user has enabled the option `gomodUpdateImportPaths` in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions) array, then Renovate uses [mod](https://github.com/marwan-at-work/mod) to update import paths on major updates, which can update any Go source file -1. If the user has any of the available `gomodTidy` options (e.g. `gomodTidy1.17`) in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions), then Renovate runs `go mod tidy` with the respective options (multiple options are allowed). -1. `go mod vendor` is run if vendored modules are detected -1. A PR will be created with `go.mod`,`go.sum`, and any updated vendored files updated in the one commit -1. If the source repository has either a "changelog" file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR +2. Renovate extracts existing dependencies from `require` statements +3. Renovate resolves the dependency's source repository and checks for SemVer tags if found. Otherwise, commits and `v0.0.0-....` syntax will be used +4. If Renovate finds an update, Renovate will update `go.mod` to the new value +5. Renovate runs `go get` to update the `go.sum` files (you can configure which directory are included using the `goGetDirs` option) +6. If the user has enabled the option `gomodUpdateImportPaths` in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions) array, then Renovate uses [mod](https://github.com/marwan-at-work/mod) to update import paths on major updates, which can update any Go source file +7. If the user has any of the available `gomodTidy` options (e.g. `gomodTidy1.17`) in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions), then Renovate runs `go mod tidy` with the respective options (multiple options are allowed). +8. `go mod vendor` is run if vendored modules are detected +9. A PR will be created with `go.mod`,`go.sum`, and any updated vendored files updated in the one commit +10. If the source repository has either a "changelog" file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR ## Enabling Go Modules Updating @@ -38,8 +38,8 @@ To install Renovate Bot itself, either enable the [Renovate App](https://github. ### Replace massaging -Renovate can massage `replace` statements it finds prior to running `go` commands, and then massage them back afterwards. -This capability was added - and originally default behavior - because relative `replace` statements outside of the current repo will not work when Renovate clones the repo locally. +Renovate can massage `replace` statements it finds prior to running `go` commands, and then massage them back afterward. +This capability was added - and originally default behavior - because relative `replace` statements outside the current repo will not work when Renovate clones the repo locally. On the other hand, this massaging of `replace` statements may lead to unexpected results, especially because `go mod tidy` may not fully tidy the `go.sum` if it is missing the `replace` directives in `go.mod`. It has therefore been disabled by default. @@ -81,7 +81,7 @@ This means you cannot use `go 1.16.6`, but you can use `go 1.16` as a constraint ### Custom registry support, and authentication This example shows how you can use a `hostRules` configuration to configure Renovate for use with a custom private Go module source using Git to pull the modules when updating `go.sum` and vendored modules. -All token `hostRules` with a `hostType` (e.g. `github`, `gitlab`, `bitbucket`, ... ) and host rules without a `hostType` are setup for authentication. +All token `hostRules` with a `hostType` (e.g. `github`, `gitlab`, `bitbucket`, ... ) and host rules without a `hostType` are set up for authentication. ```js module.exports = { diff --git a/docs/usage/key-concepts/automerge.md b/docs/usage/key-concepts/automerge.md index 43095d66b7ded7..8905bebffc107d 100644 --- a/docs/usage/key-concepts/automerge.md +++ b/docs/usage/key-concepts/automerge.md @@ -164,7 +164,7 @@ Finally, allow Renovate to automerge by setting `automerge=true` in your Renovat If you _don't_ use GitHub Actions as your CI provider, follow these steps: -Update your CI provider's configuration so it also runs tests on the temporary `gh-readonly-queue/{base_branch}` branches, read your CI providers's documentation to learn how to do this. +Update your CI provider's configuration, so it also runs tests on the temporary `gh-readonly-queue/{base_branch}` branches, read your CI provider's documentation to learn how to do this. On `github.com`, go to your repository's "homepage", click on Settings, scroll down to the Pull Requests section and [enable the "Allow auto-merge" checkbox](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository#managing-auto-merge). Go to your repository's branch protection rules for your base branch (usually `main`) and enable the "Require merge queue" setting. @@ -189,7 +189,7 @@ This is a lot better than you waking up to two PRs and then having to deal with ## Branch vs PR automerging -Even if you automerge PRs, you are likely to still get notification noise - one when the PR is created and another when it is merged. +Even if you automerge PRs, you're likely to still get notification noise - 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 @@ -199,7 +199,7 @@ For this reason we recommend you consider setting `automergeType=branch` which w Add the `renovate/**` branch to your testing workflow files, or Renovate will not work properly with the `automergeType=branch` setting. The result is that passing updates are essentially "silent" - the only sign of them are the commits Renovate pushes to your base branch. -If you have enabled branch protection which prevents Renovate from automerging directly to the base branch, then this won't work and you should stick with the default PR-based automerging instead. +If you have enabled branch protection which prevents Renovate from automerging directly to the base branch, then this won't work, and you should stick with the default PR-based automerging instead. ## Assignees and Reviewers @@ -224,7 +224,7 @@ If you have no tests but still want Renovate to automerge, you need to add `"ign !!! tip - We strongly recommend you have tests in any project where you are regularly updating dependencies. + We strongly recommend you have tests in any project where you're regularly updating dependencies. ### Committer restrictions @@ -249,7 +249,7 @@ Depending on the platform, having a `CODEOWNERS` file could block automerging, b ### Overriding global automerge -You might have setup a global configuration in a `.github` repository, that has a `renovate.json` file that turns on automerge for certain dependencies. +You might have set up a global configuration in a `.github` repository, that has a `renovate.json` file that turns on automerge for certain dependencies. It does not matter where you've put the global config, the important point in this example is that you're extending from a global config that's somewhere else. For this example we'll assume you put your config in a repository on GitHub, called `.github`. diff --git a/docs/usage/key-concepts/changelogs.md b/docs/usage/key-concepts/changelogs.md index 8af4280e864286..898cb8edd36a47 100644 --- a/docs/usage/key-concepts/changelogs.md +++ b/docs/usage/key-concepts/changelogs.md @@ -10,11 +10,11 @@ This page explains how Renovate fetches changelogs, when it can display them, an Renovate detects and populates changelogs by: 1. Identifying a source URL from the datasource response for a package, and saving that internally as `sourceUrl` if found -1. Checking if Renovate's internal [_manual_ metadata](https://github.com/renovatebot/renovate/blob/main/lib/modules/datasource/metadata-manual.ts) for the package includes a source URL -1. Looking up the source URL, if it resides on a supported platform (e.g. GitHub) -1. Checking for both "Releases" metadata in the repository and any commonly known "changelog" file names -1. Filtering the found releases to only include those versions being updated by the current PR -1. Formatting and embedding the results into the PR body +2. Checking if Renovate's internal [_manual_ metadata](https://github.com/renovatebot/renovate/blob/main/lib/modules/datasource/metadata-manual.ts) for the package includes a source URL +3. Looking up the source URL, if it resides on a supported platform (e.g. GitHub) +4. Checking for both "Releases" metadata in the repository and any commonly known "changelog" file names +5. Filtering the found releases to only include those versions being updated by the current PR +6. Formatting and embedding the results into the PR body ## Changelogs for private packages @@ -59,16 +59,16 @@ Follow these steps to find out why Renovate does not find a changelog: - If the registry fundamentally does not provide this data, then the only possibility is for it to be manually populated through PRs to Renovate's source code - If the registry provides source URLs in its response but Renovate does not understand the required fields, then raise a feature request with examples, or better yet a Pull Request to implement support for the source URL parsing/mapping yourself - Sometimes self-hosted versions of registries don't include the full metadata compared to what the public registries do -1. The package was published without source URL information being included. +2. The package was published without source URL information being included. - For example, occasionally `npm` packages don't have `repository` fields included - For example, Docker images regularly do not have the required `LABEL` entry -1. Renovate cannot access the source repository +3. Renovate cannot access the source repository - This is typically a concern for private repositories only - Check if the token Renovate uses has access rights to the repository you need it to access -1. Renovate cannot detect the file names or release name convention within the repository +4. Renovate cannot detect the file names or release name convention within the repository - In this case an enhancement to Renovate might be needed to better detect the releases/formats, assuming the package/repository has a reasonable convention to follow -If none of this helps, search the Renovate issues and discussions to see if this is a known problem. +If none of these steps help, search the Renovate issues and discussions to see if this is a known problem. ## Advice for package maintainers @@ -77,7 +77,7 @@ This section is for package maintainers that want to make sure Renovate can see There isn't much information to add other than what's already written above. Make sure that you have the required source URL in your package metadata, not just in your repository but also in the final data which the registry returns. -For example, we have seen cases where the `repository` field in npm's `package.json` is populated correctly in the repository, but stripped out as part of the publishing process. +For example, we have seen cases where the `repository` field in the npm `package.json` is populated correctly in the repository, but stripped out as part of the publishing process. ### Let Renovate understand your versioning and changelogs diff --git a/docs/usage/key-concepts/how-renovate-works.md b/docs/usage/key-concepts/how-renovate-works.md index bed2d0e12a0b62..e10dcf657b3d68 100644 --- a/docs/usage/key-concepts/how-renovate-works.md +++ b/docs/usage/key-concepts/how-renovate-works.md @@ -28,9 +28,9 @@ Renovate's modules are: Renovate uses these modules in order: 1. The platform module interacts with the source control platform and clones the repository -1. The manager module looks for files based on their name and extracts the dependencies (each dependency has a datasource) -1. The datasource module looks up versions of the dependency -1. The versioning module validates and sorts the returned versions +2. The manager module looks for files based on their name and extracts the dependencies (each dependency has a datasource) +3. The datasource module looks up versions of the dependency +4. The versioning module validates and sorts the returned versions For example: diff --git a/docs/usage/key-concepts/presets.md b/docs/usage/key-concepts/presets.md index 4ffaa25de680f0..2f43325a4e32df 100644 --- a/docs/usage/key-concepts/presets.md +++ b/docs/usage/key-concepts/presets.md @@ -20,7 +20,7 @@ Use presets to: Let's say you're using the `config:recommended` preset, and want to pin your GitHub Action digests. Instead of writing your own Renovate config, you search through Renovate's built-in presets. -You find the the `helpers:pinGitHubActionDigests` preset and add it to the `extends` array: +You find the `helpers:pinGitHubActionDigests` preset and add it to the `extends` array: ```json { diff --git a/docs/usage/key-concepts/pull-requests.md b/docs/usage/key-concepts/pull-requests.md index 7e2af2e96a9bb1..1095e9da547fd8 100644 --- a/docs/usage/key-concepts/pull-requests.md +++ b/docs/usage/key-concepts/pull-requests.md @@ -21,17 +21,17 @@ But if you group PRs and use titles like "All non-major updates", then multiple ## Normal PRs As explained above, Renovate PRs normally have some "uniqueness" in their title relating to the version in the upgrade. -When you close a "unique" PR, Renovate assumes you don't want to see that PR again in future, for example: +When you close a "unique" PR, Renovate assumes you don't want to see that PR again in the future, for example: 1. You ignored `lodash@4.17.21` by closing Renovate's PR -1. Renovate assumes you don't want any updates to `4.17.21` of `lodash` -1. Renovate creates a new PR when the branch + title "uniqueness" exists again, like when `lodash@4.17.22` releases +2. Renovate assumes you don't want any updates to `4.17.21` of `lodash` +3. Renovate creates a new PR when the branch + title "uniqueness" exists again, like when `lodash@4.17.22` releases Renovate behaves similarly for `major` updates, for example: 1. You ignored a `major` update for Lodash (pr title: "Update lodash to v4") by closing Renovate's PR -1. Renovate assumes you don't want any updates to `v4` of `lodash` -1. Renovate won't create any update PRs for `v4` of `lodash`, even if there are newer versions of `v4` +2. Renovate assumes you don't want any updates to `v4` of `lodash` +3. Renovate won't create any update PRs for `v4` of `lodash`, even if there are newer versions of `v4` ## Immortal PRs @@ -45,7 +45,7 @@ This document explains why we have immortal PRs, and how you can fix them. ### Why we have immortal PRs -First off, we don't have immortal PRs for some philosphical reason like: "don't ignore this update, it's good for you!". +First off, we don't have immortal PRs for some philosophical reason like: "don't ignore this update, it's good for you!". We have no good way to ignore some PRs after they're closed. #### Branch name and PR title are cache keys diff --git a/docs/usage/key-concepts/scheduling.md b/docs/usage/key-concepts/scheduling.md index 204bff8f1f2d24..2f7f9ebaaf4450 100644 --- a/docs/usage/key-concepts/scheduling.md +++ b/docs/usage/key-concepts/scheduling.md @@ -42,9 +42,9 @@ You can customize when Renovate runs, by using the `timezone` and `schedule` con At a high level you need to follow these steps: 1. Tell Renovate what `timezone` you want to use -1. Learn about the scheduling syntax -1. Optional: configure an "in repository schedule" -1. Optional: create packageRules with a custom `schedule` for specific packages +2. Learn about the scheduling syntax +3. Optional: configure an "in repository schedule" +4. Optional: create packageRules with a custom `schedule` for specific packages ### Setting your timezone diff --git a/docs/usage/known-limitations.md b/docs/usage/known-limitations.md index 5912b1556964e8..fd0757ec3f1c5b 100644 --- a/docs/usage/known-limitations.md +++ b/docs/usage/known-limitations.md @@ -23,7 +23,7 @@ For scheduled action to take place, both these need to happen: ### The Mend Renovate app and scheduled jobs -The Mend Renovate App checks each active repository roughly every three hours, if no activity has been seen before then (merged PRs, etc). +The Mend Renovate App checks each active repository roughly every three hours, if no activity has been seen before then (merged PRs, etc.). For this reason, you should set your schedule window to at least three or four hours. This makes it likely that Renovate bot checks your repository at least once during the schedule. diff --git a/docs/usage/merge-confidence.md b/docs/usage/merge-confidence.md index 01a24c4633abbb..4936e754db4c6f 100644 --- a/docs/usage/merge-confidence.md +++ b/docs/usage/merge-confidence.md @@ -28,7 +28,7 @@ Merge Confidence badges for pull requests are available on any supported platfor Renovate will show Merge Confidence badges for these languages: | Language | Datasource | -| ---------- | ----------- | +|------------|-------------| | Golang | `go` | | JavaScript | `npm` | | Java | `maven` | diff --git a/docs/usage/modules/manager/index.md b/docs/usage/modules/manager/index.md index 237c33194a4ee6..8cb9eeef2f9b52 100644 --- a/docs/usage/modules/manager/index.md +++ b/docs/usage/modules/manager/index.md @@ -59,7 +59,7 @@ The `config:recommended` preset ignores common test and example directory names, #### Enabling experimental managers Most managers are enabled by default. -For those that aren't, typically because they are considered experimental, you can opt-in manually. +For those that aren't, typically because they are considered experimental, you can opt in manually. If there was a manager called `some-new-manager` you would enable it like this: ```json diff --git a/docs/usage/noise-reduction.md b/docs/usage/noise-reduction.md index 468c5383dc5747..4793370eafd5c3 100644 --- a/docs/usage/noise-reduction.md +++ b/docs/usage/noise-reduction.md @@ -7,7 +7,7 @@ description: How to reduce the "noise" associated with module updates 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. +Indeed, if you leave Renovate on its default settings of raising a PR every single time any dependency receives any update, you'll 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 approach. Of course, please keep in mind that people's definitions of "noise" may differ. @@ -50,7 +50,7 @@ Grouping dependencies versus single PRs: - Grouping dependencies increases the chance that the branch has an error ("break" your build) - When you upgrade multiple dependencies in one PR, it takes longer to find out which package broke the build - If a group PR "breaks", you'll have to wait upgrading your other dependencies until _all_ updates in the PR pass -- You will have less flexibility when one (or more) dependencies in the group have a major upgrade, but the other dependencies are good to go +- You'll have less flexibility when one (or more) dependencies in the group have a major upgrade, but the other dependencies are good to go ## Scheduling Renovate @@ -72,15 +72,15 @@ In that case, you might schedule Renovate to run every Tuesday after midnight to There are multiple reasons why Renovate may need to "recreate" PRs after you merge another: 1. Conflict with `package.json` (sometimes) -1. Conflict with lock files (often) -1. If you have configured Renovate or GitHub that PRs must always be kept up-to-date with the base branch +2. Conflict with lock files (often) +3. If you have configured Renovate or GitHub that PRs must always be kept up-to-date with the base branch Any of the above reasons can lead to a Renovate branch being considered "stale" and then Renovate needs to rebase it off the base branch before you can test and merge again, and Renovate won't do this until it's back in schedule. ### Selective scheduling Don't think that you need to apply blanket rules to scheduling. -Remember that Renovate's configuration is highly flexible so you can configure `automerge` anywhere from globally (entire repo) right down to a package/upgrade type level. +Remember that Renovate's configuration is highly flexible, so you can configure `automerge` anywhere from globally (entire repo) right down to a package/upgrade type level. You could even configure a nonsensical rule like: "patch updates of `jquery` are for Mondays only". Remember our example of grouping all `eslint` packages? @@ -125,7 +125,7 @@ In short: it means that Renovate can merge PRs or even branches itself if they p We recommend that you enable automerge for any type of dependency update where you would select 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 select Merge on a Renovate PR without manually testing it, you should consider if you can enable automerge and save yourself the time in future. +Every time you select Merge on a Renovate PR without manually testing it, you should consider if you can enable automerge and save yourself the time in the future. Automerge works particularly well for `devDependencies` and for production `dependencies` that have great test coverage. @@ -135,7 +135,7 @@ If you have an API with 100% test coverage and `express` is updated: automerge i ### 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. +Those of you familiar with GitHub might note that even if you automerge PRs, you're 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 @@ -185,7 +185,7 @@ Using lock files greatly increases the chance that merging one PR will result in 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 | -| ------------------------------------ | ------------------------ | ----------------------------- | +|--------------------------------------|--------------------------|-------------------------------| | Group dependencies together | Decreases separate PRs | Decreases | | Automerge dependencies | Decreases concurrent PRs | Decreases | | Decrease scheduled time for Renovate | Increases concurrent PRs | Increases | @@ -196,7 +196,7 @@ First of all, if you ever have any ideas about how to make Renovate less noisy, Our philosophy is: 1. Nearly everyone should use Renovate-like dependency update automation -1. Over time, you should "see" Renovate less and less +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. diff --git a/docs/usage/nuget.md b/docs/usage/nuget.md index 49a4b0c2eaf865..838bc200a9b781 100644 --- a/docs/usage/nuget.md +++ b/docs/usage/nuget.md @@ -18,16 +18,16 @@ By default, this includes: - .NET Core 1.0 and above - .NET Standard class libraries -- `.csproj`, `.fsproj` or `.vbproj` files that use the SDK-style syntax +- `.csproj`, `.fsproj` or `.vbproj` files that use the SDK-style syntaxes To convert your .NET Framework `.csproj`, `.fsproj` or `.vbproj` files into an SDK-style project, follow the steps in this [guide](https://natemcmaster.com/blog/2017/03/09/vs2015-to-vs2017-upgrade/). ## How it works 1. Renovate searches in each repository for any files with a `.csproj`, `.fsproj`, or `.vbproj` extension -1. Existing dependencies are extracted from `` and `` tags -1. Renovate looks up the latest version on [nuget.org](https://nuget.org) (or an alternative feed if configured) to see if any upgrades are available -1. If the source package includes a GitHub URL as its source, and has either: +2. Existing dependencies are extracted from `` and `` tags +3. Renovate looks up the latest version on [nuget.org](https://nuget.org) (or an alternative feed if configured) to see if any upgrades are available +4. If the source package includes a GitHub URL as its source, and has either: - a "changelog" file, or - uses GitHub releases @@ -39,7 +39,7 @@ Find out here how to [migrate from `packages.config` to `PackageReference`](http ## Alternate feeds -By default Renovate performs all lookups on `https://api.nuget.org/v3/index.json`, but you can set alternative NuGet feeds. +By default, Renovate performs all lookups on `https://api.nuget.org/v3/index.json`, but you can set alternative NuGet feeds. You can set alternative feeds: - 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 diff --git a/docs/usage/php.md b/docs/usage/php.md index 358d14c0143981..a75fe7e169c0ee 100644 --- a/docs/usage/php.md +++ b/docs/usage/php.md @@ -10,10 +10,10 @@ Renovate can upgrade dependencies in PHP's `composer.json` and `composer.lock` f ## How It Works 1. Renovate searches in each repository for any `composer.json` files -1. Existing dependencies are extracted from the relevant sections of the JSON -1. Renovate resolves the dependency on Packagist (or elsewhere if configured), and filter for SemVer versions -1. A PR is created with `composer.json` and `composer.lock` updated in the same commit -1. If the source repository has either a "changelog" file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR +2. Existing dependencies are extracted from the relevant sections of the JSON +3. Renovate resolves the dependency on Packagist (or elsewhere if configured), and filter for SemVer versions +4. A PR is created with `composer.json` and `composer.lock` updated in the same commit +5. If the source repository has either a "changelog" file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR ## Enabling @@ -21,7 +21,7 @@ Either install the [Renovate App](https://github.com/apps/renovate) on GitHub, o ## Private packages -If you are using a [privately hosted Composer package](https://getcomposer.org/doc/articles/authentication-for-private-packages.md) you can pass the credentials via the [`hostRules`](./configuration-options.md#hostrules) configuration. +If you're using a [privately hosted Composer package](https://getcomposer.org/doc/articles/authentication-for-private-packages.md) you can pass the credentials via the [`hostRules`](./configuration-options.md#hostrules) configuration. ```json { @@ -42,7 +42,7 @@ 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 Mend Renovate App then you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. +If you're using the Mend Renovate App then you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. Go to [https://app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt), paste in the secret string you wish to encrypt, select _Encrypt_, then copy the encrypted result. You may encrypt your `password` only, but you can encrypt your `username` as well. diff --git a/docs/usage/python.md b/docs/usage/python.md index 146dda8772fb13..bf70a5c18d619e 100644 --- a/docs/usage/python.md +++ b/docs/usage/python.md @@ -10,7 +10,7 @@ See [all supported managers](./modules/manager/index.md). ## Versioning support -We've written a JavaScript version of the [PEP440 specification](https://www.python.org/dev/peps/pep-0440/) so we can use it in Renovate bot. +We've written a JavaScript version of the [PEP440 specification](https://www.python.org/dev/peps/pep-0440/), so we can use it in Renovate bot. You can find this project in our [`renovatebot/pep440` repository](https://github.com/renovatebot/pep440). Our PEP440 implementation supports pinned versions and ranges. @@ -19,9 +19,9 @@ Legacy versions with the `===` prefix are ignored. ## How it works 1. Renovate searches through each repository for package files -1. Existing dependencies are extracted from the package files -1. Renovate searches for the latest version on [PyPI](https://pypi.org/) to decide if there are upgrades -1. If the source package includes a GitHub URL as its source, and has a "changelog" file _or_ uses GitHub releases, a Release Note will be embedded in the generated PR +2. Existing dependencies are extracted from the package files +3. Renovate searches for the latest version on [PyPI](https://pypi.org/) to decide if there are upgrades +4. If the source package includes a GitHub URL as its source, and has a "changelog" file _or_ uses GitHub releases, a Release Note will be embedded in the generated PR ## Alternative file names @@ -43,7 +43,7 @@ You can tell Renovate where to find your file(s) by setting your own `fileMatch` ## Alternate registries -By default Renovate checks for upgrades on the `pypi.org` registry. +By default, Renovate checks for upgrades on the `pypi.org` registry. If you want, you can set alternative index URLs. There are three ways to do this: diff --git a/docs/usage/reading-list.md b/docs/usage/reading-list.md index e36b01a1b15987..ff9dd4fdb299c3 100644 --- a/docs/usage/reading-list.md +++ b/docs/usage/reading-list.md @@ -69,7 +69,7 @@ If you're going to self-host Renovate then read: - [Running Renovate](./getting-started/running.md) - [Self-hosting examples](./examples/self-hosting.md) -- Skim the [self hosted configuration options](./self-hosted-configuration.md) +- Skim the [self-hosted configuration options](./self-hosted-configuration.md) ## Private packages diff --git a/docs/usage/ruby.md b/docs/usage/ruby.md index 133d8d5dc51613..3858315e825fe7 100644 --- a/docs/usage/ruby.md +++ b/docs/usage/ruby.md @@ -10,9 +10,9 @@ Renovate supports upgrading dependencies in Bundler's Gemfiles and associated `G ## How it works 1. Renovate searches in each repository for any Gemfiles -1. Existing dependencies are extracted from the Gemfiles -1. Renovate resolves the dependency on Rubygems.org (or elsewhere if configured), and checks for newer versions -1. A PR is created which updates the `Gemfile` and `Gemfile.lock` in a single commit +2. Existing dependencies are extracted from the Gemfiles +3. Renovate resolves the dependency on Rubygems.org (or elsewhere if configured), and checks for newer versions +4. A PR is created which updates the `Gemfile` and `Gemfile.lock` in a single commit ## Warnings diff --git a/docs/usage/rust.md b/docs/usage/rust.md index 594abea989aab8..292e75ea474cec 100644 --- a/docs/usage/rust.md +++ b/docs/usage/rust.md @@ -10,10 +10,10 @@ Renovate supports upgrading dependencies in `Cargo.toml` files and associated `C ## How it works 1. Renovate searches in each repository for any `Cargo.toml` files -1. Renovate extracts existing dependencies from `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]` and `[workspace.dependencies]` -1. Renovate looks up Cargo configuration to find index URLs for private registries -1. Renovate resolves the dependency's version using the crates.io API or by cloning the index URL -1. If Renovate finds an update, Renovate will use `cargo update` to update both `Cargo.toml` and `Cargo.lock` +2. Renovate extracts existing dependencies from `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]` and `[workspace.dependencies]` +3. Renovate looks up Cargo configuration to find index URLs for private registries +4. Renovate resolves the dependency's version using the crates.io API or by cloning the index URL +5. If Renovate finds an update, Renovate will use `cargo update` to update both `Cargo.toml` and `Cargo.lock` ## Enabling Rust Modules Updating diff --git a/docs/usage/security-and-permissions.md b/docs/usage/security-and-permissions.md index 2e80c359f13764..8126d9ba350765 100644 --- a/docs/usage/security-and-permissions.md +++ b/docs/usage/security-and-permissions.md @@ -31,7 +31,7 @@ We apply the Principle of Least Privilege (PoLP) but do need substantial privile These permissions are always needed to run the respective app. | Permission | The Mend Renovate App | Forking Renovate | Why | -| ----------------- | :-------------------: | :----------------: | ------------------------------------------------------------- | +|-------------------|:---------------------:|:------------------:|---------------------------------------------------------------| | Dependabot alerts | `read` | `read` | Create vulnerability fix PRs | | Administration | `read` | `read` | Read branch protections and to be able to assign teams to PRs | | Metadata | `read` | `read` | Mandatory for all apps | @@ -44,11 +44,11 @@ These permissions are always needed to run the respective app. ### User permissions -Renovate can also request users's permission to the following resources. +Renovate can also request users' permission to the following resources. These permissions will be requested and authorized on an individual-user basis. | Permission | The Mend Renovate App | Forking Renovate | Why | -| ---------- | :-------------------: | :--------------: | -------------------------------------------------------- | +|------------|:---------------------:|:----------------:|----------------------------------------------------------| | email | `read` | not applicable | Per-user consent requested if logging into App dashboard | ## Privacy diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index 56a07967d3010c..0ad55f19947b93 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -89,7 +89,7 @@ If you use an environment variable or the CLI to set the value for `autodiscover Commas will be used as delimiter for a new filter. ``` -# DO NOT use commas inside the filter if your are using env or cli variables to configure it. +# DO NOT use commas inside the filter if you're using env or cli variables to configure it. RENOVATE_AUTODISCOVER_FILTER="/MyOrg/{my-repo,foo-repo}" @@ -146,7 +146,7 @@ For example: ## autodiscoverTopics Some platforms allow you to add tags, or topics, to repositories and retrieve repository lists by specifying those -topics. Set this variable to a list of strings, all of which will be topics for the autodiscovered repositories. +topics. Set this variable to a list of strings, all of which will be topics for the auto-discovered repositories. For example: @@ -158,7 +158,7 @@ For example: ## baseDir -By default Renovate uses a temporary directory like `/tmp/renovate` to store its data. +By default, Renovate uses a temporary directory like `/tmp/renovate` to store its data. You can override this default with the `baseDir` option. For example: @@ -189,9 +189,9 @@ Renovate supports four possible ways to access those tools: - `hermit`: Uses the [Hermit](https://github.com/cashapp/hermit) tool installation approach. Starting in v36, Renovate's default Docker image (previously referred to as the "slim" image) uses `binarySource=install` while the "full" Docker image uses `binarySource=global`. -If you are running Renovate in an environment where runtime download and install of tools is not possible then you should use the "full" image. +If you're running Renovate in an environment where runtime download and install of tools is not possible then you should use the "full" image. -If you are building your own Renovate image, e.g. by installing Renovate using `npm`, then you will need to ensure that all necessary tools are installed globally before running Renovate so that `binarySource=global` will work. +If you're building your own Renovate image, e.g. by installing Renovate using `npm`, then you'll need to ensure that all necessary tools are installed globally before running Renovate so that `binarySource=global` will work. The `binarySource=docker` approach should not be necessary in most cases now and `binarySource=install` is recommended instead. If you have a use case where you cannot use `binarySource=install` but can use `binarySource=docker` then please share it in a GitHub Discussion so that the maintainers can understand it. @@ -199,7 +199,7 @@ For this to work, `docker` needs to be installed and the Docker socket available ## cacheDir -By default Renovate stores cache data in a temporary directory like `/tmp/renovate/cache`. +By default, Renovate stores cache data in a temporary directory like `/tmp/renovate/cache`. Use the `cacheDir` option to override this default. The `baseDir` and `cacheDir` option may point to different directories. @@ -251,11 +251,11 @@ Example: `renovate --checked-branches=renovate/chalk-4.x renovate-reproductions/ This directory is used to cache downloads when `binarySource=docker` or `binarySource=install`. -Use this option if you need such downloads to be stored outside of Renovate's regular cache directory (`cacheDir`). +Use this option if you need such downloads to be stored outside Renovate's regular cache directory (`cacheDir`). ## customEnvVariables -This configuration will be applied after all other environment variables so you can use it to override defaults. +This configuration will be applied after all other environment variables, so you can use it to override defaults. ## detectGlobalManagerConfig @@ -263,7 +263,7 @@ The purpose of this config option is to allow you (as a bot admin) to configure This config option is disabled by default because it may prove surprising or undesirable for some users who don't expect Renovate to go into their home directory and import registry or credential information. -Currently this config option is supported for the `npm` manager only - specifically the `~/.npmrc` file. +Currently, this config option is supported for the `npm` manager only - specifically the `~/.npmrc` file. If found, it will be imported into `config.npmrc` with `config.npmrcMerge` set to `true`. ## detectHostRulesFromEnv @@ -372,11 +372,11 @@ You can use `dockerCliOptions` to pass Docker CLI options to Renovate's sidecar For example, `{"dockerCliOptions": "--memory=4g"}` will add a CLI flag to the `docker run` command that limits the amount of memory Renovate's sidecar Docker container can use to 4 gigabytes. -Read the [Docker Docs, configure runtime resource contraints](https://docs.docker.com/config/containers/resource_constraints/) to learn more. +Read the [Docker Docs, configure runtime resource constraints](https://docs.docker.com/config/containers/resource_constraints/) to learn more. ## dockerSidecarImage -By default Renovate pulls the sidecar Docker containers from `ghcr.io/containerbase/sidecar`. +By default, Renovate pulls the sidecar Docker containers from `ghcr.io/containerbase/sidecar`. You can use the `dockerSidecarImage` option to override this default. Say you want to pull a custom image from `ghcr.io/your_company/sidecar`. @@ -431,7 +431,7 @@ Information provided mainly in debug log level. ## executionTimeout Default execution timeout in minutes for child processes Renovate creates. -If this option is not set, Renovate will fallback to 15 minutes. +If this option is not set, Renovate will fall back to 15 minutes. ## exposeAllEnv @@ -471,7 +471,7 @@ This can be used if you're migrating from user-based forks to organization-based If you've set a `forkOrg` then Renovate will: 1. Check if a fork exists in the preferred organization before checking it exists in the fork user's account -1. If no fork exists: it will be created in the `forkOrg`, not the user account +2. If no fork exists: it will be created in the `forkOrg`, not the user account ## forkToken @@ -502,10 +502,10 @@ It will be loaded _lazily_. Before the first commit in a repository, Renovate will: 1. Run `gpg import` (if you haven't before) -1. Run `git config user.signingkey` and `git config commit.gpgsign true` +2. Run `git config user.signingkey` and `git config commit.gpgsign true` The `git` commands are run locally in the cloned repo instead of globally. -This reduces the chance of unintended consequences with global Git configs on shared systems. +This reduces the chance of unintended consequences of global Git configs on shared systems. ## gitTimeout @@ -593,7 +593,7 @@ Only set this to `false` if all three statements are true: 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. +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 @@ -613,7 +613,7 @@ Otherwise, Renovate skips onboarding a repository if it finds no dependencies in ## onboardingPrTitle -If you have an existing Renovate installation and you change the `onboardingPrTitle`: then you may get onboarding PRs _again_ for repositories with closed non-merged onboarding PRs. +If you have an existing Renovate installation, and you change the `onboardingPrTitle`: then you may get onboarding PRs _again_ for repositories with closed non-merged onboarding PRs. This is similar to what happens when you change the `onboardingBranch` config option. ## onboardingRebaseCheckbox @@ -623,8 +623,8 @@ This is similar to what happens when you change the `onboardingBranch` config op When this option is `true`, Renovate will do the following during repository initialization: 1. Try to fetch the default config file (e.g. `renovate.json`) -1. Check if the file contains `"enabled": false` -1. If so, skip cloning and skip the repository immediately +2. Check if the file contains `"enabled": false` +3. If so, skip cloning and skip the repository immediately If `onboardingConfigFileName` is set, that file name will be used instead of the default. @@ -676,7 +676,7 @@ TTL is 15 minutes by default, and it is adjustable in [cacheTtlOverride](#cachet 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 UI to encrypt values you can put the public key in a HTML page similar to . +If you want a UI to encrypt values you can put the public key in a webpage similar to . To create the key pair with GPG use the following commands: @@ -687,7 +687,7 @@ To create the key pair with GPG use the following commands: ``` ❯ gpg --full-generate-key gpg (GnuPG) 2.2.24; Copyright (C) 2020 Free Software Foundation, Inc. -This is free software: you are free to change and redistribute it. +This is free software: you're free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Please select what kind of key you want: @@ -754,7 +754,7 @@ Instead, with scoped secrets it means that Renovate ensures that the organizatio Use this field if you need to perform a "key rotation" and support more than one keypair at a time. Decryption with this key will be tried after `privateKey`. -If you are migrating from the legacy public key encryption approach to use GPG, then move your legacy private key from `privateKey` to `privateKeyOld` and then put your new GPG private key in `privateKey`. +If you're migrating from the legacy public key encryption approach to use GPG, then move your legacy private key from `privateKey` to `privateKeyOld` and then put your new GPG private key in `privateKey`. Doing so will mean that Renovate will first try to decrypt using the GPG key but fall back to the legacy key and try that next. You can remove the `privateKeyOld` config option once all the old encrypted values have been migrated, or if you no longer want to support the old key and let the processing of repositories fail. @@ -780,7 +780,7 @@ For non encrypted connections, Example URL structure: `redis://[[username]:[password]]@localhost:6379/0`. -For TLS/SSL-enabled connections, use rediss prefix +For TLS/SSL-enabled connections, use the rediss prefix Example URL structure: `rediss://[[username]:[password]]@localhost:6379/0`. @@ -827,7 +827,7 @@ JSON files will be stored inside the `cacheDir` beside the existing file-based p !!! note - S3 repository is used as a repository cache (e.g. extracted dependencies) and not a lookup cache (e.g. available versions of dependencies). To keep the later remotely, define [Redis URL](#redisurl). + S3 repository is used as a repository cache (e.g. extracted dependencies) and not a lookup cache (e.g. available versions of dependencies). To keep the latter remotely, define [Redis URL](#redisurl). ## requireConfig @@ -842,11 +842,11 @@ You can choose any of these settings: This feature is closely related to the `onboarding` config option. The combinations of `requireConfig` and `onboarding` are: -| | `onboarding=true` | `onboarding=false` | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -| `requireConfig=required` | An onboarding PR will be created if no config file exists. If the onboarding PR is closed and there's no config file, then the repository is skipped. | Repository is skipped unless a config file is added manually. | -| `requireConfig=optional` | An onboarding PR will be created if no config file exists. If the onboarding PR is closed and there's no config file, the repository will be processed. | Repository is processed regardless of config file presence. | -| `requireConfig=ignored` | No onboarding PR will be created and repo will be processed while ignoring any config file present. | Repository is processed, any config file is ignored. | +| | `onboarding=true` | `onboarding=false` | +|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------| +| `requireConfig=required` | An onboarding PR will be created if no config file exists. If the onboarding PR is closed, and there's no config file, the repository is skipped. | Repository is skipped unless a config file is added manually. | +| `requireConfig=optional` | An onboarding PR will be created if no config file exists. If the onboarding PR is closed, and there's no config file, the repository will be processed. | Repository is processed regardless of config file presence. | +| `requireConfig=ignored` | No onboarding PR will be created and repo will be processed while ignoring any config file present. | Repository is processed, any config file is ignored. | ## secrets @@ -894,7 +894,7 @@ Secret names must start with an upper or lower case character and can have only ## 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. +If this is set to false, then a full installation of modules will be done. This is currently applicable to `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-hosted-experimental.md b/docs/usage/self-hosted-experimental.md index 01a2993e414873..2027cd4afdd61f 100644 --- a/docs/usage/self-hosted-experimental.md +++ b/docs/usage/self-hosted-experimental.md @@ -95,7 +95,7 @@ If set, Renovate will terminate the whole process group of a terminated child pr ## `RENOVATE_X_GITLAB_AUTO_MERGEABLE_CHECK_ATTEMPS` -If set to an positive integer, Renovate will use this as the number of attempts to check if a merge request on GitLab is mergable before trying to automerge. +If set to a positive integer, Renovate will use this as the number of attempts to check if a merge request on GitLab is mergeable before trying to automerge. The formula for the delay between attempts is `250 * attempt * attempt` milliseconds. Default value: `5` (attempts results in max. 13.75 seconds timeout). diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md index 9966fc312a4919..4a2a3b481a1a29 100644 --- a/docs/usage/troubleshooting.md +++ b/docs/usage/troubleshooting.md @@ -30,7 +30,7 @@ For a full overview, select the `DEBUG` log level. The easiest way to gather logs from Renovate for any platform is to use the default logging to `stdout`/console. By default, Renovate will log in a human-readable format at `INFO` level. -For troubleshooting it's recommended to increase logging to `DEBUG` level by adding `LOG_LEVEL=debug` to your environment variables before invoking Renovate. +For troubleshooting, it's recommended to increase logging to `DEBUG` level by adding `LOG_LEVEL=debug` to your environment variables before invoking Renovate. If your Renovate logs are being processed by a log service before you access them, you may find it better to have Renovate output logs in JSON format instead so that they can be reliably parsed and filtered. This can be achieved by adding `LOG_FORMAT=json` to your environment variables before invoking Renovate. @@ -54,8 +54,8 @@ To troubleshoot further, you usually need to look at `DEBUG` logs. We recommend you follow this process: 1. Try to narrow in on the problem area e.g. by looking for relevant branches or `WARN` or `ERROR` messages -1. Find all relevant `DEBUG` or `INFO` messages from before and after the problem occurred -1. Copy/paste the relevant parts of the logs into your discussion post or bug report +2. Find all relevant `DEBUG` or `INFO` messages from before and after the problem occurred +3. Copy/paste the relevant parts of the logs into your discussion post or bug report If you cannot fix the problem yourself after reading the logs, and reading - or searching through - our documentation, search the [`renovatebot/renovate` discussion](https://github.com/renovatebot/renovate/discussions) forum to see if somebody has asked a similar or related question. @@ -63,9 +63,9 @@ If none of these steps have helped you, then create a new discussion post to get Please locate the relevant parts of the logs as described earlier before asking for help or posting a bug report. Do not expect the Renovate maintainers to read through the full logs when trying to help you, as that takes a lot of time on our part. -If later it turns out that the full logs are necessary, you will be asked for them then. +If later it turns out that the full logs are necessary, you'll be asked for them then. ## Validating configuration changes -Sometimes you will have to change your Renovate configuration to solve a problem. -The [`renovate-config-validator` program](config-validation.md) helps validate such configuration changes without commiting them to your repository. +Sometimes you'll have to change your Renovate configuration to solve a problem. +The [`renovate-config-validator` program](config-validation.md) helps validate such configuration changes without committing them to your repository. diff --git a/docs/usage/updating-rebasing.md b/docs/usage/updating-rebasing.md index 6bfadb298f1c37..28690148f3a619 100644 --- a/docs/usage/updating-rebasing.md +++ b/docs/usage/updating-rebasing.md @@ -10,7 +10,7 @@ There are many situations in which Renovate must update/rebase a branch. Here is a list of the most common cases where Renovate must update/rebase the branch: - When a pull request has conflicts due to changes on the base branch -- When you have enabled "Require branches to be up to date before merging" on GitHub +- When you have enabled "Require branches to be up-to-date before merging" on GitHub - When you have manually told Renovate to rebase when behind the base branch with `"rebaseWhen": "behind-base-branch"` - When a newer version of the dependency is released - When you request a manual rebase from the Renovate bot @@ -42,8 +42,8 @@ You can disable this functionality by configuring `"rebaseWhen": "never"` (not r There are multiple cases where Renovate will rebase its branches off the base branch every time they are out of date: 1. If you configure `"rebaseWhen": "behind-base-branch"` -1. If you use the default configuration `"rebaseWhen": "auto"` and the repository has a requirement that branches must be up-to-date before merging (e.g. "Require branches to be up to date before merging" on GitHub, or fast-forward-only settings on Bitbucket Server or GitLab) -1. If you use the default configuration `"rebaseWhen" : "auto"` and configure `"automerge" : true` +2. If you use the default configuration `"rebaseWhen": "auto"` and the repository has a requirement that branches must be up-to-date before merging (e.g. "Require branches to be up to date before merging" on GitHub, or fast-forward-only settings on Bitbucket Server or GitLab) +3. If you use the default configuration `"rebaseWhen" : "auto"` and configure `"automerge" : true` In that case Renovate PRs will be rebased off the repository's base branch whenever they are behind the base branch, even if the PRs are not conflicted. @@ -64,6 +64,6 @@ The label name is configurable via the `rebaseLabel` option. If you apply a rebase label then Renovate will regenerate its commit for the branch, even if the branch has been modified. The rebase label is useful in situations like: -- If a branch is behind the base branch but you don't have `rebaseWhen=behind-base-branch` enabled -- If a branch has been edited and you want to discard the edits and have Renovate create it again +- If a branch is behind the base branch, but you don't have `rebaseWhen=behind-base-branch` enabled +- If a branch has been edited, and you want to discard the edits and have Renovate create it again - If a branch was created with an error (e.g. lockfile generation) and you want Renovate to try again diff --git a/docs/usage/upgrade-best-practices.md b/docs/usage/upgrade-best-practices.md index f180921b866872..5b3ae4697cf225 100644 --- a/docs/usage/upgrade-best-practices.md +++ b/docs/usage/upgrade-best-practices.md @@ -2,7 +2,7 @@ This page explains what we (the Renovate maintainers) recommend you do to update your dependencies. -We'll cover starting a new project, updating a year-old project, and updating a project with five year old dependencies. +We'll cover starting a new project, updating a year-old project, and updating a project with dependencies that are five years old. We explain why you should update often, and how to nudge your team to update their dependencies. ## General recommendations @@ -80,7 +80,7 @@ The [GitHub Docs, using third-party actions](https://docs.github.com/en/actions/ We recommend pinning _all_ Actions. That's why the `helpers:pinGitHubActionDigests` preset pins all GitHub Actions. -For an in-depth explanation why you should pin your Github Actions, read the [Palo Alto Networks blogpost about the GitHub Actions worm](https://www.paloaltonetworks.com/blog/prisma-cloud/github-actions-worm-dependencies/). +For an in-depth explanation why you should pin your GitHub Actions, read the [Palo Alto Networks blogpost about the GitHub Actions worm](https://www.paloaltonetworks.com/blog/prisma-cloud/github-actions-worm-dependencies/). #### Extends `:pinDevDependencies` @@ -116,7 +116,7 @@ This is because you already: #### You'll be ready for CVE patches -Thirdly, you'll be ready when a upstream package releases a patch for a critical CVE. +Thirdly, you'll be ready when an upstream package releases a patch for a critical CVE. If you're current, you can review and merge Renovate's PR quickly. When you're behind on updates, you'll have a bad time, because you must read _more_ changelogs and make _more_ changes before you can merge the critical patch. @@ -138,7 +138,7 @@ After pushing the initial commit, you should enable and onboard Renovate. Now you'll have to stay on the "update often" train. -## Project with one year old dependencies +## Project with dependencies that are a year old If you have a project that's a year behind on dependencies, you'll need to do some work. Let's assume that most dependencies need a `patch` or `minor` update, and at _least_ one dependency needs a `major` update. @@ -147,7 +147,7 @@ Start small, and get the `patch` and `minor` updates first. Read the changelogs for your updates. You may have to make small changes to get things working again. -When you have the latest `patch` and `minor` versions, you are ready for `major` updates. +When you have the latest `patch` and `minor` versions, you're ready for `major` updates. Start with `major` version updates for tools like Prettier or ESLint. Then work on `major` updates for your framework or library. @@ -156,9 +156,9 @@ Let multiple team members review your work before merging, it's easy to miss som Finally, update your development tools. -Now you're up to date, you should think how to make updating a regular habit. +Now you're up-to-date, you should think how to make updating a regular habit. -## Project with five year old dependencies +## Project with dependencies that are five years old Let's assume your Dependency Dashboard lists more than 50 updates, and you have a few `major` version updates pending. If your project is this badly behind on updates, you have two problems: @@ -199,7 +199,7 @@ Use the [`:separateMultipleMajorReleases`](./presets-default.md#separatemultiple ### Update development tools -Finally update development tools like Prettier, ESLint, TSLint, Cypress, and so on. +Finally, update development tools like Prettier, ESLint, TSLint, Cypress, and so on. ### Improve the human side @@ -212,7 +212,7 @@ Avoid blaming developers for not updating often. ## Why developers avoid updating -Let's assume most developers _want_ a project that's up to date. +Let's assume most developers _want_ a project that's up-to-date. So why are your developers avoiding updates? Some common reasons: @@ -230,7 +230,7 @@ Make it easy and fast to update dependencies. ### Talk with your team about the update process Listen to your team, write down their problems. -Then fix each problem as best as you can. +Then fix each problem the best you can. ### Make updating easy and fast @@ -250,7 +250,7 @@ Respect your developer's time and brains: As a starting point: -- Avoid long lived branches that diverge from `main` over time +- Avoid long-lived branches that diverge from `main` over time - Dig beyond "developer error" when things go wrong, again: focus on the process - Ensure company policy allows frequent updates From 8e519684c7c2c78efa090f52c0ee580f8aad4420 Mon Sep 17 00:00:00 2001 From: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> Date: Thu, 28 Dec 2023 05:39:19 +0100 Subject: [PATCH 2/9] chore: Ran prettier Signed-off-by: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> --- docs/development/adding-a-package-manager.md | 2 +- docs/development/branches-commits.md | 2 +- docs/usage/bot-comparison.md | 4 ++-- docs/usage/config-presets.md | 8 ++++---- docs/usage/configuration-options.md | 6 +++--- docs/usage/examples/self-hosting.md | 2 +- docs/usage/faq.md | 4 ++-- docs/usage/merge-confidence.md | 2 +- docs/usage/noise-reduction.md | 2 +- docs/usage/security-and-permissions.md | 4 ++-- docs/usage/self-hosted-configuration.md | 2 +- 11 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/development/adding-a-package-manager.md b/docs/development/adding-a-package-manager.md index a21a9db4e2c2a2..5aa2ca9aae3bcc 100644 --- a/docs/development/adding-a-package-manager.md +++ b/docs/development/adding-a-package-manager.md @@ -16,7 +16,7 @@ Common application logic for Renovate, not specific to particular managers, usua The manager's `index.ts` file supports the following values or functions: | Value/function | Optional | Async | -|-------------------------------|----------|-------| +| ----------------------------- | -------- | ----- | | `bumpPackageVersion` | yes | | | `extractPackageFile` | | yes | | `extractAllPackageFiles` | yes | yes | diff --git a/docs/development/branches-commits.md b/docs/development/branches-commits.md index 1ec1eedc74a58c..e7565764bb1934 100644 --- a/docs/development/branches-commits.md +++ b/docs/development/branches-commits.md @@ -14,7 +14,7 @@ Renovate always creates one commit per branch, even when updating multiple files This keeps Renovate's branches neat, so we can use the following logic: | Last commit in branch made by | Behavior | -|-------------------------------|-------------------------------------------------------------| +| ----------------------------- | ----------------------------------------------------------- | | Renovate | Assume branch is clean | | Someone or something else | Assume branch edited by user, do not push to branch anymore | diff --git a/docs/usage/bot-comparison.md b/docs/usage/bot-comparison.md index f296b0fc2dea98..4abcbdcdd49d40 100644 --- a/docs/usage/bot-comparison.md +++ b/docs/usage/bot-comparison.md @@ -8,7 +8,7 @@ If you see anything wrong on this page, please let us know by creating a [Discus ## Table of features | Feature | Renovate | Dependabot | -|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dependency Dashboard | Yes | No | | Grouped updates | Yes, use community-provided groups, or create your own | Yes, create [`groups`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups) manually | | Upgrades common monorepo packages at once | Yes | No | @@ -68,7 +68,7 @@ If you're an advanced user, you may use the [`dependabot-core` repository](https ### Show changelogs | Feature | Renovate | Dependabot | -|---------------------------------------|------------------------------|---------------------------------| +| ------------------------------------- | ---------------------------- | ------------------------------- | | Link to GitHub release | Yes, to specific release tag | Yes, to "releases landing page" | | Link to GitHub's comparing changes UI | Yes | Yes | | Release notes | Yes | Yes | diff --git a/docs/usage/config-presets.md b/docs/usage/config-presets.md index fe73205c20a941..9300d42df2cd33 100644 --- a/docs/usage/config-presets.md +++ b/docs/usage/config-presets.md @@ -43,7 +43,7 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c ### GitHub | name | example use | preset | resolves as | filename | Git tag | -|---------------------------------------------|----------------------------------|-----------|------------------------------|-----------------|----------------| +| ------------------------------------------- | -------------------------------- | --------- | ---------------------------- | --------------- | -------------- | | GitHub default | `github>abc/foo` | `default` | `https://github.com/abc/foo` | `default.json` | Default branch | | GitHub with preset name | `github>abc/foo:xyz` | `xyz` | `https://github.com/abc/foo` | `xyz.json` | Default branch | | GitHub with preset name (JSON5) | `github>abc/foo:xyz.json5` | `xyz` | `https://github.com/abc/foo` | `xyz.json5` | Default branch | @@ -56,7 +56,7 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c ### GitLab | name | example use | preset | resolves as | filename | Git tag | -|---------------------------------------------|----------------------------------|-----------|------------------------------|-----------------|----------------| +| ------------------------------------------- | -------------------------------- | --------- | ---------------------------- | --------------- | -------------- | | GitLab default | `gitlab>abc/foo` | `default` | `https://gitlab.com/abc/foo` | `default.json` | Default branch | | GitLab with preset name | `gitlab>abc/foo:xyz` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json` | Default branch | | GitLab with preset name (JSON5) | `gitlab>abc/foo:xyz.json5` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json5` | Default branch | @@ -68,7 +68,7 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c ### Gitea | name | example use | preset | resolves as | filename | Git tag | -|--------------------------------------------|---------------------------------|-----------|-----------------------------|-----------------|----------------| +| ------------------------------------------ | ------------------------------- | --------- | --------------------------- | --------------- | -------------- | | Gitea default | `gitea>abc/foo` | `default` | `https://gitea.com/abc/foo` | `default.json` | Default branch | | Gitea with preset name | `gitea>abc/foo:xyz` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json` | Default branch | | Gitea with preset name (JSON5) | `gitea>abc/foo:xyz.json5` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json5` | Default branch | @@ -80,7 +80,7 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c ### Self-hosted Git | name | example use | preset | resolves as | filename | Git tag | -|--------------------------------------------|---------------------------------|-----------|--------------------------------------|-----------------|----------------| +| ------------------------------------------ | ------------------------------- | --------- | ------------------------------------ | --------------- | -------------- | | Local default | `local>abc/foo` | `default` | `https://github.company.com/abc/foo` | `default.json` | Default branch | | Local with preset path | `local>abc/foo:xyz` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json` | Default branch | | Local with preset path (JSON5) | `local>abc/foo:xyz.json5` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json5` | Default branch | diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index 821ccd168675c7..5b67ad6e77d938 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -646,7 +646,7 @@ When `constraintsFiltering=strict`, the following logic applies: Here are some examples: | Your repo `engines.node` | Dependency release `engines.node` | Result | -|--------------------------|-----------------------------------|----------| +| ------------------------ | --------------------------------- | -------- | | `18` | `16 \|\| 18` | allowed | | `^18.10.0` | `>=18` | allowed | | `^16.10.0 \|\| >=18.0.0` | `>= 16.0.0` | allowed | @@ -1847,7 +1847,7 @@ For example, using this option could be used whenever authentication using Git f Supported artifactAuth and hostType combinations: | artifactAuth | hostTypes | -|--------------|---------------------------------------------| +| ------------ | ------------------------------------------- | | `composer` | `gitlab`, `packagist`, `github`, `git-tags` | ### matchHost @@ -2997,7 +2997,7 @@ This way Renovate can use GitHub's [Commit signing support for bots and other Gi Table with options: | Name | Description | -|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bundlerConservative` | Enable conservative mode for `bundler` (Ruby dependencies). This will only update the immediate dependency in the lockfile instead of all subdependencies. | | `gomodMassage` | Enable massaging `replace` directives before calling `go` commands. | | `gomodTidy` | Run `go mod tidy` after Go module updates. This is implicitly enabled for major module updates when `gomodUpdateImportPaths` is enabled. | diff --git a/docs/usage/examples/self-hosting.md b/docs/usage/examples/self-hosting.md index 30f30c3ed93acc..260f8aa06e0313 100644 --- a/docs/usage/examples/self-hosting.md +++ b/docs/usage/examples/self-hosting.md @@ -393,7 +393,7 @@ When you use `LOG_LEVEL=debug` and `LOG_FORMAT=json`, Renovate uses numbers in t The logging level output is controlled by the Bunyan logging library. | Level | Meaning | -|------:|---------| +| ----: | ------- | | 10 | trace | | 20 | debug | | 30 | info | diff --git a/docs/usage/faq.md b/docs/usage/faq.md index d32a918b74be26..248dc072ad8cfb 100644 --- a/docs/usage/faq.md +++ b/docs/usage/faq.md @@ -39,7 +39,7 @@ Major releases of Renovate are held back until the maintainers are reasonably ce ## Renovate core features not supported on all platforms | Feature | Platforms which lack feature | See Renovate issue(s) | -|-----------------------|------------------------------------------------------------|--------------------------------------------------------------| +| --------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | | Dependency Dashboard | Azure, Bitbucket, Bitbucket Server | [#9592](https://github.com/renovatebot/renovate/issues/9592) | | The Mend Renovate App | Azure, Bitbucket, Bitbucket Server, Forgejo, Gitea, GitLab | | @@ -48,7 +48,7 @@ Major releases of Renovate are held back until the maintainers are reasonably ce Some major platform features are not supported at all by Renovate. | Feature name | Platform | See Renovate issue(s) | -|-----------------------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Jira issues | Bitbucket | [#20568](https://github.com/renovatebot/renovate/issues/20568) | | Jira issues | Bitbucket Server | [#3796](https://github.com/renovatebot/renovate/issues/3796) | | Merge trains | GitLab | [#5573](https://github.com/renovatebot/renovate/issues/5573) | diff --git a/docs/usage/merge-confidence.md b/docs/usage/merge-confidence.md index 4936e754db4c6f..01a24c4633abbb 100644 --- a/docs/usage/merge-confidence.md +++ b/docs/usage/merge-confidence.md @@ -28,7 +28,7 @@ Merge Confidence badges for pull requests are available on any supported platfor Renovate will show Merge Confidence badges for these languages: | Language | Datasource | -|------------|-------------| +| ---------- | ----------- | | Golang | `go` | | JavaScript | `npm` | | Java | `maven` | diff --git a/docs/usage/noise-reduction.md b/docs/usage/noise-reduction.md index 4793370eafd5c3..89bc51d401f056 100644 --- a/docs/usage/noise-reduction.md +++ b/docs/usage/noise-reduction.md @@ -185,7 +185,7 @@ Using lock files greatly increases the chance that merging one PR will result in 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 | -|--------------------------------------|--------------------------|-------------------------------| +| ------------------------------------ | ------------------------ | ----------------------------- | | Group dependencies together | Decreases separate PRs | Decreases | | Automerge dependencies | Decreases concurrent PRs | Decreases | | Decrease scheduled time for Renovate | Increases concurrent PRs | Increases | diff --git a/docs/usage/security-and-permissions.md b/docs/usage/security-and-permissions.md index 8126d9ba350765..00632af88d7a48 100644 --- a/docs/usage/security-and-permissions.md +++ b/docs/usage/security-and-permissions.md @@ -31,7 +31,7 @@ We apply the Principle of Least Privilege (PoLP) but do need substantial privile These permissions are always needed to run the respective app. | Permission | The Mend Renovate App | Forking Renovate | Why | -|-------------------|:---------------------:|:------------------:|---------------------------------------------------------------| +| ----------------- | :-------------------: | :----------------: | ------------------------------------------------------------- | | Dependabot alerts | `read` | `read` | Create vulnerability fix PRs | | Administration | `read` | `read` | Read branch protections and to be able to assign teams to PRs | | Metadata | `read` | `read` | Mandatory for all apps | @@ -48,7 +48,7 @@ Renovate can also request users' permission to the following resources. These permissions will be requested and authorized on an individual-user basis. | Permission | The Mend Renovate App | Forking Renovate | Why | -|------------|:---------------------:|:----------------:|----------------------------------------------------------| +| ---------- | :-------------------: | :--------------: | -------------------------------------------------------- | | email | `read` | not applicable | Per-user consent requested if logging into App dashboard | ## Privacy diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index 0ad55f19947b93..9d072a020ba36c 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -843,7 +843,7 @@ This feature is closely related to the `onboarding` config option. The combinations of `requireConfig` and `onboarding` are: | | `onboarding=true` | `onboarding=false` | -|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------| +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `requireConfig=required` | An onboarding PR will be created if no config file exists. If the onboarding PR is closed, and there's no config file, the repository is skipped. | Repository is skipped unless a config file is added manually. | | `requireConfig=optional` | An onboarding PR will be created if no config file exists. If the onboarding PR is closed, and there's no config file, the repository will be processed. | Repository is processed regardless of config file presence. | | `requireConfig=ignored` | No onboarding PR will be created and repo will be processed while ignoring any config file present. | Repository is processed, any config file is ignored. | From 67c23ef52e38d60689c4c29b440a855cf5ae275f Mon Sep 17 00:00:00 2001 From: Koen van Zuijlen <8818390+kvanzuijlen@users.noreply.github.com> Date: Thu, 28 Dec 2023 13:20:20 +0100 Subject: [PATCH 3/9] Apply suggestions from code review (1/2) Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> --- docs/development/branches-commits.md | 4 ++-- .../creating-editing-renovate-presets.md | 12 +++++----- docs/development/design-decisions.md | 8 +++---- docs/development/issue-labeling.md | 4 ++-- docs/development/local-development.md | 17 +++++++------- docs/development/minimal-reproductions.md | 12 +++++----- docs/development/triage-guide.md | 20 ++++++++--------- docs/usage/bazel.md | 16 +++++++------- docs/usage/config-presets.md | 2 +- docs/usage/config-validation.md | 10 ++++----- docs/usage/contributing-to-renovate.md | 22 +++++++++---------- docs/usage/dependency-pinning.md | 6 ++--- docs/usage/docker.md | 18 +++++++-------- docs/usage/examples/self-hosting.md | 2 +- .../getting-started/installing-onboarding.md | 16 +++++++------- .../usage/getting-started/private-packages.md | 4 ++-- docs/usage/noise-reduction.md | 2 +- docs/usage/nuget.md | 2 +- docs/usage/self-hosted-configuration.md | 8 +++---- docs/usage/troubleshooting.md | 2 +- 20 files changed, 94 insertions(+), 93 deletions(-) diff --git a/docs/development/branches-commits.md b/docs/development/branches-commits.md index e7565764bb1934..71642988b82ffa 100644 --- a/docs/development/branches-commits.md +++ b/docs/development/branches-commits.md @@ -25,5 +25,5 @@ This means we let Renovate force-push a single new commit whenever it needs to. For example: 1. Renovate creates a `renovate/jest` branch to update the Jest package to `1.0.1` -2. Renovate later finds a newer `1.1.0` version -3. Renovate force-pushes a new commit for the `1.1.0` update into its `renovate/jest` branch +1. Renovate later finds a newer `1.1.0` version +1. Renovate force-pushes a new commit for the `1.1.0` update into its `renovate/jest` branch diff --git a/docs/development/creating-editing-renovate-presets.md b/docs/development/creating-editing-renovate-presets.md index 1eb402c7940745..1d4e59ad8f87bf 100644 --- a/docs/development/creating-editing-renovate-presets.md +++ b/docs/development/creating-editing-renovate-presets.md @@ -8,7 +8,7 @@ Follow the rules below to increase the chance that your pull request gets merged ## General rules 1. Avoid creating presets for problems which can be fixed upstream -2. The internal preset should be helpful for a significant number of Renovate users +1. The internal preset should be helpful for a significant number of Renovate users ### Specific rules @@ -27,20 +27,20 @@ We have multiple kinds of `group:` presets, with different rules. ##### Rules for `group:*` presets 1. Finally, any other `group:*` presets can be added if they are beneficial to a wide number of users -2. They don't need to be added to `group:recommended`, meaning that users will "opt in" to them one by one and not get them automatically from `config:recommended`, which includes `group:monorepo` and `group:recommended` +1. They don't need to be added to `group:recommended`, meaning that users will "opt in" to them one by one and not get them automatically from `config:recommended`, which includes `group:monorepo` and `group:recommended` #### Replacement presets Rules: 1. Replacement PRs should ideally propose a replacement only once the user is on a compatible version, by specifying a compatible `matchCurrentVersion` constraint -2. If no compatible replacement upgrade is possible, it's acceptable to propose an incompatible one (e.g. a major version upgrade) -3. Replacements should update the user to the first recommended version of the new dependency and not include any new changes - whether breaking or not - if they can be avoided +1. If no compatible replacement upgrade is possible, it's acceptable to propose an incompatible one (e.g. a major version upgrade) +1. Replacements should update the user to the first recommended version of the new dependency and not include any new changes - whether breaking or not - if they can be avoided #### Monorepo presets Rules: 1. The primary use case of monorepo presets is finding packages from the same origin source repository which should be updated together -2. Packages from the same repository which are developed and versioned independently do not need to be grouped as a monorepo, but in many cases we still do -3. Packages from separate repositories but which are released together and dependent on each other may also be added to the "monorepo" definitions even if not strictly true +1. Packages from the same repository which are developed and versioned independently do not need to be grouped as a monorepo, but in many cases we still do +1. Packages from separate repositories but which are released together and dependent on each other may also be added to the "monorepo" definitions even if not strictly true diff --git a/docs/development/design-decisions.md b/docs/development/design-decisions.md index a95dde37c1f4bb..16672b110feb9d 100644 --- a/docs/development/design-decisions.md +++ b/docs/development/design-decisions.md @@ -32,10 +32,10 @@ This means that specific configuration options always override more general conf From most specific to least specific: 1. Update type (e.g. `major`, `minor`, `patch`) -2. Package (e.g. `lodash`, `django`) -3. Manager (e.g. `npm`, `pypi`) -4. Repository config -5. Global configuration +1. Package (e.g. `lodash`, `django`) +1. Manager (e.g. `npm`, `pypi`) +1. Repository config +1. Global configuration ## Automatic discovery of package file locations diff --git a/docs/development/issue-labeling.md b/docs/development/issue-labeling.md index 3e0ac21a13ac5b..f3d7ac9d100bfa 100644 --- a/docs/development/issue-labeling.md +++ b/docs/development/issue-labeling.md @@ -198,8 +198,8 @@ Add a label `auto:format-code` to any Discussion which needs code formatting. Add a label `auto:logs` to indicate that there's a problem with the logs, and the contributor needs to do one of these things: 1. Provide logs (if there are none yet) -2. Provide more logs (in case current logs are insufficient) -3. Format their logs properly +1. Provide more logs (in case current logs are insufficient) +1. Format their logs properly Add a label `auto:needs-details` to discussions which need more details to move forward. diff --git a/docs/development/local-development.md b/docs/development/local-development.md index 0ad7c6aa9b8b21..fbf98e63441455 100644 --- a/docs/development/local-development.md +++ b/docs/development/local-development.md @@ -96,18 +96,19 @@ The Renovate project uses the [pnpm](https://github.com/pnpm/pnpm) package manag To ensure everything is working properly on your end, you must: 1. Install all dependencies with `pnpm install` -2. Make a build with `pnpm build`, which should pass with no errors -3. Verify all tests pass and have 100% test coverage, by running `pnpm test` -4. Verify the installation by running `pnpm start`. You must see this error: `You must configure a GitHub personal access token` +1. Make a build with `pnpm build`, which should pass with no errors +1. Verify all tests pass and have 100% test coverage, by running `pnpm test` +1. Verify the installation by running `pnpm start`. You must see this error: `You must configure a GitHub personal access token` -Do not worry about the token error for now, as you'll be given instructions on how to configure the token a little later down in this document. +Don't worry about the token error for now. +You'll configure the token properly a little later, so keep reading. You only need to do these steps once. Before you submit a pull request you should: 1. Install newer dependencies with `pnpm install` -2. Run the tests with `pnpm test` +1. Run the tests with `pnpm test` ## Platform Account Setup @@ -215,9 +216,9 @@ You can debug Renovate with Chrome's inspect tool. Here's an example: 1. Open `chrome://inspect` in Chrome, then select "Open dedicated DevTools for Node" -2. Add a `debugger;` statement somewhere in the source code where you want to start debugging -3. Run Renovate using `pnpm debug ...` instead of `pnpm start ...` -4. Select "Resume script execution" in Chrome DevTools and wait for your break point to be triggered +1. Add a `debugger;` statement somewhere in the source code where you want to start debugging +1. Run Renovate using `pnpm debug ...` instead of `pnpm start ...` +1. Select "Resume script execution" in Chrome DevTools and wait for your break point to be triggered ### VS Code diff --git a/docs/development/minimal-reproductions.md b/docs/development/minimal-reproductions.md index cdaf56b12f53bf..4d4232b4d87af5 100644 --- a/docs/development/minimal-reproductions.md +++ b/docs/development/minimal-reproductions.md @@ -45,12 +45,12 @@ There are two ways to create a minimal reproduction: General steps: 1. Create your minimal reproduction repository on GitHub, only use GitLab or Bitbucket if really needed -2. Use the fewest number of repository files and dependencies -3. Reduce the Renovate config to a minimum -4. Remove private or secret information -5. Create a `readme.md` file that explains the current behavior and expected behavior -6. Set the repository visibility to `public` -7. Give us the link to the repository +1. Use the fewest number of repository files and dependencies +1. Reduce the Renovate config to a minimum +1. Remove private or secret information +1. Create a `readme.md` file that explains the current behavior and expected behavior +1. Set the repository visibility to `public` +1. Give us the link to the repository ### Why we won't use your production repository to debug diff --git a/docs/development/triage-guide.md b/docs/development/triage-guide.md index ddf90b304d00cf..e88e19e3deb4e0 100644 --- a/docs/development/triage-guide.md +++ b/docs/development/triage-guide.md @@ -13,20 +13,20 @@ The general triage workflow is similar for bug reports and feature requests, but Take the following steps on an incoming bug report: 1. Determine if this is a valid bug report at all, close and optionally delete obvious spam. -2. If poster is asking a configuration question, or has not made a convincing case that it's really a bug, then convert to an "Ask a question" discussion, add either a response or at least a note that it's been converted. -3. Determine if this is a duplicate of an open issue/discussion, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. -4. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. -5. Check if the _relevant_ logs are provided. If not apply the `auto:logs` label. +1. If poster is asking a configuration question, or has not made a convincing case that it's really a bug, then convert to an "Ask a question" discussion, add either a response or at least a note that it's been converted. +1. Determine if this is a duplicate of an open issue/discussion, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. +1. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. +1. Check if the _relevant_ logs are provided. If not apply the `auto:logs` label. ### Triaging feature requests workflow Take the following steps on an incoming feature request: 1. Determine if this is a valid feature request at all, close and optionally delete obvious spam. -2. If poster is asking a configuration question, or has not made a convincing case that it's really a feature request, then convert to an "Ask a question" discussion, add either a response or at least a note that it's been converted. -3. Determine if this is a duplicate of an open issue, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. -4. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. -5. Make a best-effort judgement if this is a reasonable feature to put into Renovate. If in doubt, let the core maintainers decide. +1. If poster is asking a configuration question, or has not made a convincing case that it's really a feature request, then convert to an "Ask a question" discussion, add either a response or at least a note that it's been converted. +1. Determine if this is a duplicate of an open issue, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. +1. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. +1. Make a best-effort judgement if this is a reasonable feature to put into Renovate. If in doubt, let the core maintainers decide. ## Creating new issues from discussions @@ -100,8 +100,8 @@ You can assign whoever makes sense. If you see an issue/discussion that's an obvious duplicate: 1. Attach a `duplicate` label -2. Use the "Duplicate of" functionality [GitHub docs, about duplicate issues and pull requests](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-duplicate-issues-and-pull-requests) -3. Close the issue/discussion +1. Use the "Duplicate of" functionality [GitHub docs, about duplicate issues and pull requests](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-duplicate-issues-and-pull-requests) +1. Close the issue/discussion Follow the same workflow to mark duplicate PRs. diff --git a/docs/usage/bazel.md b/docs/usage/bazel.md index 469bd4db672605..e63054570e36cf 100644 --- a/docs/usage/bazel.md +++ b/docs/usage/bazel.md @@ -10,9 +10,9 @@ Renovate upgrades dependencies in Bazel `WORKSPACE` files and `MODULE.bazel` fil ## How it works 1. Bazel support is enabled automatically -2. Renovate searches the repository for any `WORKSPACE` and `MODULE.bazel` files -3. Renovate extracts the dependencies it finds from the files (see below for the supported dependency declarations) -4. Renovate updates old dependencies to the latest version +1. Renovate searches the repository for any `WORKSPACE` and `MODULE.bazel` files +1. Renovate extracts the dependencies it finds from the files (see below for the supported dependency declarations) +1. Renovate updates old dependencies to the latest version ## Bazel module (`MODULE.bazel`) support @@ -48,7 +48,7 @@ build --registry=https://example.com/custom_registry The final registry list is: 1. `` -2. `` +1. `` #### Example: registry entries using Bazel configuration @@ -165,8 +165,8 @@ For example, `_http_archive` is treated the same as `http_archive`. Renovate updates any `git_repository` declaration that has the following: 1. `name` -2. `remote` matching `https://github.com//.git` -3. `tag` using a valid SemVer +1. `remote` matching `https://github.com//.git` +1. `tag` using a valid SemVer e.g.: @@ -185,8 +185,8 @@ Renovate uses the list of **tags** on the remote repository (GitHub) to detect a Renovate updates any `http_archive` or `http_file` declaration that has the following: 1. `name` -2. `url` matching `https://github.com///releases/download//.tar.gz` -3. `sha256` +1. `url` matching `https://github.com///releases/download//.tar.gz` +1. `sha256` e.g.: diff --git a/docs/usage/config-presets.md b/docs/usage/config-presets.md index 9300d42df2cd33..a34c779fc28de6 100644 --- a/docs/usage/config-presets.md +++ b/docs/usage/config-presets.md @@ -92,7 +92,7 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c !!! tip - You can't combine the path and sub-preset syntax. + You can't combine the path and sub-preset syntaxes. This means that anything in the form `provider>owner/repo//path/to/file:subsubpreset` is not supported. One workaround is to use distinct files instead of sub-presets. diff --git a/docs/usage/config-validation.md b/docs/usage/config-validation.md index 6179d6120111a4..f6b6f36a362f11 100644 --- a/docs/usage/config-validation.md +++ b/docs/usage/config-validation.md @@ -56,12 +56,12 @@ Renovate can validate configuration changes in Pull Requests when you use a spec Follow these steps to validate your configuration: 1. Create a new Git branch that matches the `{{branchPrefix}}reconfigure` pattern. For example, if you're using the default prefix `renovate/`, your branch name must be `renovate/reconfigure`. -2. Commit your updated Renovate config file to this branch, and push it to your Git hosting platform. +1. Commit your updated Renovate config file to this branch, and push it to your Git hosting platform. The next time Renovate runs on that repo it will: 1. Search for a branch that matches the special reconfigure pattern. -2. Check for a config file in the reconfigure branch. Renovate can even find a renamed configuration file (compared to the config file in the default branch). -3. Add a passing or failing status to the branch, depending on the outcome of the config validation run. -4. If there's an _open_ pull request with validation errors from the _reconfigure_ branch then Renovate comments in the PR with details. -5. Validate each commit the next time Renovate runs on the repository, until the PR is merged. +1. Check for a config file in the reconfigure branch. Renovate can even find a renamed configuration file (compared to the config file in the default branch). +1. Add a passing or failing status to the branch, depending on the outcome of the config validation run. +1. If there's an _open_ pull request with validation errors from the _reconfigure_ branch then Renovate comments in the PR with details. +1. Validate each commit the next time Renovate runs on the repository, until the PR is merged. diff --git a/docs/usage/contributing-to-renovate.md b/docs/usage/contributing-to-renovate.md index fe2820ef0aca38..cd4090b16814f6 100644 --- a/docs/usage/contributing-to-renovate.md +++ b/docs/usage/contributing-to-renovate.md @@ -8,8 +8,8 @@ The [`docs/development/` directory of the `renovatebot/renovate` repository](htt ### Read this first 1. [Contributing guide](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) -2. [Best practices](https://github.com/renovatebot/renovate/blob/main/docs/development/best-practices.md) -3. [Local Development](https://github.com/renovatebot/renovate/blob/main/docs/development/local-development.md) or [Remote Development](https://github.com/renovatebot/renovate/blob/main/docs/development/remote-development.md) +1. [Best practices](https://github.com/renovatebot/renovate/blob/main/docs/development/best-practices.md) +1. [Local Development](https://github.com/renovatebot/renovate/blob/main/docs/development/local-development.md) or [Remote Development](https://github.com/renovatebot/renovate/blob/main/docs/development/remote-development.md) ### Creating/editing Renovate preset @@ -22,11 +22,11 @@ The [`docs/development/` directory of the `renovatebot/renovate` repository](htt ### Background information 1. [Design Decisions](https://github.com/renovatebot/renovate/blob/main/docs/development/design-decisions.md) -2. [Zod schema guideline](https://github.com/renovatebot/renovate/blob/main/docs/development/zod.md) -3. [Branches and commits behavior](https://github.com/renovatebot/renovate/blob/main/docs/development/branches-commits.md) -4. [Configuration](https://github.com/renovatebot/renovate/blob/main/docs/development/configuration.md) -5. [Static Data](https://github.com/renovatebot/renovate/blob/main/docs/development/static-data.md) -6. [How to bump Renovate to next NodeJS LTS release](https://github.com/renovatebot/renovate/blob/main/docs/development/bump-node-major.md) +1. [Zod schema guideline](https://github.com/renovatebot/renovate/blob/main/docs/development/zod.md) +1. [Branches and commits behavior](https://github.com/renovatebot/renovate/blob/main/docs/development/branches-commits.md) +1. [Configuration](https://github.com/renovatebot/renovate/blob/main/docs/development/configuration.md) +1. [Static Data](https://github.com/renovatebot/renovate/blob/main/docs/development/static-data.md) +1. [How to bump Renovate to next NodeJS LTS release](https://github.com/renovatebot/renovate/blob/main/docs/development/bump-node-major.md) ## I want to write documentation @@ -37,11 +37,11 @@ Read the [Contributing guide](https://github.com/renovatebot/renovate/blob/main/ Start by reading: 1. [Contributing guide](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) -2. [Triage guide](https://github.com/renovatebot/renovate/blob/main/docs/development/triage-guide.md) -3. [Issue labeling](https://github.com/renovatebot/renovate/blob/main/docs/development/issue-labeling.md) +1. [Triage guide](https://github.com/renovatebot/renovate/blob/main/docs/development/triage-guide.md) +1. [Issue labeling](https://github.com/renovatebot/renovate/blob/main/docs/development/issue-labeling.md) You may need to direct a Renovate user to one of these pages: 1. [About minimal reproductions](https://github.com/renovatebot/renovate/blob/main/docs/development/minimal-reproductions.md) -2. [New package manager questionnaire](https://github.com/renovatebot/renovate/blob/main/docs/development/new-package-manager-template.md) -3. [Help Us Help You](https://github.com/renovatebot/renovate/blob/main/docs/development/help-us-help-you.md) +1. [New package manager questionnaire](https://github.com/renovatebot/renovate/blob/main/docs/development/new-package-manager-template.md) +1. [Help Us Help You](https://github.com/renovatebot/renovate/blob/main/docs/development/help-us-help-you.md) diff --git a/docs/usage/dependency-pinning.md b/docs/usage/dependency-pinning.md index 63a9ea3f22f70f..a75108abae1902 100644 --- a/docs/usage/dependency-pinning.md +++ b/docs/usage/dependency-pinning.md @@ -59,7 +59,7 @@ This benefits when upgrading versions as well as when rolling back in case of pr ### Upgrading pinned versions -Let's say that a "faulty" version `1.2.0` of `foobar` is released, and it breaks one of your tests. +Let's say that a "faulty" version `1.2.0` of `foobar` is released which breaks one of your tests. If you were using default caret SemVer ranges, then your `main` 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`. @@ -135,7 +135,7 @@ To learn all about controlling Renovate's schedule, read the [key concepts, sche ### 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 one branch combined even if multiple packages have updates available. +You can add a package rule in your Renovate configuration to group these together, and you'll get one branch combined even if multiple packages have updates available. ## Pinning Dependencies and Lock Files @@ -208,7 +208,7 @@ 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.?). +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, and so on). 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 dependencies for breaks than I am, to use the example above. diff --git a/docs/usage/docker.md b/docs/usage/docker.md index 2171f8ce59fa7f..9f8a0838e28100 100644 --- a/docs/usage/docker.md +++ b/docs/usage/docker.md @@ -16,8 +16,8 @@ Renovate supports upgrading dependencies in various types of Docker definition f ## How It Works 1. Renovate searches in each repository for any files matching each manager's configured `fileMatch` pattern(s) -2. Matching files are parsed, Renovate checks if the file(s) has any Docker image references (e.g. `FROM` lines in a `Dockerfile`) -3. If the image tag in use "looks" like a version (e.g. `myimage:1`, `myimage:1.1`, `myimage:1.1.0`, `myimage:1-onbuild`) then Renovate checks the Docker registry for upgrades (e.g. from `myimage:1.1.0` to `myimage:1.2.0`) +1. Matching files are parsed, Renovate checks if the file(s) has any Docker image references (e.g. `FROM` lines in a `Dockerfile`) +1. If the image tag in use "looks" like a version (e.g. `myimage:1`, `myimage:1.1`, `myimage:1.1.0`, `myimage:1-onbuild`) then Renovate checks the Docker registry for upgrades (e.g. from `myimage:1.1.0` to `myimage:1.2.0`) ## Preservation of Version Precision @@ -276,8 +276,8 @@ Google Artifact Registry supports `_json_key_base64` and a base64 encoded servic If all your dependencies are on the Google Artifact Registry, you can base64 encode and use the service account directly: 1. Download your JSON service account and store it on your machine. Make sure that the service account has `read` (and only `read`) permissions to your artifacts -2. Base64 encode the service account credentials by running `cat service-account.json | base64` -3. Add the encoded service account to your configuration file +1. Base64 encode the service account credentials by running `cat service-account.json | base64` +1. Add the encoded service account to your configuration file 1. If you want to add it to your self-hosted configuration file: @@ -293,7 +293,7 @@ If all your dependencies are on the Google Artifact Registry, you can base64 enc } ``` - 2. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: + 1. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: ```json { @@ -312,7 +312,7 @@ If all your dependencies are on the Google Artifact Registry, you can base64 enc If you have dependencies on Google Container Registry (and Artifact Registry) you need to use `_json_key` and a slightly different encoding: 1. Download your JSON service account and store it on your machine. Make sure that the service account has `read` (and only `read`) permissions to your artifacts -2. Open the file and prefix the content with `_json_key:`. The file should look like this: +1. Open the file and prefix the content with `_json_key:`. The file should look like this: ``` _json_key:{ @@ -329,8 +329,8 @@ If you have dependencies on Google Container Registry (and Artifact Registry) yo } ``` -3. Base64 encode the prefixed service account credentials by running `cat prefixed-service-account.json | base64` -4. Add the prefixed and encoded service account to your configuration file +1. Base64 encode the prefixed service account credentials by running `cat prefixed-service-account.json | base64` +1. Add the prefixed and encoded service account to your configuration file 1. If you want to add it to your self-hosted configuration file: @@ -346,7 +346,7 @@ If you have dependencies on Google Container Registry (and Artifact Registry) yo } ``` - 2. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: + 1. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: ```json { diff --git a/docs/usage/examples/self-hosting.md b/docs/usage/examples/self-hosting.md index 260f8aa06e0313..d16f4bab2029ae 100644 --- a/docs/usage/examples/self-hosting.md +++ b/docs/usage/examples/self-hosting.md @@ -281,7 +281,7 @@ Only add the script to `cron` after you checked it works. This section describes how to use a Git binary with SSH for GitLab, to avoid API shortcomings. -You first need to create an SSH key, then add the public part to GitLab (see this [guide](https://docs.gitlab.com/ee/ssh/)). +Create an SSH key and then add the public part to GitLab (see this [guide](https://docs.gitlab.com/ee/ssh/)). Then, you need to create the secret to add the SSH key, and the following config to your container: diff --git a/docs/usage/getting-started/installing-onboarding.md b/docs/usage/getting-started/installing-onboarding.md index 4d8d43c7841e97..bd41ec4a800e9b 100644 --- a/docs/usage/getting-started/installing-onboarding.md +++ b/docs/usage/getting-started/installing-onboarding.md @@ -15,7 +15,7 @@ Otherwise, the process for adding new repositories to a Renovate installation ca Follow these steps to install and enable the Mend Renovate App: -First, navigate to [https://github.com/apps/renovate](https://github.com/apps/renovate) and select the "Install" button: +First, navigate to [https://github.com/apps/renovate](https://github.com/apps/renovate) and select the _Install_ button: ![The Mend Renovate App Install button](../assets/images/github-app-install.png){ loading=lazy } @@ -27,7 +27,7 @@ Renovate will ignore any repositories that don't have known package files, as we That said, most people run Renovate on selected repositories. Unfortunately GitHub doesn't offer a "select all except X, Y, Z" option, so you must select each repository where you want Renovate to run. -Once you're done selecting repositories for Renovate to run on, select the green "Install" button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. +Once you're done selecting repositories for Renovate to run on, select the green _Install_ button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. !!! note @@ -131,10 +131,10 @@ There are two recommended approaches: If you want to make config edits directly, follow these steps: 1. Create a new Git branch to work on -2. Install or update the `renovate` package globally (`npm i -g renovate` or `yarn global add renovate`) to get the `renovate-config-validator` program -3. Edit your Renovate configuration file -4. [Validate your config](../config-validation.md) -5. If the improved config passes the validation, merge the branch into your mainline branch +1. Install or update the `renovate` package globally (`npm i -g renovate` or `yarn global add renovate`) to get the `renovate-config-validator` program +1. Edit your Renovate configuration file +1. [Validate your config](../config-validation.md) +1. If the improved config passes the validation, merge the branch into your mainline branch ### Nuke config and re-onboard @@ -143,8 +143,8 @@ You can follow the steps below to nuke the config and get a new PR. Any existing Renovate PRs will be closed after you've completed these steps. 1. Find your original `Configure Renovate` PR -2. Rename the original PR to something else, e.g. `Configure Renovate - old` -3. Remove the current Renovate configuration file (e.g. `renovate.json`) from your mainline branch +1. Rename the original PR to something else, e.g. `Configure Renovate - old` +1. Remove the current Renovate configuration file (e.g. `renovate.json`) from your mainline branch Following these steps will trick Renovate into thinking that your repository was _never_ onboarded, and will trigger a new "Configure Renovate" PR. If you're using the Mend Renovate App and you don't get a new onboarding PR within a few hours, then please create a Discussions post to request staff trigger it manually. diff --git a/docs/usage/getting-started/private-packages.md b/docs/usage/getting-started/private-packages.md index d97c09d769511d..791a572a0983f1 100644 --- a/docs/usage/getting-started/private-packages.md +++ b/docs/usage/getting-started/private-packages.md @@ -10,7 +10,7 @@ First, a quick note on terminology: ## When does Renovate need credentials? -By default, the only credentials Renovate has, are those for the "platform", i.e. GitHub, GitLab, etc. +By default, Renovate only has "platform" credentials, for GitHub, GitLab, and so on. If the token used has sufficient permissions, this will enable Renovate to lookup dependencies located in alternative repositories on the same host or any hosted on any embedded package registry on the same host. It's also quite common to need to look up packages on other protected hosts, including npmjs, Docker Hub, or private registries like Nexus or Artifactory. @@ -31,7 +31,7 @@ There are four times in Renovate's behavior when it may need credentials: Renovate supports config presets, including those which are private. -Although npm presets were the first type supported, they are now deprecated, and it is recommended that all users migrate to git-hosted "local" presets instead. +Although npm presets were the first type supported, they are now deprecated, and we recommend that all users migrate to git-hosted "local" presets instead. However, if you do still use them, private modules should work if you configure `hostRules` (recommended) or `npmrc` including token credentials in your bot global config. It is strongly recommended not to use private modules on a private registry and a warning will be logged if that is found. Credentials stored on disk (e.g. in `~/.npmrc`) are no longer supported. diff --git a/docs/usage/noise-reduction.md b/docs/usage/noise-reduction.md index 89bc51d401f056..b6706268d190bd 100644 --- a/docs/usage/noise-reduction.md +++ b/docs/usage/noise-reduction.md @@ -196,7 +196,7 @@ First of all, if you ever have any ideas about how to make Renovate less noisy, Our philosophy is: 1. Nearly everyone should use Renovate-like dependency update automation -2. Over time, you should "see" Renovate less and less +1. 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. diff --git a/docs/usage/nuget.md b/docs/usage/nuget.md index 838bc200a9b781..2e6cd063e468af 100644 --- a/docs/usage/nuget.md +++ b/docs/usage/nuget.md @@ -18,7 +18,7 @@ By default, this includes: - .NET Core 1.0 and above - .NET Standard class libraries -- `.csproj`, `.fsproj` or `.vbproj` files that use the SDK-style syntaxes +- `.csproj`, `.fsproj` or `.vbproj` files that use SDK-style syntaxes To convert your .NET Framework `.csproj`, `.fsproj` or `.vbproj` files into an SDK-style project, follow the steps in this [guide](https://natemcmaster.com/blog/2017/03/09/vs2015-to-vs2017-upgrade/). diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index 9d072a020ba36c..31ba81cf19696d 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -431,7 +431,7 @@ Information provided mainly in debug log level. ## executionTimeout Default execution timeout in minutes for child processes Renovate creates. -If this option is not set, Renovate will fall back to 15 minutes. +If this option is not set, Renovate defaults to 15 minutes. ## exposeAllEnv @@ -471,7 +471,7 @@ This can be used if you're migrating from user-based forks to organization-based If you've set a `forkOrg` then Renovate will: 1. Check if a fork exists in the preferred organization before checking it exists in the fork user's account -2. If no fork exists: it will be created in the `forkOrg`, not the user account +1. If no fork exists: it will be created in the `forkOrg`, not the user account ## forkToken @@ -502,7 +502,7 @@ It will be loaded _lazily_. Before the first commit in a repository, Renovate will: 1. Run `gpg import` (if you haven't before) -2. Run `git config user.signingkey` and `git config commit.gpgsign true` +1. Run `git config user.signingkey` and `git config commit.gpgsign true` The `git` commands are run locally in the cloned repo instead of globally. This reduces the chance of unintended consequences of global Git configs on shared systems. @@ -894,7 +894,7 @@ Secret names must start with an upper or lower case character and can have only ## 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 installation of modules will be done. +If this is set to `false`, then a full installation of modules will be done. This is currently applicable to `npm` only, and only used in cases where bugs in `npm` result in incorrect lock files being updated. ## token diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md index 4a2a3b481a1a29..9510cabd82c8d6 100644 --- a/docs/usage/troubleshooting.md +++ b/docs/usage/troubleshooting.md @@ -30,7 +30,7 @@ For a full overview, select the `DEBUG` log level. The easiest way to gather logs from Renovate for any platform is to use the default logging to `stdout`/console. By default, Renovate will log in a human-readable format at `INFO` level. -For troubleshooting, it's recommended to increase logging to `DEBUG` level by adding `LOG_LEVEL=debug` to your environment variables before invoking Renovate. +For troubleshooting, we recommend you increase the logging to `DEBUG` level by adding `LOG_LEVEL=debug` to your environment variables before invoking Renovate. If your Renovate logs are being processed by a log service before you access them, you may find it better to have Renovate output logs in JSON format instead so that they can be reliably parsed and filtered. This can be achieved by adding `LOG_FORMAT=json` to your environment variables before invoking Renovate. From c858452e49286c706d703fa039a0222ca5d6aee0 Mon Sep 17 00:00:00 2001 From: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> Date: Thu, 28 Dec 2023 15:00:41 +0100 Subject: [PATCH 4/9] chore: avoid manually ordering numbered lists Signed-off-by: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> --- docs/development/local-development.md | 6 +- docs/usage/bicep.md | 4 +- docs/usage/configuration-options.md | 56 +++++++++---------- docs/usage/dependency-pinning.md | 6 +- docs/usage/faq.md | 6 +- .../usage/getting-started/private-packages.md | 8 +-- docs/usage/getting-started/use-cases.md | 22 ++++---- docs/usage/golang.md | 18 +++--- docs/usage/java.md | 8 +-- docs/usage/key-concepts/changelogs.md | 16 +++--- docs/usage/key-concepts/how-renovate-works.md | 10 ++-- docs/usage/key-concepts/pull-requests.md | 8 +-- docs/usage/key-concepts/scheduling.md | 6 +- docs/usage/noise-reduction.md | 4 +- docs/usage/nuget.md | 6 +- docs/usage/php.md | 8 +-- docs/usage/python.md | 6 +- docs/usage/ruby.md | 6 +- docs/usage/rust.md | 8 +-- docs/usage/self-hosted-configuration.md | 4 +- docs/usage/troubleshooting.md | 4 +- docs/usage/updating-rebasing.md | 4 +- 22 files changed, 112 insertions(+), 112 deletions(-) diff --git a/docs/development/local-development.md b/docs/development/local-development.md index fbf98e63441455..e5561af1eeb31a 100644 --- a/docs/development/local-development.md +++ b/docs/development/local-development.md @@ -226,7 +226,7 @@ You can also debug Renovate with VS Code. Here's an example: 1. In the configuration file, e.g. `config.js` in the root directory of the project, add `token` with your Personal Access Token -2. In the same configuration file, add `repositories` with the repository you want to test against. The file `config.js` would look something like this: +1. In the same configuration file, add `repositories` with the repository you want to test against. The file `config.js` would look something like this: ```javascript module.exports = { @@ -235,5 +235,5 @@ Here's an example: }; ``` -3. Set a breakpoint somewhere in the source code and launch the application in debug mode with selected configuration as `debug` -4. Wait for your breakpoint to be triggered +1. Set a breakpoint somewhere in the source code and launch the application in debug mode with selected configuration as `debug` +1. Wait for your breakpoint to be triggered diff --git a/docs/usage/bicep.md b/docs/usage/bicep.md index ae21a09c0f956a..34ea15feff81d6 100644 --- a/docs/usage/bicep.md +++ b/docs/usage/bicep.md @@ -11,8 +11,8 @@ Upgrading `module` versions is not supported. ## How it works 1. Renovate searches for `.bicep` files. -2. Renovate parses the files for `resource` types and API versions. -3. Renovate looks up the latest version in the [Azure/bicep-types-az](https://github.com/Azure/bicep-types-az) repository. +1. Renovate parses the files for `resource` types and API versions. +1. Renovate looks up the latest version in the [Azure/bicep-types-az](https://github.com/Azure/bicep-types-az) repository. ## Known issues diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index 5b67ad6e77d938..1c01c7f210a33a 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -11,15 +11,15 @@ Any config you define applies to the whole repository (e.g. if you have a monore You can store your Renovate configuration file in one of these locations: 1. `renovate.json` -2. `renovate.json5` -3. `.github/renovate.json` -4. `.github/renovate.json5` -5. `.gitlab/renovate.json` -6. `.gitlab/renovate.json5` -7. `.renovaterc` -8. `.renovaterc.json` -9. `.renovaterc.json5` -10. `package.json` _(within a `"renovate"` section)_ +1. `renovate.json5` +1. `.github/renovate.json` +1. `.github/renovate.json5` +1. `.gitlab/renovate.json` +1. `.gitlab/renovate.json5` +1. `.renovaterc` +1. `.renovaterc.json` +1. `.renovaterc.json5` +1. `package.json` _(within a `"renovate"` section)_ !!! warning @@ -1575,8 +1575,8 @@ Example for configuring `docker` auth: If multiple `hostRules` match a request, then they will be applied in the following order/priority: 1. rules with only `hostType` specified -2. rules with only `matchHost` specified (sorted by `matchHost` length if multiple match) -3. rules with both `matchHost` and `hostType` specified (sorted by `matchHost` length if multiple match) +1. rules with only `matchHost` specified (sorted by `matchHost` length if multiple match) +1. rules with both `matchHost` and `hostType` specified (sorted by `matchHost` length if multiple match) To disable requests to a particular host, you can configure a rule like: @@ -3192,10 +3192,10 @@ Slowing Renovate down can be handy when you're onboarding a repository with a lo What may happen if you don't set a `prHourlyLimit`: 1. Renovate creates an Onboarding PR -2. You merge the onboarding PR to activate Renovate -3. Renovate creates a "Pin Dependencies" PR (if needed) -4. You merge the "Pin Dependencies" PR -5. Renovate creates every single upgrade PR needed, which can be a lot +1. You merge the onboarding PR to activate Renovate +1. Renovate creates a "Pin Dependencies" PR (if needed) +1. You merge the "Pin Dependencies" PR +1. Renovate creates every single upgrade PR needed, which can be a lot The above may cause: @@ -3229,11 +3229,11 @@ By default, Renovate sorts/prioritizes based on the update type, going from the Renovate creates update PRs in this order: 1. `pinDigest` -2. `pin` -3. `digest` -4. `patch` -5. `minor` -6. `major` +1. `pin` +1. `digest` +1. `patch` +1. `minor` +1. `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 setting a negative value will make dependencies sort last, while higher values sort first. @@ -3297,9 +3297,9 @@ Behavior: Renovate's `"auto"` strategy works like this for npm: 1. Widen `peerDependencies` -2. If an existing range already ends with an "or" operator like `"^1.0.0 || ^2.0.0"`, then Renovate widens it into `"^1.0.0 || ^2.0.0 || ^3.0.0"` -3. Otherwise, if the update is outside the existing range, Renovate replaces the range. So `"^2.0.0"` is replaced by `"^3.0.0"` -4. Finally, if the update is in-range, Renovate will update the lockfile with the new exact version. +1. If an existing range already ends with an "or" operator like `"^1.0.0 || ^2.0.0"`, then Renovate widens it into `"^1.0.0 || ^2.0.0 || ^3.0.0"` +1. Otherwise, if the update is outside the existing range, Renovate replaces the range. So `"^2.0.0"` is replaced by `"^3.0.0"` +1. Finally, if the update is in-range, Renovate will update the lockfile with the new exact version. By default, Renovate assumes that if you're using ranges then it's because you want them to be wide/open. Renovate won't deliberately "narrow" any range by increasing the semver value inside. @@ -3756,11 +3756,11 @@ For this to work, you must enable the [Dependency graph](https://docs.github.com Follow these steps: 1. While logged in to GitHub, navigate to your repository -2. Select the "Settings" tab -3. Select "Code security and analysis" in the sidebar -4. Enable the "Dependency graph" -5. Enable "Dependabot alerts" -6. If you're running Renovate in app mode: make sure the app has `read` permissions for "Dependabot alerts". +1. Select the "Settings" tab +1. Select "Code security and analysis" in the sidebar +1. Enable the "Dependency graph" +1. Enable "Dependabot alerts" +1. If you're running Renovate in app mode: make sure the app has `read` permissions for "Dependabot alerts". If you're the account administrator, browse to the app (for example [the Mend Renovate App](https://github.com/apps/renovate)), select "Configure", and then scroll down to the "Permissions" section and make sure that `read` access to "Dependabot alerts" is mentioned Once the above conditions are met, and you got one or more vulnerability alerts from GitHub for this repository, then Renovate tries to raise fix PRs. diff --git a/docs/usage/dependency-pinning.md b/docs/usage/dependency-pinning.md index a75108abae1902..5233d6363c8545 100644 --- a/docs/usage/dependency-pinning.md +++ b/docs/usage/dependency-pinning.md @@ -219,9 +219,9 @@ But certainly "does it give a false sense of security" is not a question we can We recommend: 1. Any apps (web or Node.js) that aren't `require()`'d by other packages should pin all types of dependencies for greatest reliability/predictability -2. Browser or dual browser/node.js libraries that are consumed/`required()`'d by others should keep using SemVer ranges for `dependencies` but can use pinned dependencies for `devDependencies` -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 +1. Browser or dual browser/node.js libraries that are consumed/`required()`'d by others should keep using SemVer ranges for `dependencies` but can use pinned dependencies for `devDependencies` +1. 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 +1. Use a lock file As noted earlier, when you pin dependencies then you'll 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. diff --git a/docs/usage/faq.md b/docs/usage/faq.md index 248dc072ad8cfb..a371da56643763 100644 --- a/docs/usage/faq.md +++ b/docs/usage/faq.md @@ -181,9 +181,9 @@ Set the configuration option `labels` to an array of labels to use. ### Apply a rule, but only to package `abc`? 1. Add a `packageRules` array to your configuration -2. Create one object inside this array -3. Set field `matchPackageNames` to value `["abc"]` -4. Add the configuration option to the same object +1. Create one object inside this array +1. Set field `matchPackageNames` to value `["abc"]` +1. Add the configuration option to the same object e.g. diff --git a/docs/usage/getting-started/private-packages.md b/docs/usage/getting-started/private-packages.md index 791a572a0983f1..2fd94a2d4e11a6 100644 --- a/docs/usage/getting-started/private-packages.md +++ b/docs/usage/getting-started/private-packages.md @@ -228,8 +228,8 @@ If you need to configure per-repository credentials then you can also configure The recommended approaches in order of preference are: 1. **Self-hosted hostRules**: Configure a hostRules entry in the bot's `config.js` with the `hostType`, `matchHost` and `token` specified -2. **The Mend Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config -3. **The Mend Renovate App with a private registry**: Add a plaintext `npmrc` plus an encrypted `npmToken` in config +1. **The Mend Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config +1. **The Mend Renovate App with a private registry**: Add a plaintext `npmrc` plus an encrypted `npmToken` in config These approaches are described in full below. @@ -323,8 +323,8 @@ If instead you use an alternative registry or need an `.npmrc` file for some oth Renovate will then use the following logic: 1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry -2. If an `npmrc` string is present and has a `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token -3. If an `npmrc` string is present but doesn't have a `${NPM_TOKEN}` then the file will have `_authToken=` appended to it +1. If an `npmrc` string is present and has a `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token +1. If an `npmrc` string is present but doesn't have a `${NPM_TOKEN}` then the file will have `_authToken=` appended to it #### Encrypted entire .npmrc file into config diff --git a/docs/usage/getting-started/use-cases.md b/docs/usage/getting-started/use-cases.md index 3b624d9981c4fb..6be6afc52ef193 100644 --- a/docs/usage/getting-started/use-cases.md +++ b/docs/usage/getting-started/use-cases.md @@ -22,8 +22,8 @@ Example package files include: Renovate: 1. Scans your repositories to find package files and their dependencies -2. Checks if any newer versions exist -3. Raises Pull Requests for available updates +1. Checks if any newer versions exist +1. Raises Pull Requests for available updates The Pull Requests patch the package files directly, and include changelogs for the newer versions (if they are available). @@ -43,11 +43,11 @@ This is why Renovate lets the package manager do the lock file update. A simplified example: 1. The repository has a `package.json` and `package-lock.json` with version `1.0.0` of a dependency -2. Renovate sees that version `1.1.0` is available -3. Renovate patches the `package.json` to change the dependency's version from `1.0.0` to `1.1.0` -4. Renovate runs `npm install` to let `npm` update the `package-lock.json` -5. Renovate commits the `package.json` and `package-lock.json` -6. Renovate creates the PR +1. Renovate sees that version `1.1.0` is available +1. Renovate patches the `package.json` to change the dependency's version from `1.0.0` to `1.1.0` +1. Renovate runs `npm install` to let `npm` update the `package-lock.json` +1. Renovate commits the `package.json` and `package-lock.json` +1. Renovate creates the PR ### Custom dependency extraction @@ -136,14 +136,14 @@ We use these Renovate features to automerge an internal dependency: We split our work over two repositories: 1. The [`renovatebot/renovate`](https://github.com/renovatebot/renovate) repository, which has the Renovate code, and most of the Markdown documentation files -2. The [`renovatebot/renovatebot.github.io`](https://github.com/renovatebot/renovatebot.github.io) repository, which has a submodule link to the `renovatebot/renovate` repository +1. The [`renovatebot/renovatebot.github.io`](https://github.com/renovatebot/renovatebot.github.io) repository, which has a submodule link to the `renovatebot/renovate` repository ##### Update process 1. We edit our documentation files on the main Renovate repository `renovatebot/renovate` -2. Renovate sees the change(s) to the `renovatebot/renovate` Git submodule, and creates an update branch on the _documentation build_ repository -3. If the tests pass Renovate automerges the update branch into the `main` branch. -4. A GitHub Actions workflow runs on `main` to build the documentation site and push the build live on our GitHub Pages domain +1. Renovate sees the change(s) to the `renovatebot/renovate` Git submodule, and creates an update branch on the _documentation build_ repository +1. If the tests pass Renovate automerges the update branch into the `main` branch. +1. A GitHub Actions workflow runs on `main` to build the documentation site and push the build live on our GitHub Pages domain ##### Benefits diff --git a/docs/usage/golang.md b/docs/usage/golang.md index 58419ea4145fca..4e20f51b82512c 100644 --- a/docs/usage/golang.md +++ b/docs/usage/golang.md @@ -19,15 +19,15 @@ To learn what these variables do, read the [Go Modules Reference about the`GOPRO ## How It Works 1. Renovate searches in each repository for any `go.mod` files -2. Renovate extracts existing dependencies from `require` statements -3. Renovate resolves the dependency's source repository and checks for SemVer tags if found. Otherwise, commits and `v0.0.0-....` syntax will be used -4. If Renovate finds an update, Renovate will update `go.mod` to the new value -5. Renovate runs `go get` to update the `go.sum` files (you can configure which directory are included using the `goGetDirs` option) -6. If the user has enabled the option `gomodUpdateImportPaths` in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions) array, then Renovate uses [mod](https://github.com/marwan-at-work/mod) to update import paths on major updates, which can update any Go source file -7. If the user has any of the available `gomodTidy` options (e.g. `gomodTidy1.17`) in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions), then Renovate runs `go mod tidy` with the respective options (multiple options are allowed). -8. `go mod vendor` is run if vendored modules are detected -9. A PR will be created with `go.mod`,`go.sum`, and any updated vendored files updated in the one commit -10. If the source repository has either a "changelog" file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR +1. Renovate extracts existing dependencies from `require` statements +1. Renovate resolves the dependency's source repository and checks for SemVer tags if found. Otherwise, commits and `v0.0.0-....` syntax will be used +1. If Renovate finds an update, Renovate will update `go.mod` to the new value +1. Renovate runs `go get` to update the `go.sum` files (you can configure which directory are included using the `goGetDirs` option) +1. If the user has enabled the option `gomodUpdateImportPaths` in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions) array, then Renovate uses [mod](https://github.com/marwan-at-work/mod) to update import paths on major updates, which can update any Go source file +1. If the user has any of the available `gomodTidy` options (e.g. `gomodTidy1.17`) in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions), then Renovate runs `go mod tidy` with the respective options (multiple options are allowed). +1. `go mod vendor` is run if vendored modules are detected +1. A PR will be created with `go.mod`,`go.sum`, and any updated vendored files updated in the one commit +1. If the source repository has either a "changelog" file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR ## Enabling Go Modules Updating diff --git a/docs/usage/java.md b/docs/usage/java.md index bec5049480a017..51b0e7caf8f36b 100644 --- a/docs/usage/java.md +++ b/docs/usage/java.md @@ -151,8 +151,8 @@ To access the Google Artifact Registry, use the JSON service account with `Basic To avoid JSON-in-JSON wrapping, which can cause problems, encode the JSON service account beforehand. 1. Download your JSON service account and store it on your machine. Make sure that the service account has `read` (and only `read`) permissions to your artifacts -2. Base64 encode the service account credentials by running `cat service-account.json | base64` -3. Add the encoded service account to your configuration file +1. Base64 encode the service account credentials by running `cat service-account.json | base64` +1. Add the encoded service account to your configuration file 1. If you want to add it to your self-hosted configuration file: @@ -168,7 +168,7 @@ To avoid JSON-in-JSON wrapping, which can cause problems, encode the JSON servic } ``` - 2. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: + 1. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: ```json { @@ -184,7 +184,7 @@ To avoid JSON-in-JSON wrapping, which can cause problems, encode the JSON servic } ``` -4. Add the following to the `packageRules` in your repository Renovate configuration file: +1. Add the following to the `packageRules` in your repository Renovate configuration file: ```json { diff --git a/docs/usage/key-concepts/changelogs.md b/docs/usage/key-concepts/changelogs.md index 898cb8edd36a47..b21f943936d168 100644 --- a/docs/usage/key-concepts/changelogs.md +++ b/docs/usage/key-concepts/changelogs.md @@ -10,11 +10,11 @@ This page explains how Renovate fetches changelogs, when it can display them, an Renovate detects and populates changelogs by: 1. Identifying a source URL from the datasource response for a package, and saving that internally as `sourceUrl` if found -2. Checking if Renovate's internal [_manual_ metadata](https://github.com/renovatebot/renovate/blob/main/lib/modules/datasource/metadata-manual.ts) for the package includes a source URL -3. Looking up the source URL, if it resides on a supported platform (e.g. GitHub) -4. Checking for both "Releases" metadata in the repository and any commonly known "changelog" file names -5. Filtering the found releases to only include those versions being updated by the current PR -6. Formatting and embedding the results into the PR body +1. Checking if Renovate's internal [_manual_ metadata](https://github.com/renovatebot/renovate/blob/main/lib/modules/datasource/metadata-manual.ts) for the package includes a source URL +1. Looking up the source URL, if it resides on a supported platform (e.g. GitHub) +1. Checking for both "Releases" metadata in the repository and any commonly known "changelog" file names +1. Filtering the found releases to only include those versions being updated by the current PR +1. Formatting and embedding the results into the PR body ## Changelogs for private packages @@ -59,13 +59,13 @@ Follow these steps to find out why Renovate does not find a changelog: - If the registry fundamentally does not provide this data, then the only possibility is for it to be manually populated through PRs to Renovate's source code - If the registry provides source URLs in its response but Renovate does not understand the required fields, then raise a feature request with examples, or better yet a Pull Request to implement support for the source URL parsing/mapping yourself - Sometimes self-hosted versions of registries don't include the full metadata compared to what the public registries do -2. The package was published without source URL information being included. +1. The package was published without source URL information being included. - For example, occasionally `npm` packages don't have `repository` fields included - For example, Docker images regularly do not have the required `LABEL` entry -3. Renovate cannot access the source repository +1. Renovate cannot access the source repository - This is typically a concern for private repositories only - Check if the token Renovate uses has access rights to the repository you need it to access -4. Renovate cannot detect the file names or release name convention within the repository +1. Renovate cannot detect the file names or release name convention within the repository - In this case an enhancement to Renovate might be needed to better detect the releases/formats, assuming the package/repository has a reasonable convention to follow If none of these steps help, search the Renovate issues and discussions to see if this is a known problem. diff --git a/docs/usage/key-concepts/how-renovate-works.md b/docs/usage/key-concepts/how-renovate-works.md index e10dcf657b3d68..3869144fe7c30f 100644 --- a/docs/usage/key-concepts/how-renovate-works.md +++ b/docs/usage/key-concepts/how-renovate-works.md @@ -28,15 +28,15 @@ Renovate's modules are: Renovate uses these modules in order: 1. The platform module interacts with the source control platform and clones the repository -2. The manager module looks for files based on their name and extracts the dependencies (each dependency has a datasource) -3. The datasource module looks up versions of the dependency -4. The versioning module validates and sorts the returned versions +1. The manager module looks for files based on their name and extracts the dependencies (each dependency has a datasource) +1. The datasource module looks up versions of the dependency +1. The versioning module validates and sorts the returned versions For example: 1. The `gitlabci` manager finds a dependency: `python:3.10-alpine` which has the `docker` datasource -2. The `docker` datasource looks for versions and finds: `[python:3.9,python:3.9-alpine,python:3.10,python:3.10-alpine,python:3.11,python:3.11-alpine]` -3. The `docker` versioning returns `python:3.11-alpine`, because that version is compatible with `python:3.10-alpine` +1. The `docker` datasource looks for versions and finds: `[python:3.9,python:3.9-alpine,python:3.10,python:3.10-alpine,python:3.11,python:3.11-alpine]` +1. The `docker` versioning returns `python:3.11-alpine`, because that version is compatible with `python:3.10-alpine` # Workflow diff --git a/docs/usage/key-concepts/pull-requests.md b/docs/usage/key-concepts/pull-requests.md index 1095e9da547fd8..f13629157c8e42 100644 --- a/docs/usage/key-concepts/pull-requests.md +++ b/docs/usage/key-concepts/pull-requests.md @@ -24,14 +24,14 @@ As explained above, Renovate PRs normally have some "uniqueness" in their title When you close a "unique" PR, Renovate assumes you don't want to see that PR again in the future, for example: 1. You ignored `lodash@4.17.21` by closing Renovate's PR -2. Renovate assumes you don't want any updates to `4.17.21` of `lodash` -3. Renovate creates a new PR when the branch + title "uniqueness" exists again, like when `lodash@4.17.22` releases +1. Renovate assumes you don't want any updates to `4.17.21` of `lodash` +1. Renovate creates a new PR when the branch + title "uniqueness" exists again, like when `lodash@4.17.22` releases Renovate behaves similarly for `major` updates, for example: 1. You ignored a `major` update for Lodash (pr title: "Update lodash to v4") by closing Renovate's PR -2. Renovate assumes you don't want any updates to `v4` of `lodash` -3. Renovate won't create any update PRs for `v4` of `lodash`, even if there are newer versions of `v4` +1. Renovate assumes you don't want any updates to `v4` of `lodash` +1. Renovate won't create any update PRs for `v4` of `lodash`, even if there are newer versions of `v4` ## Immortal PRs diff --git a/docs/usage/key-concepts/scheduling.md b/docs/usage/key-concepts/scheduling.md index 2f7f9ebaaf4450..204bff8f1f2d24 100644 --- a/docs/usage/key-concepts/scheduling.md +++ b/docs/usage/key-concepts/scheduling.md @@ -42,9 +42,9 @@ You can customize when Renovate runs, by using the `timezone` and `schedule` con At a high level you need to follow these steps: 1. Tell Renovate what `timezone` you want to use -2. Learn about the scheduling syntax -3. Optional: configure an "in repository schedule" -4. Optional: create packageRules with a custom `schedule` for specific packages +1. Learn about the scheduling syntax +1. Optional: configure an "in repository schedule" +1. Optional: create packageRules with a custom `schedule` for specific packages ### Setting your timezone diff --git a/docs/usage/noise-reduction.md b/docs/usage/noise-reduction.md index b6706268d190bd..3ccb1c09fbb650 100644 --- a/docs/usage/noise-reduction.md +++ b/docs/usage/noise-reduction.md @@ -72,8 +72,8 @@ In that case, you might schedule Renovate to run every Tuesday after midnight to 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) -3. If you have configured Renovate or GitHub that PRs must always be kept up-to-date with the base branch +1. Conflict with lock files (often) +1. If you have configured Renovate or GitHub that PRs must always be kept up-to-date with the base branch Any of the above reasons can lead to a Renovate branch being considered "stale" and then Renovate needs to rebase it off the base branch before you can test and merge again, and Renovate won't do this until it's back in schedule. diff --git a/docs/usage/nuget.md b/docs/usage/nuget.md index 2e6cd063e468af..fdce327a595164 100644 --- a/docs/usage/nuget.md +++ b/docs/usage/nuget.md @@ -25,9 +25,9 @@ To convert your .NET Framework `.csproj`, `.fsproj` or `.vbproj` files into an S ## How it works 1. Renovate searches in each repository for any files with a `.csproj`, `.fsproj`, or `.vbproj` extension -2. Existing dependencies are extracted from `` and `` tags -3. Renovate looks up the latest version on [nuget.org](https://nuget.org) (or an alternative feed if configured) to see if any upgrades are available -4. If the source package includes a GitHub URL as its source, and has either: +1. Existing dependencies are extracted from `` and `` tags +1. Renovate looks up the latest version on [nuget.org](https://nuget.org) (or an alternative feed if configured) to see if any upgrades are available +1. If the source package includes a GitHub URL as its source, and has either: - a "changelog" file, or - uses GitHub releases diff --git a/docs/usage/php.md b/docs/usage/php.md index a75fe7e169c0ee..e74d968b5061f1 100644 --- a/docs/usage/php.md +++ b/docs/usage/php.md @@ -10,10 +10,10 @@ Renovate can upgrade dependencies in PHP's `composer.json` and `composer.lock` f ## How It Works 1. Renovate searches in each repository for any `composer.json` files -2. Existing dependencies are extracted from the relevant sections of the JSON -3. Renovate resolves the dependency on Packagist (or elsewhere if configured), and filter for SemVer versions -4. A PR is created with `composer.json` and `composer.lock` updated in the same commit -5. If the source repository has either a "changelog" file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR +1. Existing dependencies are extracted from the relevant sections of the JSON +1. Renovate resolves the dependency on Packagist (or elsewhere if configured), and filter for SemVer versions +1. A PR is created with `composer.json` and `composer.lock` updated in the same commit +1. If the source repository has either a "changelog" file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR ## Enabling diff --git a/docs/usage/python.md b/docs/usage/python.md index bf70a5c18d619e..5213442cbe6663 100644 --- a/docs/usage/python.md +++ b/docs/usage/python.md @@ -19,9 +19,9 @@ Legacy versions with the `===` prefix are ignored. ## How it works 1. Renovate searches through each repository for package files -2. Existing dependencies are extracted from the package files -3. Renovate searches for the latest version on [PyPI](https://pypi.org/) to decide if there are upgrades -4. If the source package includes a GitHub URL as its source, and has a "changelog" file _or_ uses GitHub releases, a Release Note will be embedded in the generated PR +1. Existing dependencies are extracted from the package files +1. Renovate searches for the latest version on [PyPI](https://pypi.org/) to decide if there are upgrades +1. If the source package includes a GitHub URL as its source, and has a "changelog" file _or_ uses GitHub releases, a Release Note will be embedded in the generated PR ## Alternative file names diff --git a/docs/usage/ruby.md b/docs/usage/ruby.md index 3858315e825fe7..133d8d5dc51613 100644 --- a/docs/usage/ruby.md +++ b/docs/usage/ruby.md @@ -10,9 +10,9 @@ Renovate supports upgrading dependencies in Bundler's Gemfiles and associated `G ## How it works 1. Renovate searches in each repository for any Gemfiles -2. Existing dependencies are extracted from the Gemfiles -3. Renovate resolves the dependency on Rubygems.org (or elsewhere if configured), and checks for newer versions -4. A PR is created which updates the `Gemfile` and `Gemfile.lock` in a single commit +1. Existing dependencies are extracted from the Gemfiles +1. Renovate resolves the dependency on Rubygems.org (or elsewhere if configured), and checks for newer versions +1. A PR is created which updates the `Gemfile` and `Gemfile.lock` in a single commit ## Warnings diff --git a/docs/usage/rust.md b/docs/usage/rust.md index 292e75ea474cec..594abea989aab8 100644 --- a/docs/usage/rust.md +++ b/docs/usage/rust.md @@ -10,10 +10,10 @@ Renovate supports upgrading dependencies in `Cargo.toml` files and associated `C ## How it works 1. Renovate searches in each repository for any `Cargo.toml` files -2. Renovate extracts existing dependencies from `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]` and `[workspace.dependencies]` -3. Renovate looks up Cargo configuration to find index URLs for private registries -4. Renovate resolves the dependency's version using the crates.io API or by cloning the index URL -5. If Renovate finds an update, Renovate will use `cargo update` to update both `Cargo.toml` and `Cargo.lock` +1. Renovate extracts existing dependencies from `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]` and `[workspace.dependencies]` +1. Renovate looks up Cargo configuration to find index URLs for private registries +1. Renovate resolves the dependency's version using the crates.io API or by cloning the index URL +1. If Renovate finds an update, Renovate will use `cargo update` to update both `Cargo.toml` and `Cargo.lock` ## Enabling Rust Modules Updating diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index 31ba81cf19696d..a770d8cddc2a1e 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -623,8 +623,8 @@ This is similar to what happens when you change the `onboardingBranch` config op When this option is `true`, Renovate will do the following during repository initialization: 1. Try to fetch the default config file (e.g. `renovate.json`) -2. Check if the file contains `"enabled": false` -3. If so, skip cloning and skip the repository immediately +1. Check if the file contains `"enabled": false` +1. If so, skip cloning and skip the repository immediately If `onboardingConfigFileName` is set, that file name will be used instead of the default. diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md index 9510cabd82c8d6..b41bcc3d9469d4 100644 --- a/docs/usage/troubleshooting.md +++ b/docs/usage/troubleshooting.md @@ -54,8 +54,8 @@ To troubleshoot further, you usually need to look at `DEBUG` logs. We recommend you follow this process: 1. Try to narrow in on the problem area e.g. by looking for relevant branches or `WARN` or `ERROR` messages -2. Find all relevant `DEBUG` or `INFO` messages from before and after the problem occurred -3. Copy/paste the relevant parts of the logs into your discussion post or bug report +1. Find all relevant `DEBUG` or `INFO` messages from before and after the problem occurred +1. Copy/paste the relevant parts of the logs into your discussion post or bug report If you cannot fix the problem yourself after reading the logs, and reading - or searching through - our documentation, search the [`renovatebot/renovate` discussion](https://github.com/renovatebot/renovate/discussions) forum to see if somebody has asked a similar or related question. diff --git a/docs/usage/updating-rebasing.md b/docs/usage/updating-rebasing.md index 28690148f3a619..9f79dfeda1bf9f 100644 --- a/docs/usage/updating-rebasing.md +++ b/docs/usage/updating-rebasing.md @@ -42,8 +42,8 @@ You can disable this functionality by configuring `"rebaseWhen": "never"` (not r There are multiple cases where Renovate will rebase its branches off the base branch every time they are out of date: 1. If you configure `"rebaseWhen": "behind-base-branch"` -2. If you use the default configuration `"rebaseWhen": "auto"` and the repository has a requirement that branches must be up-to-date before merging (e.g. "Require branches to be up to date before merging" on GitHub, or fast-forward-only settings on Bitbucket Server or GitLab) -3. If you use the default configuration `"rebaseWhen" : "auto"` and configure `"automerge" : true` +1. If you use the default configuration `"rebaseWhen": "auto"` and the repository has a requirement that branches must be up-to-date before merging (e.g. "Require branches to be up to date before merging" on GitHub, or fast-forward-only settings on Bitbucket Server or GitLab) +1. If you use the default configuration `"rebaseWhen" : "auto"` and configure `"automerge" : true` In that case Renovate PRs will be rebased off the repository's base branch whenever they are behind the base branch, even if the PRs are not conflicted. From 7142b85e0aea854ed5a771a2b81c3863a621b941 Mon Sep 17 00:00:00 2001 From: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> Date: Thu, 28 Dec 2023 15:04:51 +0100 Subject: [PATCH 5/9] chore: Apply suggestions from code review (2/2) Signed-off-by: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> --- docs/development/design-decisions.md | 6 +++--- docs/usage/dependency-pinning.md | 2 +- docs/usage/self-hosted-configuration.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/development/design-decisions.md b/docs/development/design-decisions.md index 16672b110feb9d..eda60cae9769bc 100644 --- a/docs/development/design-decisions.md +++ b/docs/development/design-decisions.md @@ -47,9 +47,9 @@ You could limit Renovate to only update the `package.json` in the root of the re ## Separate Branches per dependency -By default, `renovate` will maintain separate branches for each dependency. -So if 20 dependencies need updating, there will be at least 20 branches/PRs. -Although this may seem undesirable, it's even less desirable if all 20 were in the same Pull Request, and it's very difficult to work out which upgrade caused the test failure. +We decided that Renovate should create a separate branch for each dependency, at least by default. +So if 20 dependencies need to be updated, you'll get 20 branches (and 20 PRs) from Renovate. +This may look bad, but it's better than putting all 20 dependencies in a single branch, which makes it hard to work out which upgrade causes a test failure. But you can override the default templates for branch name to get 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. diff --git a/docs/usage/dependency-pinning.md b/docs/usage/dependency-pinning.md index 5233d6363c8545..ec4668c6b2351b 100644 --- a/docs/usage/dependency-pinning.md +++ b/docs/usage/dependency-pinning.md @@ -194,7 +194,7 @@ e.g. are you interested in a Renovate feature where you get a lockfile-only PR a A good argument made by [@LinusU](https://github.com/LinusU) is: -> In many cases, pinning will only protect you against breakage in a small percentage of your packages. If you for example have installed Express and pinned it, you'll only protect yourself against a bad Express release, it will not help with the 30 dependencies that Express has. +> Pinning will only protect you against breakage in a, in many cases, small percentage of your packages. If you for example have installed Express and pinned it, you will only protect yourself against a bad Express release, it will not help with the 30 dependencies that Express has. > > 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. diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index a770d8cddc2a1e..a23bce930e12a6 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -145,8 +145,8 @@ For example: ## autodiscoverTopics -Some platforms allow you to add tags, or topics, to repositories and retrieve repository lists by specifying those -topics. Set this variable to a list of strings, all of which will be topics for the auto-discovered repositories. +Some platforms allow you to add tags, or topics, to repositories and retrieve repository lists by specifying those topics. +Set this variable to a list of strings, all of which will be topics for the auto-discovered repositories. For example: @@ -687,7 +687,7 @@ To create the key pair with GPG use the following commands: ``` ❯ gpg --full-generate-key gpg (GnuPG) 2.2.24; Copyright (C) 2020 Free Software Foundation, Inc. -This is free software: you're free to change and redistribute it. +This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Please select what kind of key you want: From 1688987e337df50781ccfa8ce822723351bf435b Mon Sep 17 00:00:00 2001 From: Koen van Zuijlen <8818390+kvanzuijlen@users.noreply.github.com> Date: Wed, 3 Jan 2024 20:53:38 +0100 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> --- docs/usage/configuration-options.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index 1c01c7f210a33a..7b4b4146ea996c 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -352,7 +352,7 @@ Example config: !!! warning - Leaving PRs/branches as unlimited or as a high number, increases the time it takes for Renovate to process a repository. + Leaving PRs/branches as unlimited or as a high number increases the time it takes for Renovate to process a repository. If you find that Renovate is too slow when rebasing out-of-date branches, decrease the `branchConcurrentLimit`. If you have too many concurrent branches which rebase themselves each run, Renovate can take a lot of time to rebase. @@ -406,7 +406,7 @@ Instead, set the old `branchPrefix` value as `branchPrefixOld` to allow Renovate ## 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 advanced field, and it's recommended you seek a config review before applying it. +This is an advanced field, and we recommend you seek a config review before applying it. ## bumpVersion @@ -3581,7 +3581,7 @@ If you wish to distinguish between patch and minor upgrades, for example if you ## separateMultipleMajor Configure this to `true` if you wish to get one PR for every separate major version upgrade of a dependency. -E.g. if you're on webpack@v1 currently then default behavior is a PR for upgrading to webpack@v3 and not for webpack@v2. +For example, if you're on webpack@v1 currently then default behavior 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. ## statusCheckNames @@ -3658,7 +3658,7 @@ 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 `rebaseWhen=behind-base-branch` and the base 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 scheduled hours then configure this field to `false`. +If you only want updates _within_ the scheduled hours, then set this field to `false`. ## updatePinnedDependencies @@ -3744,7 +3744,7 @@ Renovate also uses custom versioning, like `"docker"` to address the most common Otherwise, Renovate does its best to sort and compare. By exposing `versioning` to config, you can override the default versioning for a package manager if needed. -We do not recommend overriding the default versioning, 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. +We recommend you stick with the default versioning, 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. Renovate supports 4-part versions (1.2.3.4) in full for the NuGet package manager. Other managers can use the `"loose"` versioning fallback: the first 3 parts are used as the version, all trailing parts are used for alphanumeric sorting. From 6b8a513390f54512a8ca3c3f7eb1806c82398de9 Mon Sep 17 00:00:00 2001 From: kvanzuijlen <8818390+kvanzuijlen@users.noreply.github.com> Date: Thu, 11 Jan 2024 13:02:26 +0100 Subject: [PATCH 7/9] chore(docs): Got rid of most contractions --- docs/development/adding-a-package-manager.md | 12 +- docs/development/best-practices.md | 12 +- docs/development/configuration.md | 2 +- .../creating-editing-renovate-presets.md | 4 +- docs/development/design-decisions.md | 10 +- docs/development/help-us-help-you.md | 38 ++-- docs/development/issue-labeling.md | 6 +- docs/development/local-development.md | 34 ++-- docs/development/minimal-reproductions.md | 20 +- .../new-package-manager-template.md | 4 +- docs/development/readme.md | 2 +- docs/development/remote-development.md | 12 +- docs/development/triage-guide.md | 22 +- docs/development/zod.md | 6 +- docs/usage/bot-comparison.md | 10 +- docs/usage/config-presets.md | 24 +-- docs/usage/config-validation.md | 6 +- docs/usage/configuration-options.md | 192 +++++++++--------- docs/usage/configuration-templates.md | 16 +- docs/usage/dependency-pinning.md | 68 +++---- docs/usage/docker.md | 20 +- docs/usage/examples/self-hosting.md | 14 +- docs/usage/faq.md | 24 +-- .../getting-started/installing-onboarding.md | 26 +-- .../usage/getting-started/private-packages.md | 28 +-- docs/usage/getting-started/running.md | 30 +-- docs/usage/getting-started/use-cases.md | 16 +- docs/usage/gitlab-bot-security.md | 12 +- docs/usage/golang.md | 4 +- docs/usage/java.md | 4 +- docs/usage/key-concepts/automerge.md | 32 +-- docs/usage/key-concepts/changelogs.md | 10 +- docs/usage/key-concepts/dashboard.md | 6 +- docs/usage/key-concepts/presets.md | 2 +- docs/usage/key-concepts/pull-requests.md | 14 +- docs/usage/key-concepts/scheduling.md | 2 +- docs/usage/known-limitations.md | 6 +- docs/usage/merge-confidence.md | 14 +- docs/usage/modules/datasource/index.md | 2 +- docs/usage/modules/manager/index.md | 10 +- docs/usage/modules/versioning.md | 8 +- docs/usage/node.md | 2 +- docs/usage/noise-reduction.md | 22 +- docs/usage/nuget.md | 4 +- docs/usage/php.md | 4 +- docs/usage/python.md | 2 +- docs/usage/reading-list.md | 8 +- docs/usage/ruby.md | 4 +- docs/usage/rust.md | 2 +- docs/usage/security-and-permissions.md | 2 +- docs/usage/self-hosted-configuration.md | 44 ++-- docs/usage/self-hosted-experimental.md | 4 +- docs/usage/semantic-commits.md | 2 +- docs/usage/templates.md | 2 +- docs/usage/troubleshooting.md | 10 +- docs/usage/updating-rebasing.md | 4 +- docs/usage/upgrade-best-practices.md | 48 ++--- .../maintaining-aur-packages-with-renovate.md | 2 +- 58 files changed, 475 insertions(+), 475 deletions(-) diff --git a/docs/development/adding-a-package-manager.md b/docs/development/adding-a-package-manager.md index 5aa2ca9aae3bcc..715bb8b517e810 100644 --- a/docs/development/adding-a-package-manager.md +++ b/docs/development/adding-a-package-manager.md @@ -38,7 +38,7 @@ For example: ### `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. +It takes as arguments the content of the file and optionally the full file pathname and config. The function returns an array of detected or extracted dependencies, including the: - dependency name @@ -46,12 +46,12 @@ The function returns an array of detected or extracted dependencies, including t - currentValue - versioning used (like SemVer, PEP 440) -The `extractPackageFile` function doesn't need to fully _understand_ the file or syntax that it gets. +The `extractPackageFile` function does not need to fully _understand_ the file or syntax that it gets. It needs to understand enough to extract a correct list of dependencies. -In general, we extract _all_ dependencies from each dependency file, even if they have values we don't support. +In general, we extract _all_ dependencies from each dependency file, even if they have values we do not support. -If the function reads parts of a dependency file that it can't parse, it should give a `skipReason` message to the `extractPackageFile` function. +If the function reads parts of a dependency file that it can not parse, it should give a `skipReason` message to the `extractPackageFile` function. Make sure the `skipReason` message is helpful to someone reading the logs. If `extractPackageFile` is passed a file which is a "false match", so not a package file, or a file with no dependencies then it can return `null`. @@ -60,7 +60,7 @@ Downstream this results in the file being ignored and removed from the list of p ### `extractAllPackageFiles(packageFiles)` (async, optional) Normally a package manager parses or extracts all package files in _parallel_, and can thus use the `extractPackageFile` function. -If the package manager you're adding works in _serial_, use this function instead. +If the package manager you are adding works in _serial_, use this function instead. For example the npm and Yarn package manager must process the `package.json` and `package-lock` or `yarn.lock` files together. This allows features like Workspaces to work. @@ -100,7 +100,7 @@ To _directly_ update dependencies in lock files: use `updateLockedDependency` in Use `updateDependency` if _both_ conditions apply: -- the manager can't be updated to use the standard replacing mechanism +- the manager can not be updated to use the standard replacing mechanism - a custom replacement has to be provided ### `updateLockedDependency` (optional) diff --git a/docs/development/best-practices.md b/docs/development/best-practices.md index 5f23796b3b48f5..092fcbbec247d8 100644 --- a/docs/development/best-practices.md +++ b/docs/development/best-practices.md @@ -1,12 +1,12 @@ # Best practices This document explains our best practices. -Follow these best practices when you're working on our code. +Follow these best practices when you are working on our code. ## Git branch names Branch names should start with a [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) scope like `feat/` or `fix/`. -If you're closing an issue with your PR then put the issue number after the scope. +If you are closing an issue with your PR then put the issue number after the scope. Finally, describe the changes in the branch in a few words. Some good branch names: @@ -18,7 +18,7 @@ Some good branch names: Avoid branch names like `patch-1`. -If you don't know the correct Conventional Commit scope: give your branch a descriptive name like `issue-1-feature-foo`. +If you do not know the correct Conventional Commit scope: give your branch a descriptive name like `issue-1-feature-foo`. If you forgot to pick a good branch name when you started work, then rename the branch before creating the pull request. Read the [GitHub Docs, renaming a branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch) to learn how to rename your branch on GitHub. @@ -73,7 +73,7 @@ Source: [Google TypeScript Style Guide, function declarations](https://google.gi ### Write understandable code Write code that is easier to read, review and maintain. -Avoid "clever" code that's hard to understand. +Avoid "clever" code that is hard to understand. Prefer verbose code which is easier for others to read and maintain than concise code which may be hard or slower for others to understand. For example, Array `reduce()` functions are often hard to understand first time, and can be replaced with simpler `for` loops. @@ -162,8 +162,8 @@ Also, inline the metadata if the metadata object is complex. `WARN`, `ERROR` and `FATAL` messages are often used in metrics or error catching services. These log messages should have a consistent `msg` component, so they can be automatically grouped or associated. -Metadata that's separate from its message is hard for humans to read. -Try to combine the metadata into the message, unless it's too complex to do so. +Metadata that is separate from its message is hard for humans to read. +Try to combine the metadata into the message, unless it is too complex to do so. Good: diff --git a/docs/development/configuration.md b/docs/development/configuration.md index a9cc9578603000..a238d412964bea 100644 --- a/docs/development/configuration.md +++ b/docs/development/configuration.md @@ -24,7 +24,7 @@ If you need an alternate location or name, set it in the environment variable `R For example `RENOVATE_CONFIG_FILE=myconfig.js` or `RENOVATE_CONFIG_FILE=myconfig.json` and not `RENOVATE_CONFIG_FILE=myconfig`. If none is provided, or the file type is invalid, Renovate will fail. -If you're in an ESM repo (`"type": "module"` in `package.json`) then you must use a `.cjs` extension and set `RENOVATE_CONFIG_FILE`. +If you are in an ESM repo (`"type": "module"` in `package.json`) then you must use a `.cjs` extension and set `RENOVATE_CONFIG_FILE`. For example `RENOVATE_CONFIG_FILE=myconfig.cjs`. Using a configuration file gives you very granular configuration options. diff --git a/docs/development/creating-editing-renovate-presets.md b/docs/development/creating-editing-renovate-presets.md index 1d4e59ad8f87bf..6a416ed6374052 100644 --- a/docs/development/creating-editing-renovate-presets.md +++ b/docs/development/creating-editing-renovate-presets.md @@ -22,12 +22,12 @@ We have multiple kinds of `group:` presets, with different rules. ##### Rules for `group:recommended` presets -1. The `group:recommended` preset is for related dependencies which aren't from a monorepo but which usually need to be updated together as separate PRs may each break +1. The `group:recommended` preset is for related dependencies which are not from a monorepo but which usually need to be updated together as separate PRs may each break ##### Rules for `group:*` presets 1. Finally, any other `group:*` presets can be added if they are beneficial to a wide number of users -1. They don't need to be added to `group:recommended`, meaning that users will "opt in" to them one by one and not get them automatically from `config:recommended`, which includes `group:monorepo` and `group:recommended` +1. They do not need to be added to `group:recommended`, meaning that users will "opt in" to them one by one and not get them automatically from `config:recommended`, which includes `group:monorepo` and `group:recommended` #### Replacement presets diff --git a/docs/development/design-decisions.md b/docs/development/design-decisions.md index eda60cae9769bc..2c07e0555081b4 100644 --- a/docs/development/design-decisions.md +++ b/docs/development/design-decisions.md @@ -48,7 +48,7 @@ You could limit Renovate to only update the `package.json` in the root of the re ## Separate Branches per dependency We decided that Renovate should create a separate branch for each dependency, at least by default. -So if 20 dependencies need to be updated, you'll get 20 branches (and 20 PRs) from Renovate. +So if 20 dependencies need to be updated, you will get 20 branches (and 20 PRs) from Renovate. This may look bad, but it's better than putting all 20 dependencies in a single branch, which makes it hard to work out which upgrade causes a test failure. But you can override the default templates for branch name to get a single branch for all dependencies. @@ -61,7 +61,7 @@ For example, if the current example is 1.6.0 and upgrades to 1.7.0 and 2.0.0 exi Our reasons for separating minor and major PRs: -- It's often the case that projects can't upgrade major dependency versions immediately +- It's often the case that projects can not upgrade major dependency versions immediately - It's also often the case that previous major versions continue receiving Minor or Patch updates - Projects should get Minor and Patch updates for their current Major release even if a new Major release exists @@ -73,7 +73,7 @@ Branches have names like `renovate/webpack-1.x` instead of `renovate/webpack-1.2 We do this because: -- Branches often get updates (e.g. new patches) before they're merged +- Branches often get updates (e.g. new patches) before they are merged - Naming the branch like `1.x` means its name still makes sense if a `1.2.1` release happens Note: You can configure the branch names by using the string template `branchName` and/or its sub-templates `branchPrefix` and `branchTopic`. @@ -86,11 +86,11 @@ This allows users to close unwelcome upgrade PRs and not worry about them being ## Rebasing unmergeable Pull Requests With the default behavior of one branch per dependency, it's often the case that a PR gets merge conflicts after an adjacent dependency update is merged. -On most platforms you can use a web interface to resolve merge conflicts, but you're still resolving the conflicts manually, which is annoying. +On most platforms you can use a web interface to resolve merge conflicts, but you are still resolving the conflicts manually, which is annoying. `renovate` will rebase any unmergeable branches and add the latest necessary commit on top of the most recent `main` 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 has not been modified by anyone else. ## Suppressing string templates from CLI diff --git a/docs/development/help-us-help-you.md b/docs/development/help-us-help-you.md index 6b3e1df408df43..d0bee9219062a3 100644 --- a/docs/development/help-us-help-you.md +++ b/docs/development/help-us-help-you.md @@ -6,7 +6,7 @@ Please follow these points whenever interacting in this repo. ## Be positive and polite This project is open source, and has the work of a lot of contributors who are proud of it. -Please avoid unnecessary criticism, especially if you're new to the project or have not contributed anything. +Please avoid unnecessary criticism, especially if you are new to the project or have not contributed anything. You are welcome to make it better, and do not need to criticize the works of others first. ## Be considerate of the time of people helping you @@ -17,30 +17,30 @@ This also means that features or bug fixes that you really want can take a long ## Be respectful to competitors -Even if you're intending to express a compliment to Renovate from a good heart, try not to phrase it in a way which would be insulting to the developers of alternative tools like Dependabot. -There are a lot of good bots out there, and while we're happy if you like Renovate, we are friends with the creators and developers of other bots and want to keep things friendly. +Even if you are intending to express a compliment to Renovate from a good heart, try not to phrase it in a way which would be insulting to the developers of alternative tools like Dependabot. +There are a lot of good bots out there, and while we are happy if you like Renovate, we are friends with the creators and developers of other bots and want to keep things friendly. -Objective, respectful comparisons or questions are always welcome too - including if you find Renovate missing something you'd like to see. +Objective, respectful comparisons or questions are always welcome too - including if you find Renovate missing something you would like to see. ## Provide adequate descriptions -Renovate maintainers and contributors spend many hours helping users, most of the time with problems which are the user's own misconfiguration or misunderstanding. -When you ask for help or are receiving it, please put effort into adequately describing your problem, what you've tried, and what you're trying to do. +Renovate maintainers and contributors spend many hours helping users, most of the time with problems which are the own misconfiguration or misunderstanding from the user. +When you ask for help or are receiving it, please put effort into adequately describing your problem, what you have tried, and what you are trying to do. -If you describe a problem with too few details, and we ask you follow-up questions, and you continue to give short and incomplete descriptions, you're likely to not get any further questions or help. +If you describe a problem with too few details, and we ask you follow-up questions, and you continue to give short and incomplete descriptions, you are likely to not get any further questions or help. You may get referred to this document though, to explain why! -In other words, if someone's taking the time to help you, "don't be lazy". +In other words, if someone is taking the time to help you, "do not be lazy". ## Avoid complaining about docs after getting help -If someone's helped you get some functionality working, or successfully troubleshoot a problem, please try to do this: +If someone has helped you get some functionality working, or successfully troubleshoot a problem, please try to do this: - Let us know which advice fixed your problem, if it's unclear -- If you're feeling polite, thank the person who helped you -- If you're feeling helpful, submit a Pull Request to improve the relevant documentation +- If you are feeling polite, thank the person who helped you +- If you are feeling helpful, submit a Pull Request to improve the relevant documentation -Please don't ruin a successful result with a criticism or complaint about the quality of the documentation. +Please do not ruin a successful result with a criticism or complaint about the quality of the documentation. If you feel frustrated because better documentation would have prevented you from making the mistake in the first place then improve it with a PR for those who come after you! ## Avoid spamming issues @@ -52,7 +52,7 @@ Instead, use the "Subscribe" button to follow issues. ## Reproduce repositories on github.com -If you've been asked to provide a reproduction repository, please create it on github.com unless the reproduction itself is specific to another platform like GitLab. +If you have been asked to provide a reproduction repository, please create it on github.com unless the reproduction itself is specific to another platform like GitLab. The Renovate maintainers can test and debug the quickest when using GitHub, and we also have a dedicated organization called [renovate-reproductions](https://github.com/renovate-reproductions/) where we fork reproductions into so that we have a copy in case the original creator removes theirs. @@ -61,21 +61,21 @@ The Renovate maintainers can test and debug the quickest when using GitHub, and We have documented what a "minimal" reproduction repository means, and request that you stick to it. The more config and the more dependencies in a reproduction, the slower it is to debug and solve the problem. -Unless you're planning to work on the feature or fix yourself, please be respectful of the person's time who would need to do the work instead. +Unless you are planning to work on the feature or fix yourself, please be respectful of the person's time who would need to do the work instead. ## Filter logs before sharing them -If you've been asked to give us the logs in an issue or discussion, please don't copy/paste the entire output and expect someone else to sort through thousands of lines to help you. +If you have been asked to give us the logs in an issue or discussion, please do not copy/paste the entire output and expect someone else to sort through thousands of lines to help you. A full log dump takes a lot of time to scroll through, and it is next to impossible to do so from mobile. Instead, please select the logs relevant to your problem and paste only the relevant logs. -If it turns out there's a need for the full dump, someone can ask you for it later. +If it turns out there is a need for the full dump, someone can ask you for it later. ## Avoid unjustified bug reports -Don't raise a bug report unless it's definitely a bug. -"I don't like this" or "I didn't expect this to happen" is not the same thing as a bug. +Do not raise a bug report unless it's definitely a bug. +"I do not like this" or "I did not expect this to happen" is not the same thing as a bug. Many unjustified bug reports are filed because people they think it will get them more attention. -Instead, you may be wasting maintainer time because we have to reclassify your invalid bug report or convert it to a discussion, and you're much less likely to get the attention you're hoping for. +Instead, you may be wasting maintainer time because we have to reclassify your invalid bug report or convert it to a discussion, and you are much less likely to get the attention you are hoping for. If in doubt, start a discussion instead. diff --git a/docs/development/issue-labeling.md b/docs/development/issue-labeling.md index f3d7ac9d100bfa..63066c309720c9 100644 --- a/docs/development/issue-labeling.md +++ b/docs/development/issue-labeling.md @@ -55,7 +55,7 @@ For example, use `status:requirements` to mean that an issue is not yet ready fo Use these to label the type of issue. For example, use `type:bug` to label a bug type issue, and use `type:feature` for feature requests. -Only use `type:refactor` for code changes, don't use `type:refactor` for documentation type changes. +Only use `type:refactor` for code changes, do not use `type:refactor` for documentation type changes. All issues should have a `type:*` label. Use [this search](https://github.com/renovatebot/renovate/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+-label%3Atype%3Abug+-label%3Atype%3Afeature+-label%3Atype%3Adocs+-label%3Atype%3Arefactor+) to find issues without a `type:*` label. @@ -195,7 +195,7 @@ Add a label `auto:discussion-first` to any PR which needs discussing first. Add a label `auto:format-code` to any Discussion which needs code formatting. -Add a label `auto:logs` to indicate that there's a problem with the logs, and the contributor needs to do one of these things: +Add a label `auto:logs` to indicate that there is a problem with the logs, and the contributor needs to do one of these things: 1. Provide logs (if there are none yet) 1. Provide more logs (in case current logs are insufficient) @@ -207,7 +207,7 @@ Add a label `auto:no-coverage-ignore` if PR authors avoid needed unit tests by i Add a label `auto:no-done-comments` if PR authors unnecessary "Done" comments, or type comments to ask for a review instead of requesting a new review through GitHub's UI. -Add a label `auto:reproduction` if nobody's reproduced it in a public repo yet and such a reproduction is necessary before further work can be done. +Add a label `auto:reproduction` if nobody has reproduced it in a public repo yet and such a reproduction is necessary before further work can be done. Add a label `auto:retry-latest` to any Discussion where the user should retry the latest version of Renovate to see if the problem persists. diff --git a/docs/development/local-development.md b/docs/development/local-development.md index e5561af1eeb31a..0fe428f3d3e4e3 100644 --- a/docs/development/local-development.md +++ b/docs/development/local-development.md @@ -37,12 +37,12 @@ To enter a development shell with the necessary packages, run `nix-shell --packa Follow these steps to set up your development environment on Windows 10. If you already installed a part, skip the corresponding step. -- 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 [Git](https://git-scm.com/downloads). Make sure you have [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/) - In an Administrator PowerShell prompt, run `npm install -global npm` and then `npm --debug install --global windows-build-tools` - Enable corepack: `corepack enable` - You can see what versions you're using like this: + You can see what versions you are using like this: ```powershell PS C:\Windows\system32> git --version @@ -52,7 +52,7 @@ If you already installed a part, skip the corresponding step. #### VS Code Dev Containers -If you're using [VS Code](https://code.visualstudio.com/) you can skip installing [the prerequisites](#prerequisites) and work in a [development container](https://code.visualstudio.com/docs/devcontainers/containers) instead. +If you are using [VS Code](https://code.visualstudio.com/) you can skip installing [the prerequisites](#prerequisites) and work in a [development container](https://code.visualstudio.com/docs/devcontainers/containers) instead. - Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [check its system requirements](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers#system-requirements) - Open the repository folder in VS Code @@ -68,7 +68,7 @@ pnpm build #### Local Docker -If, for some reason, you can't run the relevant versions on your local machine, you can run everything from a Docker image. +If, for some reason, you can not run the relevant versions on your local machine, you can run everything from a Docker image. To build the correct docker image: ``` @@ -100,8 +100,8 @@ To ensure everything is working properly on your end, you must: 1. Verify all tests pass and have 100% test coverage, by running `pnpm test` 1. Verify the installation by running `pnpm start`. You must see this error: `You must configure a GitHub personal access token` -Don't worry about the token error for now. -You'll configure the token properly a little later, so keep reading. +Do not worry about the token error for now. +You will configure the token properly a little later, so keep reading. You only need to do these steps once. @@ -112,12 +112,12 @@ Before you submit a pull request you should: ## Platform Account Setup -Although it's possible to make small source code improvements without testing against a real repository, in most cases you should 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 is possible to make small source code improvements without testing against a real repository, in most cases you should run a "real" test on a repository before you submit a feature or fix. +It is possible to do this against GitHub, GitLab or Bitbucket public servers. ### Register new account (optional) -If you're going to be doing a lot of Renovate development then it's recommended that you set up a dedicated test account on GitHub or GitLab, so that you reduce the risk that you accidentally cause problems when testing out Renovate. +If you are going to be doing a lot of Renovate development then it's recommended that you set up a dedicated test account on GitHub or GitLab, so that you reduce the risk that you accidentally cause problems when testing out Renovate. e.g. if your GitHub username is "alex88" then maybe you register "alex88-testing" for use with Renovate. @@ -152,13 +152,13 @@ Refactor PRs should ideally not change or remove tests (adding tests is OK). Run the Jest unit tests with the `pnpm jest` command. You can also run a subset of the Jest tests using file matching, e.g. `pnpm jest composer` or `pnpm jest workers/repository/update/branch`. -If you get a test failure due to a "snapshot" mismatch, and you're sure that you need to update the snapshot, then you can append `-u` to the end. +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. `pnpm jest composer -u` would update the saved snapshots for _all_ tests in `**/composer/**`. ### Coverage The Renovate project maintains 100% test coverage, so any Pull Request will fail if it does not have full coverage for code. -Using `// istanbul ignore` is not ideal, but can be a pragmatic solution if adding more tests wouldn't really prove anything. +Using `// istanbul ignore` is not ideal, but can be a pragmatic solution if adding more tests would not really prove anything. To view the current test coverage locally, open up `coverage/index.html` in your browser. @@ -170,9 +170,9 @@ Also, it can be good to submit your PR as a work in progress (WIP) without tests We use [Prettier](https://github.com/prettier/prettier) to format our code. If your code fails `pnpm test` due to a `prettier` rule then run `pnpm lint-fix` to fix it or most `eslint` errors automatically before running `pnpm test` again. -You usually don't need to fix any Prettier errors by hand. +You usually do not need to fix any Prettier errors by hand. -If you're only working on the documentation files, you can use the `pnpm doc-fix` command to format your work. +If you are only working on the documentation files, you can use the `pnpm doc-fix` command to format your work. ## Keeping your Renovate fork up to date @@ -210,10 +210,10 @@ Also create documentation for the option in the `docs/usage/configuration-option ## Debugging -### Chrome's inspect tool +### Google Chrome DevTools -You can debug Renovate with Chrome's inspect tool. -Here's an example: +You can debug Renovate with Google Chrome DevTools. +Here is an example: 1. Open `chrome://inspect` in Chrome, then select "Open dedicated DevTools for Node" 1. Add a `debugger;` statement somewhere in the source code where you want to start debugging @@ -223,7 +223,7 @@ Here's an example: ### VS Code You can also debug Renovate with VS Code. -Here's an example: +Here is an example: 1. In the configuration file, e.g. `config.js` in the root directory of the project, add `token` with your Personal Access Token 1. In the same configuration file, add `repositories` with the repository you want to test against. The file `config.js` would look something like this: diff --git a/docs/development/minimal-reproductions.md b/docs/development/minimal-reproductions.md index 4d4232b4d87af5..ee17d2316650d4 100644 --- a/docs/development/minimal-reproductions.md +++ b/docs/development/minimal-reproductions.md @@ -2,7 +2,7 @@ We may ask you to create a "minimal reproduction" repository to help us fix bugs or work on a feature. -This document explains why we need a minimal reproduction, why we won't use your production repository to debug, and how to create a good minimal reproduction. +This document explains why we need a minimal reproduction, why we will not use your production repository to debug, and how to create a good minimal reproduction. ## Help yourself by creating a minimal reproduction @@ -16,13 +16,13 @@ It's fastest if you - as the bug reporter or feature requester - create the repr ## How the Renovate developers use your minimal reproduction -The first benefit of a public reproduction is to prove that the problem is not caused by your environment or by a setting you left out of your description, thinking it wasn't relevant. -If there were any doubts about whether you'd found a genuine problem before, they are usually removed once a reproduction is made. +The first benefit of a public reproduction is to prove that the problem is not caused by your environment or by a setting you left out of your description, thinking it was not relevant. +If there were any doubts about whether you had found a genuine problem before, they are usually removed once a reproduction is made. Next, when a reproduction has minimal config, it can often let us narrow down or even identify the root cause, suggest workarounds, etc. This means we can often help you from code inspection alone. -Finally, by making the code/dependencies minimal, it usually makes the problem feasible to step through using a debugging if code inspection wasn't sufficient. +Finally, by making the code/dependencies minimal, it usually makes the problem feasible to step through using a debugging if code inspection was not sufficient. Production repositories or non-minimal reproductions are often very difficult to debug because break points get triggered dozens or hundreds or times. ## What is a minimal reproduction? @@ -33,7 +33,7 @@ A minimal reproduction helps the developers see where the bug or missing feature ## Where to host the minimal reproduction If you can, use GitHub to host your reproduction. -If the reproduction needs to be on GitLab or Bitbucket, that's also okay. +If the reproduction needs to be on GitLab or Bitbucket, that is also okay. ## Creating a minimal reproduction @@ -52,7 +52,7 @@ General steps: 1. Set the repository visibility to `public` 1. Give us the link to the repository -### Why we won't use your production repository to debug +### Why we do not use your production repository to debug You may think: @@ -74,10 +74,10 @@ Reducing the config to a minimum helps us find out exactly which config elements ### "It's too much work to create a minimal reproduction" -We'd love to get down to zero reported bugs or feature requests remaining, but we have a lot to do and must set our priorities. +We would love to get down to zero reported bugs or feature requests remaining, but we have a lot to do and must set our priorities. This means we prefer working on issues with a minimal reproduction, as they allow us to spend our time efficiently. -If you don't create a minimal reproduction, we won't prioritize working on your issue. +If you do not create a minimal reproduction, we will not prioritize working on your issue. Issues without a reproduction will probably stay open until you, or somebody else, creates a minimal reproduction. After a while, issues without a reproduction may be closed unfixed. @@ -85,7 +85,7 @@ After a while, issues without a reproduction may be closed unfixed. ### "I already described what you need in the issue" Thank you for describing your issue in detail. -But we still need a minimal reproduction in a repository, and we'd like you to be the one to make sure it matches both your description and expected behavior. +But we still need a minimal reproduction in a repository, and we would like you to be the one to make sure it matches both your description and expected behavior. ### Forcing Renovate to create a lot of pending updates @@ -105,4 +105,4 @@ Set a high `minimumReleaseAge` for that dependency, for example: } ``` -You'll get a lot of pending updates, which you can see on the Dependency Dashboard. +You will get a lot of pending updates, which you can see on the Dependency Dashboard. diff --git a/docs/development/new-package-manager-template.md b/docs/development/new-package-manager-template.md index 919f0471ded3dd..2bb1f202b966ad 100644 --- a/docs/development/new-package-manager-template.md +++ b/docs/development/new-package-manager-template.md @@ -2,11 +2,11 @@ Did you read our documentation on adding a package manager? -- [ ] I've read the [adding a package manager](adding-a-package-manager.md) documentation. +- [ ] I have read the [adding a package manager](adding-a-package-manager.md) documentation. ## Basics -### What's the name of the package manager? +### What is the name of the package manager? ### What language(s) does this package manager support? diff --git a/docs/development/readme.md b/docs/development/readme.md index 40f28c8d2fb735..4d1a8216c983ac 100644 --- a/docs/development/readme.md +++ b/docs/development/readme.md @@ -1,7 +1,7 @@ # Renovate Developer Docs > [!NOTE] -> If you're an end-user of Renovate, please read the [Renovate documentation](https://docs.renovatebot.com). +> If you are an end-user of Renovate, please read the [Renovate documentation](https://docs.renovatebot.com). The `docs/development` directory is for developers and contributors. The Markdown files explain how to work on Renovate's code. diff --git a/docs/development/remote-development.md b/docs/development/remote-development.md index 956a3ca77e59d3..3415ed2aae87c0 100644 --- a/docs/development/remote-development.md +++ b/docs/development/remote-development.md @@ -8,18 +8,18 @@ For example, if you think anything is unclear, or you think something needs to b Read the [local development docs](./local-development.md) first. -## What's remote development? +## What is remote development? When you work locally, you install the tooling and code editor on your computer. You are responsible for setting up the environment correctly. -With remote development you use a container that's hosted somewhere else. -You'll use the same code editor and have the same config as all other developers. +With remote development you use a container that is hosted somewhere else. +You will use the same code editor and have the same config as all other developers. ### Benefits - You only need a browser and internet -- You don't need to install development dependencies on your computer +- You do not need to install development dependencies on your computer - Start work in a fresh environment every time - Reproducible development environment - Similar config for all developers @@ -28,8 +28,8 @@ You'll use the same code editor and have the same config as all other developers ### Drawbacks - Waiting for the remote container to start -- If your internet is down you can't work -- If GitHub Codespaces is down you can't work +- If your internet is down you can not work +- If GitHub Codespaces is down you can not work ## GitHub Codespaces diff --git a/docs/development/triage-guide.md b/docs/development/triage-guide.md index e88e19e3deb4e0..b9b5aef123de5c 100644 --- a/docs/development/triage-guide.md +++ b/docs/development/triage-guide.md @@ -40,7 +40,7 @@ In short: users create discussions, and when it's clear what we need to do, the ## What a triagist is allowed to do -If you've been given triage rights, you're allowed to do the following things: +If you have been given triage rights, you are allowed to do the following things: - Apply labels to issues/discussions - Close, reopen, and assign all issues and pull requests @@ -49,13 +49,13 @@ If you've been given triage rights, you're allowed to do the following things: - Lock and unlock discussions - Individually convert issues to discussions (do _not_ bulk convert issues) -**Note:** We don't use milestones or project boards. +**Note:** We do not use milestones or project boards. ## Guidelines for triage workflow The following are guidelines as we cannot cover all situations. -Use common sense, do your best, and you'll do all right. -Don't be afraid to ask for help. +Use common sense, do your best, and you will do all right. +Do not be afraid to ask for help. ### Apply labels to issues @@ -75,7 +75,7 @@ For really old issues, it's a good idea to ask the maintainers to decide if they ### Closing pull requests -You won't need to close PRs very often, but you can certainly do it in case of spam or malicious content in the PR diff. +You do not need to close PRs very often, but you can certainly do it in case of spam or malicious content in the PR diff. ### Reopen issues @@ -87,7 +87,7 @@ Otherwise, ask the user to open a new issue if it seems like it is different. ### Assign issues -You can assign an issue to yourself, or to somebody else, so that others know who's going to work on the issue. +You can assign an issue to yourself, or to somebody else, so that others know who is going to work on the issue. GitHub allows issues to be assigned to: - any project collaborator, or @@ -97,7 +97,7 @@ You can assign whoever makes sense. ### Mark duplicate issues and pull requests -If you see an issue/discussion that's an obvious duplicate: +If you see an issue/discussion that is an obvious duplicate: 1. Attach a `duplicate` label 1. Use the "Duplicate of" functionality [GitHub docs, about duplicate issues and pull requests](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-duplicate-issues-and-pull-requests) @@ -119,8 +119,8 @@ Ideally warn the user with an `auto:bad-vibes` label first, and then use the `au One of the most important non-code contributions people can do is help features and fixes go from `status:requirements` to an actionable issue. We use the label `status:requirements` to mean "more information or research is needed before someone could start coding this". -It can sometimes be an oversight of the maintainers, but more often it's because there are requirements or edge cases to consider and the user hasn't got an opinion or time to think about them and contribute enough. -Sometimes it can be because there's a need for some research and "design" decisions to be made, which may require maintainers to do, but it's not high enough priority to justify the time yet. +It can sometimes be an oversight of the maintainers, but more often it's because there are requirements or edge cases to consider and the user does not have an opinion or time to think about them and contribute enough. +Sometimes it can be because there is a need for some research and "design" decisions to be made, which may require maintainers to do, but it's not high enough priority to justify the time yet. -In a way `status:requirements` means "someone's going to need to put more thought into this before it can move forward to development". -It can also mean "don't start this now because you might do something which can't be accepted into the code base". +In a way `status:requirements` means "someone is going to need to put more thought into this before it can move forward to development". +It can also mean "do not start this now because you might do something which can not be accepted into the code base". diff --git a/docs/development/zod.md b/docs/development/zod.md index 70890b233f1d4a..2362c04f8842a3 100644 --- a/docs/development/zod.md +++ b/docs/development/zod.md @@ -22,7 +22,7 @@ We decided that Renovate should use [Zod](https://github.com/colinhacks/zod) for This means that any new manager or datasource should use Zod as well. This document explains _how_ and _why_ you should use Zod features. -When writing schema validation you're aiming for a balance between strictness of explicit contracts between separately developed systems, and the permissiveness of Renovate. +When writing schema validation you are aiming for a balance between strictness of explicit contracts between separately developed systems, and the permissiveness of Renovate. We want Renovate to be only as strict as it _needs_ to be. Renovate should _not_ assume a field is always present. @@ -67,7 +67,7 @@ Avoid names like `ComplexNumberSchema`. ### Inferred types -Create inferred types after schemas if they're needed somewhere in the code. +Create inferred types after schemas if they are needed somewhere in the code. Place such inferred types just after the schema definition using the same name. While IDEs may confuse schema and type name sometimes, it's obvious which is which from the syntactic context. @@ -109,7 +109,7 @@ const volume = width * height * length; ``` The code above refers to the `color` and `weight` fields, which Renovate does _not_ need to do its job. -Here's the **correct** code: +Here is the **correct** code: ```ts const Box = z.object({ diff --git a/docs/usage/bot-comparison.md b/docs/usage/bot-comparison.md index 4abcbdcdd49d40..0e68188184f49b 100644 --- a/docs/usage/bot-comparison.md +++ b/docs/usage/bot-comparison.md @@ -1,7 +1,7 @@ # Bot comparison This page explains the key differences between Renovate and Dependabot, to help you choose a bot. -We're trying to be as objective as possible, so this is not a "versus" or anti-Dependabot page. +We are trying to be as objective as possible, so this is not a "versus" or anti-Dependabot page. If you see anything wrong on this page, please let us know by creating a [Discussion](https://github.com/renovatebot/renovate/discussions), or edit this page with a PR. @@ -27,7 +27,7 @@ If you see anything wrong on this page, please let us know by creating a [Discus This section explains the key differences between the Mend Renovate app and the GitHub-native Dependabot. -Even if you're going to self-host a bot, read the hosted app section first, because many features and concepts are similar. +Even if you are going to self-host a bot, read the hosted app section first, because many features and concepts are similar. Then read the self-hosted section. ### Dependency Dashboard @@ -58,7 +58,7 @@ Renovate works on multiple platforms, including GitHub. Read the [list of Renovate platforms](./modules/platform/index.md) to learn more. The _official_ Dependabot program only works on GitHub. -If you're an advanced user, you may use the [`dependabot-core` repository](https://github.com/dependabot/dependabot-core) as a base to build your own Dependabot, which you can run on other platforms. +If you are an advanced user, you may use the [`dependabot-core` repository](https://github.com/dependabot/dependabot-core) as a base to build your own Dependabot, which you can run on other platforms. ### Supported languages @@ -82,7 +82,7 @@ If you're an advanced user, you may use the [`dependabot-core` repository](https Renovate shows four _Merge Confidence_ badges in its PRs: - **Age**: The age of the package -- **Adoption**: The percentage of this package's users (within Renovate) which are using this release +- **Adoption**: The percentage of users of this package (within Renovate) who are using this release - **Passing**: The percentage of updates which have passing tests for this package - **Confidence**: The confidence level for this update @@ -161,4 +161,4 @@ The Dependabot team has a community-maintained collection of scripts to start se #### `dependabot-gitlab/dependabot` -There's also a community-maintained Dependabot for GitLab: [`dependabot-gitlab/dependabot`](https://gitlab.com/dependabot-gitlab/dependabot). +There is also a community-maintained Dependabot for GitLab: [`dependabot-gitlab/dependabot`](https://gitlab.com/dependabot-gitlab/dependabot). diff --git a/docs/usage/config-presets.md b/docs/usage/config-presets.md index a34c779fc28de6..bbc8360db8d345 100644 --- a/docs/usage/config-presets.md +++ b/docs/usage/config-presets.md @@ -16,8 +16,8 @@ Shareable config presets must use the JSON or JSON5 formats, other formats are n !!! warning - We've deprecated using a `renovate.json` file for presets, as this causes issues if the repository configuration _also_ uses a `renovate.json` file. - If you're using a `renovate.json` file to share your presets, rename it to `default.json`. + We have deprecated using a `renovate.json` file for presets, as this causes issues if the repository configuration _also_ uses a `renovate.json` file. + If you are using a `renovate.json` file to share your presets, rename it to `default.json`. !!! tip @@ -92,7 +92,7 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c !!! tip - You can't combine the path and sub-preset syntaxes. + You ca not combine the path and sub-preset syntaxes. This means that anything in the form `provider>owner/repo//path/to/file:subsubpreset` is not supported. One workaround is to use distinct files instead of sub-presets. @@ -112,7 +112,7 @@ It mostly uses Renovate config defaults but adds a few smart customizations such ## How to Use Preset Configs By default, Renovate App's onboarding PR suggests the `["config:recommended]"` preset. -If you're self-hosting, and want to use the `config:recommended` preset, then you must add `"onboardingConfig": { "extends": ["config:recommended"] }` to your bot's config. +If you are self-hosting, and want to use the `config:recommended` preset, then you must add `"onboardingConfig": { "extends": ["config:recommended"] }` to your bot's config. Read the [Full Config Presets](./presets-config.md) page to learn more about our `config:` presets. @@ -124,8 +124,8 @@ A typical onboarding `renovate.json` looks like this: } ``` -Here's an example of using presets to change Renovate's behavior. -You're happy with the `config:recommended` preset, but want Renovate to create PRs when you're not at the office. +Here is an example of using presets to change Renovate's behavior. +You are happy with the `config:recommended` preset, but want Renovate to create PRs when you are not at the office. You look at our `schedule:` presets, and find the `schedule:nonOfficeHours` preset. You put `schedule:nonOfficeHours` in the `extends` array of your `renovate.json` file, like this: @@ -137,7 +137,7 @@ You put `schedule:nonOfficeHours` in the `extends` array of your `renovate.json` ## Preset Parameters -If you browse the "default" presets, you'll see some that have parameters, e.g.: +If you browse the "default" presets, you will see some that have parameters, e.g.: ```json { @@ -163,14 +163,14 @@ Here is how you would use these in your Renovate config: In short, the number of `{{argx}}` parameters 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're repeating config a lot, you might consider publishing one of these types of parameterised presets yourself. +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, see [Contributing to presets](#contributing-to-presets). ## GitHub-hosted Presets To host your preset config on GitHub: -- Create a new repository. Normally you'd call it `renovate-config` but it can be named anything +- Create a new repository. Normally you would call it `renovate-config` but it can be named anything - Add configuration files to this new repo for any presets you want to share. For the default preset, `default.json` will be checked. For named presets, `.json` will be loaded. For example, loading preset `library` would load `library.json`. No other files are necessary. - In other repos, reference it in an extends array like `github>owner/name`, for example: @@ -189,7 +189,7 @@ For a private GitLab repository Renovate requires at least `Reporter` level acce To host your preset config on GitLab: -- Create a new repository on GitLab. Normally you'd call it `renovate-config` but it can be named anything +- Create a new repository on GitLab. Normally you would call it `renovate-config` but it can be named anything - Add a `default.json` to this new repo containing the preset config. No other files are necessary - In other repos, reference it in an extends array like "gitlab>owner/name", e.g. "gitlab>rarkins/renovate-config" @@ -197,7 +197,7 @@ To host your preset config on GitLab: To host your preset config on Gitea: -- Create a new repository on Gitea. Normally you'd call it `renovate-config` but you can use any name you want +- Create a new repository on Gitea. Normally you would call it `renovate-config` but you can use any name you want - Add a `default.json` to this new repository containing the preset config. No other files are necessary - In other repositories, reference it in an extends array like `"gitea>owner/name"`, e.g. `"gitea>rarkins/renovate-config"` @@ -215,7 +215,7 @@ Please consider contributing it to the [Renovate repository](https://github.com/ Create a [discussion](https://github.com/renovatebot/renovate/discussions) to propose your preset to the Renovate maintainers. The maintainers can also help improve the preset, and let you know where to put it in the code. -If you're proposing a "monorepo" preset addition then it's OK to raise a PR directly as that can be more efficient than a GitHub Discussion. +If you are proposing a "monorepo" preset addition then it's OK to raise a PR directly as that can be more efficient than a GitHub Discussion. ## Group/Organization level presets diff --git a/docs/usage/config-validation.md b/docs/usage/config-validation.md index f6b6f36a362f11..5d7d246eeb338b 100644 --- a/docs/usage/config-validation.md +++ b/docs/usage/config-validation.md @@ -33,7 +33,7 @@ You can pass the `--strict` flag to make it fail if a scanned config needs migra ### Pass file to check as CLI arguments You can pass the file you want to check to the `renovate-config-validator` program with a CLI argument. -This can be handy to check a config file with a non-default name, like when you're using preset repositories. +This can be handy to check a config file with a non-default name, like when you are using preset repositories. For example: ```console @@ -55,7 +55,7 @@ Renovate can validate configuration changes in Pull Requests when you use a spec Follow these steps to validate your configuration: -1. Create a new Git branch that matches the `{{branchPrefix}}reconfigure` pattern. For example, if you're using the default prefix `renovate/`, your branch name must be `renovate/reconfigure`. +1. Create a new Git branch that matches the `{{branchPrefix}}reconfigure` pattern. For example, if you are using the default prefix `renovate/`, your branch name must be `renovate/reconfigure`. 1. Commit your updated Renovate config file to this branch, and push it to your Git hosting platform. The next time Renovate runs on that repo it will: @@ -63,5 +63,5 @@ The next time Renovate runs on that repo it will: 1. Search for a branch that matches the special reconfigure pattern. 1. Check for a config file in the reconfigure branch. Renovate can even find a renamed configuration file (compared to the config file in the default branch). 1. Add a passing or failing status to the branch, depending on the outcome of the config validation run. -1. If there's an _open_ pull request with validation errors from the _reconfigure_ branch then Renovate comments in the PR with details. +1. If there is an _open_ pull request with validation errors from the _reconfigure_ branch then Renovate comments in the PR with details. 1. Validate each commit the next time Renovate runs on the repository, until the PR is merged. diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index 8a3e6c2bb19ea6..486bf1cd6a4186 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -37,7 +37,7 @@ Shareable config presets only work with the JSON format. If you have any questions about the config options, or want to get help/feedback about a config, go to the [discussions tab in the Renovate repository](https://github.com/renovatebot/renovate/discussions) and start a new "config help" discussion. We will do our best to answer your question(s). -A `subtype` in the configuration table specifies what type you're allowed to use within the main element. +A `subtype` in the configuration table specifies what type you are allowed to use within the main element. If a config option has a `parent` defined, it means it's only allowed to configure it within an object with the parent name, such as `packageRules` or `hostRules`. @@ -82,10 +82,10 @@ With the above config: ## additionalBranchPrefix By default, the value for this config option is an empty string. -Normally you don't need to set this config option. +Normally you d not need to set this config option. Here's an example where `additionalBranchPrefix` can help you. -Say you're using a monorepo and want to split pull requests based on the location of the package definition, so that individual teams can manage their own Renovate pull requests. +Say you are using a monorepo and want to split pull requests based on the location of the package definition, so that individual teams can manage their own Renovate pull requests. This can be done with this configuration: ```json @@ -163,7 +163,7 @@ By default, Renovate raises PRs but leaves them to someone or something else to By configuring this setting, you allow Renovate to automerge PRs or even branches. Using automerge reduces 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. +Usually you do not 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 @@ -197,7 +197,7 @@ So for example you could choose to automerge all (passing) `devDependencies` onl !!! warning "Negative reviews on GitHub block Renovate automerge" - Renovate won't automerge on GitHub if a PR has a negative review. + Renovate does not automerge on GitHub if a PR has a negative review. !!! note @@ -213,7 +213,7 @@ You must select at least one status check in the _"Require status checks to pass - `platformAutomerge=true`, Renovate defaults to `true` - You use GitHub's _"Require status checks to pass before merging"_ branch protection rule -If you don't select any status check, and you use platform automerge, then GitHub might automerge PRs with failing tests! +If you do not select any status check, and you use platform automerge, then GitHub might automerge PRs with failing tests! ## automergeComment @@ -240,8 +240,8 @@ To configure this option refer to [`schedule`](#schedule) as the syntax is the s The automerge strategy defaults to `auto`, so Renovate decides how to merge pull requests as best it can. If possible, Renovate follows the merge strategy set on the platform itself for the repository. -If you've set `automerge=true` and `automergeType=pr` for any of your dependencies, then you may choose what automerge strategy Renovate uses by setting the `automergeStrategy` config option. -If you're happy with the default behavior, you don't need to do anything. +If you have set `automerge=true` and `automergeType=pr` for any of your dependencies, then you may choose what automerge strategy Renovate uses by setting the `automergeStrategy` config option. +If you are happy with the default behavior, you do not need to do anything. You may choose from these values: @@ -254,7 +254,7 @@ You may choose from these values: Platforms may only support _some_ of these merge strategies. If the chosen automerge strategy is not supported on your platform then Renovate stops automerging. -In that case you'll have to set a supported automerge strategy. +In that case you will have to set a supported automerge strategy. ## automergeType @@ -277,7 +277,7 @@ If you prefer that Renovate more silently automerge _without_ Pull Requests at a - 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. +If you are not already using `bors-ng` or similar, do not worry about this option. ## azureWorkItemId @@ -325,8 +325,8 @@ You can also use the special `"$default"` string to denote the repository's defa !!! note - Do _not_ use the `baseBranches` config option when you've set a `forkToken`. - You may need a `forkToken` when you're using the Forking Renovate app. + Do _not_ use the `baseBranches` config option when you have set a `forkToken`. + You may need a `forkToken` when you are using the Forking Renovate app. ## bbUseDefaultReviewers @@ -334,7 +334,7 @@ Configuring this to `true` means that Renovate will detect and apply the default ## branchConcurrentLimit -By default, Renovate won't enforce any concurrent branch limits. +By default, Renovate does not enforce any concurrent branch limits. The `config:recommended` preset that many extend from limits the number of concurrent branches to 10, but in many cases a limit as low as 3 or 5 can be most efficient for a repository. If you want the same limit for both concurrent branches and concurrent PRs, then set a value for `prConcurrentLimit` and it will be re-used for branch calculations too. @@ -358,7 +358,7 @@ Example config: If you have too many concurrent branches which rebase themselves each run, Renovate can take a lot of time to rebase. Solutions: -- Decrease the concurrent branch limit (note: this won't go and delete any existing, so won't have an effect until you either merge or close existing ones manually) +- Decrease the concurrent branch limit (note: this does not delete any existing branches, so it does not have an effect until you either merge or close existing ones manually) - Remove automerge and/or automatic rebasing (set `rebaseWhen` to `conflicted`). However, if you have branch protection saying PRs must be up-to-date then it's not ideal to remove automatic rebasing ## branchName @@ -371,7 +371,7 @@ Solutions: 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 open a new "config help" discussion at the [Renovate discussions tab](https://github.com/renovatebot/renovate/discussions) or -- You have a use case we didn't expect, please open a discussion to see if we want to get a feature request from you +- You have a use case we did not expect, please open a discussion to see if we want to get a feature request from you ## branchNameStrict @@ -424,14 +424,14 @@ Currently, this config option only works with these managers: Raise a feature request if you want to use this config option with other package managers. Use `bumpVersion` if you want Renovate to update the `version` field in your package file when it updates the dependencies in that file. -This can be handy when you have automated your package's release, as you you don't need extra steps after the Renovate upgrade, you can just release a new version. +This can be handy when you have automated your package's release, as you you do not need extra steps after the Renovate upgrade, you can just release a new version. Configure this value to `"prerelease"`, `"patch"`, `"minor"` or `"major"` to have Renovate update the version in your edited package file. e.g. if you wish Renovate to always increase the target `package.json` version with a patch update, configure this to `"patch"`. For `npm` only 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. +Make sure that version is a pinned version of course, as otherwise it will not be valid. For `sbt` note that Renovate will update the version string only for packages that have the version string in their project's `built.sbt` file. @@ -439,7 +439,7 @@ For `sbt` note that Renovate will update the version string only for packages th Enabling this option will mean that any detected Git submodules will be cloned at time of repository clone. -Important: private submodules aren't supported by Renovate, unless the underlying `ssh` layer already has the correct permissions. +Important: private submodules are not supported by Renovate, unless the underlying `ssh` layer already has the correct permissions. ## commitBody @@ -523,7 +523,7 @@ We recommend you use `matchManagers` and `commitMessageTopic` in a `packageRules ## composerIgnorePlatformReqs -By default, Renovate will ignore Composer platform requirements as the PHP platform used by Renovate most probably won't match the required PHP environment of your project as configured in your `composer.json` file. +By default, Renovate will ignore Composer platform requirements as the PHP platform used by Renovate most probably does not match the required PHP environment of your project as configured in your `composer.json` file. Composer `2.2` and up will be run with `--ignore-platform-req='ext-*' --ignore-platform-req='lib-*'`, which ignores extension and library platform requirements but not the PHP version itself and should work in most cases. @@ -532,7 +532,7 @@ This can result in updated dependencies that are not compatible with your platfo To customize this behaviour, you can explicitly ignore platform requirements (for example `ext-zip`) by setting them separately in this array. Each item will be added to the Composer command with `--ignore-platform-req`, resulting in it being ignored during its invocation. -Note that this requires your project to use Composer V2, as V1 doesn't support excluding single platform requirements. +Note that this requires your project to use Composer V2, as V1 does not support excluding single platform requirements. The used PHP version will be guessed automatically from your `composer.json` definition, so `php` should not be added as explicit dependency. If an empty array is configured, Renovate uses its default behaviour. @@ -559,7 +559,7 @@ If enabled, all issues created by Renovate are set as confidential, even in a pu If enabled, Renovate raises a pull request when it needs to migrate the Renovate config file. Renovate only performs `configMigration` on `.json` and `.json5` files. -We're adding new features to Renovate bot often. +We are adding new features to Renovate bot often. Often you can keep using your Renovate config and use the new features right away. But sometimes you need to update your Renovate configuration. To help you with this, Renovate will create config migration pull requests, when you enable `configMigration`. @@ -585,13 +585,13 @@ After we changed the [`baseBranches`](#basebranches) feature, the Renovate confi !!! note When you close a config migration PR, Renovate ignores it forever. - This also means that Renovate won't create a config migration PR in the future. + This also means that Renovate will not create a config migration PR in the future. If you closed the PR by accident, find the closed PR and re-name the PR title to get a new PR. ## configWarningReuseIssue Renovate's default behavior is to reuse/reopen a single Config Warning issue in each repository 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. +However, for some people this has the downside that the config warning will not 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 @@ -696,7 +696,7 @@ You must have a named capture group matching (e.g. `(?.*)`) _or_ config - `currentValue` Use named capture group matching _or_ set a corresponding template. -We recommend you use only _one_ of these methods, or you'll get confused. +We recommend you use only _one_ of these methods, or you will get confused. We recommend that you also tell Renovate what `versioning` to use. If the `versioning` field is missing, then Renovate defaults to using `semver` versioning. @@ -1197,7 +1197,7 @@ Example: } ``` -To enable custom managers you'll need to add `custom.` prefix before their names +To enable custom managers you will need to add `custom.` prefix before their names Example: @@ -1215,7 +1215,7 @@ Before you put any secrets in your repository configuration, encrypt the secrets You can encrypt secrets using either our webpage, or the CLI. To encrypt secrets for the Mend Renovate App for github.com using our webpage, go to [app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt) and complete the form. -If you're self-hosting Renovate, you may download and edit the form, to use your own PGP public key. +If you are self-hosting Renovate, you may download and edit the form, to use your own PGP public key. You can also encrypt secrets from the CLI, using the `curl`, `echo`, `jq`, `gpg`, `grep` and `tr` CLI programs. Here is an example: @@ -1249,7 +1249,7 @@ For more information on how to use secrets for private packages, read [Private p ## excludeCommitPaths -Be careful you know what you're doing with this option. +Be careful you know what you are 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: @@ -1328,7 +1328,7 @@ The available options are: - `pr`(default) - fetches changelogs while creating/updating pull-request Avoid setting `fetchChangeLogs=branch`, because this slows down Renovate. -But if you're embedding changelogs in commit information, you may use `fetchChangeLogs=branch`. +But if you are embedding changelogs in commit information, you may use `fetchChangeLogs=branch`. Renovate can fetch changelogs when they are hosted on one of these platforms: @@ -1336,12 +1336,12 @@ Renovate can fetch changelogs when they are hosted on one of these platforms: - GitHub (.com and Enterprise Server) - GitLab (.com and CE/EE) -If you're running on any platform except `github.com`, you need to [configure a Personal Access Token](./getting-started/running.md#githubcom-token-for-changelogs) to allow Renovate to fetch changelogs notes from `github.com`. +If you are running on any platform except `github.com`, you need to [configure a Personal Access Token](./getting-started/running.md#githubcom-token-for-changelogs) to allow Renovate to fetch changelogs notes from `github.com`. !!! note Renovate can only show changelogs from some platforms and some package managers. - We're planning improvements so that Renovate can show more changelogs. + We are planning improvements so that Renovate can show more changelogs. Read [issue 14138 on GitHub](https://github.com/renovatebot/renovate/issues/14138) to get an overview of the planned work. ## fileMatch @@ -1355,12 +1355,12 @@ Here Renovate looks for _any_ `go.mod` file. In this case you can probably keep using that default `fileMatch`. 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 have 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. +For default, Kubernetes manifests can exist in any `*.yaml` file, and we do not want Renovate to parse every single YAML file in every repository just in case some of them have 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. +Finally, there are cases where Renovate's default `fileMatch` is good, but you may be using file patterns that a bot could not possibly guess about. For example, Renovate's default `fileMatch` for `Dockerfile` is `['(^|/|\\.)([Dd]ocker|[Cc]ontainer)file$', '(^|/)([Dd]ocker|[Cc]ontainer)file[^/]*$']`. 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 add the missing file like this: +Because `fileMatch` is mergeable, you do not need to duplicate the defaults and could add the missing file like this: ```json { @@ -1396,10 +1396,10 @@ The main usecase is to follow a pre-release tag of a dependency, say TypeScript' } ``` -If you've set a `followTag` then Renovate skips its normal major/minor/patch upgrade logic and stable/unstable consistency logic, and instead keeps your dependency version synced _strictly_ to the version in the tag. +If you have set a `followTag` then Renovate skips its normal major/minor/patch upgrade logic and stable/unstable consistency logic, and instead keeps your dependency version synced _strictly_ to the version in the tag. Renovate follows tags _strictly_, this can cause problems when a tagged stream is no longer maintained. -For example: you're following the `next` tag, but later the stream you actually want is called `stable` instead. +For example: you are following the `next` tag, but later the stream you actually want is called `stable` instead. If `next` is no longer getting updates, you must switch your `followTag` to `stable` to get updates again. ## forkModeDisallowMaintainerEdits @@ -1421,7 +1421,7 @@ If this option is enabled, reviewers will need to create a new PR if more change ## forkProcessing By default, Renovate skips any forked repositories when in `autodiscover` mode. -It even skips a forked repository that has a Renovate configuration file, because Renovate doesn't know if that file was added by the forked repository. +It even skips a forked repository that has a Renovate configuration file, because Renovate does not know if that file was added by the forked repository. **Process a fork in `autodiscover` mode`** @@ -1432,7 +1432,7 @@ If you want Renovate to run on a forked repository when in `autodiscover` mode t **Process a fork in other modes** -If you're running Renovate in some other mode, for example when giving a list of repositories to Renovate, but want to skip forked repositories: set `"forkProcessing": "disabled"` in your _global_ config. +If you are running Renovate in some other mode, for example when giving a list of repositories to Renovate, but want to skip forked repositories: set `"forkProcessing": "disabled"` in your _global_ config. **When using the Mend Renovate App** @@ -1450,7 +1450,7 @@ If you allow Renovate to run on "Selected" repositories, `forkProcessing` will b **Allowed filenames** Only the `onboardingConfigFileName` (which defaults to `renovate.json`) is supported for `forkProcessing`. -You can't use other filenames because Renovate only checks the default filename when using the Git-hosting platform's API. +You can not use other filenames because Renovate only checks the default filename when using the Git-hosting platform's API. ## gitAuthor @@ -1472,8 +1472,8 @@ Development Bot Specify commit authors ignored by Renovate. By default, Renovate will treat any PR as modified if another Git author has added to the branch. -When a PR is considered modified, Renovate won't perform any further commits such as if it's conflicted or needs a version update. -If you have other bots which commit on top of Renovate PRs, and don't want Renovate to treat these PRs as modified, then add the other Git author(s) to `gitIgnoredAuthors`. +When a PR is considered modified, Renovate will not perform any further commits such as if it's conflicted or needs a version update. +If you have other bots which commit on top of Renovate PRs, and do not want Renovate to treat these PRs as modified, then add the other Git author(s) to `gitIgnoredAuthors`. Example: @@ -1503,7 +1503,7 @@ If you need to modify this path, for example in order to ignore directories, you ## group -The default configuration for groups are essentially internal to Renovate and you normally shouldn't need to modify them. +The default configuration for groups are essentially internal to Renovate and you normally should not need to modify them. But you may _add_ settings to any group by defining your own `group` configuration object. ## groupName @@ -1552,7 +1552,7 @@ As a result of the above, the branchName would be `renovate/dev-dependencies` in !!! note - You shouldn't usually need to configure this unless you really care about your branch names. + Usually, you should not need to configure this unless you really care about your branch names. ## hashedBranchLength @@ -1704,7 +1704,7 @@ You may use the `authType` option to create a custom HTTP `authorization` header For `authType` to work, you must also set your own `token`. Do not set `authType=Bearer`: it's the default setting for Renovate anyway. -Do not set a username or password when you're using `authType`, as `authType` doesn't use usernames or passwords. +Do not set a username or password when you are using `authType`, as `authType` does not use usernames or passwords. An example for npm basic auth with token: @@ -1758,7 +1758,7 @@ Example config: ``` Use an exact host for `matchHost` and not a domain (e.g. `api.github.com` as shown above and not `github.com`). -Do not combine with `hostType` in the same rule, or it won't work. +Do not combine with `hostType` in the same rule, or it will not work. ### maxRequestsPerSecond @@ -1812,7 +1812,7 @@ 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 `matchHost` and only one host type is in use for those, as is usually the case. +You usually do not need to configure it in a host rule if you have already configured `matchHost` 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 `matchHost` rules could achieve the same thing. ### insecureRegistry @@ -1869,7 +1869,7 @@ If the value starts with `http(s)` then it will only match against URLs which st Otherwise, it will be matched by checking if the hostname of the URL matches the `matchHost` directly or ends with it. When checking the end of the hostname, a single dot is prefixed to the value of `matchHost`, if one is not already present, to ensure it can only match against whole domain segments. -The `matchHost` URL must be the same as the `registryUrl` set in `.npmrc`, or you'll get authentication issues when the artifacts are updated when yarn or npm runs. +The `matchHost` URL must be the same as the `registryUrl` set in `.npmrc`, or you will get authentication issues when the artifacts are updated when yarn or npm runs. ```json { @@ -1928,8 +1928,8 @@ Specifies the [Certificate chains](https://en.wikipedia.org/wiki/X.509#Certifica ## 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, only because it's higher than the current version. +By default, Renovate does not update a dependency version to a deprecated release unless the current version was _itself_ deprecated. +The goal of this is to make sure you do not upgrade from a non-deprecated version to a deprecated one, only 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`, which we do not recommend for most situations. @@ -1971,7 +1971,7 @@ For instance if you have a project with an `"examples/"` directory you wish to i ``` Renovate's default ignore is `node_modules` and `bower_components` only. -If you're extending from the popular `config:recommended` preset then it adds ignore patterns for `vendor`, `examples`, `test(s)` and `fixtures` directories too. +If you are extending from the popular `config:recommended` preset then it adds ignore patterns for `vendor`, `examples`, `test(s)` and `fixtures` directories too. ## ignorePlugins @@ -1982,12 +1982,12 @@ Applicable for Composer only for now. This is usually needed if someone needs to migrate bot accounts, including from the Mend Renovate App to the self-hosted variant. If `ignorePrAuthor` is configured to true, it means Renovate will fetch the entire list of repository PRs instead of optimizing to fetch only those PRs which it created itself. -You should only want to enable this if you're changing the bot account (e.g. from `@old-bot` to `@new-bot`) and want `@new-bot` to find and update any existing PRs created by `@old-bot`. +You should only want to enable this if you are changing the bot account (e.g. from `@old-bot` to `@new-bot`) and want `@new-bot` to find and update any existing PRs created by `@old-bot`. It's recommended to revert this setting once that transition period is over and all old PRs are resolved. ## ignorePresets -Use this if you're extending a complex preset but don't want to use every "sub preset" that it includes. +Use this if you are extending a complex preset but do not want to use every "sub preset" that it includes. For example, consider this config: ```json @@ -2021,13 +2021,13 @@ Applicable for npm and Composer only for now. Set this to `true` if running scri Currently, Renovate's default behavior is to only automerge if every status check has succeeded. Setting this option to `true` means that Renovate will ignore _all_ status checks. -You can set this if you don't have any status checks but still want Renovate to automerge PRs. +You can set this if you do not have any status checks but still want Renovate to automerge PRs. Beware: configuring Renovate to automerge without any tests can lead to broken builds on your base branch, please think again before enabling this! ## 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're 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. +By default, Renovate will not 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. @@ -2037,7 +2037,7 @@ Also check out the `followTag` configuration option above if you wish Renovate t If you wish for Renovate to process only select paths in the repository, use `includePaths`. Alternatively, if you need to _exclude_ certain paths in the repository then consider `ignorePaths` instead. -If you're more interested in including only certain package managers (e.g. `npm`), then consider `enabledManagers` instead. +If you are more interested in including only certain package managers (e.g. `npm`), then consider `enabledManagers` instead. ## internalChecksAsSuccess @@ -2045,7 +2045,7 @@ By default, internal Renovate checks such as `renovate/stability-days` are not c This is primarily to prevent automerge when the only check is a passing Renovate check. Internal checks will always be counted/considered if they are in pending or failed states. -If there are multiple passing checks for a branch, including non-Renovate ones, then this setting won't make any difference. +If there are multiple passing checks for a branch, including non-Renovate ones, then this setting will not make any difference. Change this setting to `true` if you want to use internal Renovate checks towards a passing branch result. @@ -2063,7 +2063,7 @@ We recommend that you use the `strict` mode, and enable the `dependencyDashboard ## labels -By default, Renovate won't add any labels to PRs. +By default, Renovate does not add any labels to PRs. If you want Renovate to add labels to PRs it creates 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. @@ -2086,7 +2086,7 @@ With the above config, every PR raised by Renovate will have the label `dependen Renovate only adds labels when it creates the PR, which means: -- If you remove labels which Renovate added, it won't re-apply them +- If you remove labels which Renovate added, it does not re-apply them - If you change your config, the new/changed labels are not applied to any open PRs The `labels` array is non-mergeable, meaning if multiple `packageRules` match then Renovate uses the last value for `labels`. @@ -2154,7 +2154,7 @@ Read [our selective-scheduling help](./noise-reduction.md#selective-scheduling) If the time since the release is less than the set `minimumReleaseAge` a "pending" status check is added to the branch. If enough days have passed then the "pending" status is removed, and a "passing" status check is added. -Some datasources don't have a release timestamp, in which case this feature is not compatible. +Some datasources do not have a release timestamp, in which case this feature is not compatible. Other datasources may have a release timestamp, but Renovate does not support it yet, in which case a feature request needs to be implemented. Maven users: you cannot use `minimumReleaseAge` if a Maven source returns unreliable `last-modified` headers. @@ -2212,7 +2212,7 @@ See [Private npm module support](./getting-started/private-packages.md) for deta This option exists to provide flexibility about whether `npmrc` strings in config should override `.npmrc` files in the repo, or be merged with them. In some situations you need the ability to force override `.npmrc` contents in a repo (`npmrcMerge=false`) while in others you might want to simply supplement the settings already in the `.npmrc` (`npmrcMerge=true`). -A use case for the latter is if you're a Renovate bot admin and wish to provide a default token for `npmjs.org` without removing any other `.npmrc` settings which individual repositories have configured (such as scopes/registries). +A use case for the latter is if you are a Renovate bot admin and wish to provide a default token for `npmjs.org` without removing any other `.npmrc` settings which individual repositories have configured (such as scopes/registries). If `false` (default), it means that defining `config.npmrc` will result in any `.npmrc` file in the repo being overridden and its values ignored. If configured to `true`, it means that any `.npmrc` file in the repo will have `config.npmrc` prepended to it before running `npm`. @@ -2222,7 +2222,7 @@ If configured to `true`, it means that any `.npmrc` file in the repo will have ` Renovate integrates with [OSV](https://osv.dev/), an open-source vulnerability database, to check if extracted dependencies have known vulnerabilities. Set `osvVulnerabilityAlerts` to `true` to get pull requests with vulnerability fixes (once they are available). -You'll only get OSV-based vulnerability alerts for _direct_ dependencies. +You will only get OSV-based vulnerability alerts for _direct_ dependencies. Renovate only queries the OSV database for dependencies that use one of these datasources: - [`crate`](./modules/datasource/crate/index.md) @@ -2801,7 +2801,7 @@ For example to apply a special label to `major` updates: !!! warning Packages that follow SemVer are allowed to make breaking changes in _any_ `0.x` version, even `patch` and `minor`. - Check if you're using any `0.x` package, and see if you need custom `packageRules` for it. + Check if you are using any `0.x` package, and see if you need custom `packageRules` for it. When setting up automerge for dependencies, make sure to stop accidental automerges of `0.x` versions. Read the [automerge non-major updates](./key-concepts/automerge.md#automerge-non-major-updates) docs for a config example that blocks `0.x` updates. @@ -2856,12 +2856,12 @@ Using this field we can specify the exact URL to fetch changelogs from. !!! note - Renovate can fetch changelogs from Bitbucket, Gitea (Forgejo), GitHub and GitLab platforms only, and setting the URL to an unsupported host/platform type won't change that. + Renovate can fetch changelogs from Bitbucket, Gitea (Forgejo), GitHub and GitLab platforms only, and setting the URL to an unsupported host/platform type does not change that. ### replacementName This config option only works with some managers. -We're working to support more managers, subscribe to issue [renovatebot/renovate#14149](https://github.com/renovatebot/renovate/issues/14149) to follow our progress. +We are working to support more managers, subscribe to issue [renovatebot/renovate#14149](https://github.com/renovatebot/renovate/issues/14149) to follow our progress. Managers which do not support replacement: @@ -2929,7 +2929,7 @@ Or, to add a registry prefix to any `docker` images that do not contain an expli ### replacementVersion This config option only works with some managers. -We're working to support more managers, subscribe to issue [renovatebot/renovate#14149](https://github.com/renovatebot/renovate/issues/14149) to follow our progress. +We are working to support more managers, subscribe to issue [renovatebot/renovate#14149](https://github.com/renovatebot/renovate/issues/14149) to follow our progress. For a list of managers which do not support replacement read the `replacementName` config option docs. Use the `replacementVersion` config option to set the version of a replacement package. @@ -2970,11 +2970,11 @@ If enabled Renovate will pin Docker images or GitHub Actions by means of their S !!! note If you use the default `platformAutomerge=true` then you should enable your Git hosting platform's capabilities to enforce test passing before PR merge. - If you don't do this, the platform might merge Renovate PRs even if the repository's tests haven't started, are in still in progress, or possibly even when they have failed. + If you do not do this, the platform might merge Renovate PRs even if the repository's tests have not started, are in still in progress, or possibly even when they have failed. On GitHub this is called "Require status checks before merging", which you can find in the "Branch protection rules" section of the settings for your repository. [GitHub docs, about protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) [GitHub docs, require status checks before merging](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-status-checks-before-merging) - If you're using another platform, search their documentation for a similar feature. + If you are using another platform, search their documentation for a similar feature. If you have enabled `automerge` and set `automergeType=pr` in the Renovate config, then leaving `platformAutomerge` as `true` speeds up merging via the platform's native automerge functionality. @@ -3064,7 +3064,7 @@ A list of glob-style matchers that determine which files will be included in the Dotfiles are included. Optional field which defaults to any non-ignored file in the repo (`**/*` glob pattern). -Specify a custom value for this if you wish to exclude certain files which are modified by your `postUpgradeTasks` and you don't want committed. +Specify a custom value for this if you wish to exclude certain files which are modified by your `postUpgradeTasks` and you do not want committed. ### executionMode @@ -3170,8 +3170,8 @@ This setting tells Renovate _when_ to create PRs: - `status-success`: Renovate only creates PRs if/when the test pass - `approval`: Renovate creates branches for updates immediately, but creates the PR _after_ getting Dependency Dashboard approval -When prCreation is set to `immediate`, you'll get a Pull Request and possible associated notification right away when a new update is available. -You'll have to wait until the checks have been performed, before you can decide if you want to merge the PR. +When prCreation is set to `immediate`, you will get a Pull Request and possible associated notification right away when a new update is available. +You will have to wait until the checks have been performed, before you can decide if you want to merge the PR. When prCreation is set to `not-pending`, Renovate creates the PR only once all tests have passed or failed. When you get the PR notification, you can take action immediately, as you have the full test results. @@ -3185,7 +3185,7 @@ Renovate still creates the _branch_ immediately. !!! note - For all cases of non-immediate PR creation, Renovate doesn't run instantly once tests complete. + For all cases of non-immediate PR creation, Renovate does not run instantly once tests complete. Instead, Renovate create the PR on its _next_ run after the relevant tests have completed, so there will be some delay. @@ -3200,8 +3200,8 @@ Renovate still creates the _branch_ immediately. This config option slows down the _rate_ at which Renovate creates PRs. -Slowing Renovate down can be handy when you're onboarding a repository with a lot of dependencies. -What may happen if you don't set a `prHourlyLimit`: +Slowing Renovate down can be handy when you are onboarding a repository with a lot of dependencies. +What may happen if you do not set a `prHourlyLimit`: 1. Renovate creates an Onboarding PR 1. You merge the onboarding PR to activate Renovate @@ -3269,7 +3269,7 @@ Here's an example of how you would define PR priority so that `devDependencies` ## prTitle -The PR title is important for some of Renovate's matching algorithms (e.g. determining whether to recreate a PR or not) so ideally don't modify it much. +The PR title is important for some of Renovate's matching algorithms (e.g. determining whether to recreate a PR or not) so ideally do not modify it much. ## prTitleStrict @@ -3313,11 +3313,11 @@ Renovate's `"auto"` strategy works like this for npm: 1. Otherwise, if the update is outside the existing range, Renovate replaces the range. So `"^2.0.0"` is replaced by `"^3.0.0"` 1. Finally, if the update is in-range, Renovate will update the lockfile with the new exact version. -By default, Renovate assumes that if you're using ranges then it's because you want them to be wide/open. -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. +Renovate will not 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 will not change anything because `1.2.0` satisfies the range. +If instead you would prefer to be updated to `^1.2.0` in cases like this, then configure `rangeStrategy` to `bump` in your Renovate config. This feature supports caret (`^`) and tilde (`~`) ranges only, like `^1.0.0` and `~1.0.0`. @@ -3343,7 +3343,7 @@ Possible values and meanings: `rebaseWhen=conflicted` is not recommended if you have enabled Renovate automerge, because: - It could result in a broken base branch if two updates are merged one after another without testing the new versions together -- If you have enforced that PRs must be up-to-date before merging (e.g. using branch protection on GitHub), then automerge won't be possible as soon as a PR gets out-of-date but remains non-conflicted +- If you have enforced that PRs must be up-to-date before merging (e.g. using branch protection on GitHub), then automerge will not be possible as soon as a PR gets out-of-date but remains non-conflicted It is also recommended to avoid `rebaseWhen=never` as it can result in conflicted branches with outdated PR descriptions and/or status checks. @@ -3366,7 +3366,7 @@ You can select which behavior you want from Renovate: - `always`: Recreates all closed or blocking PRs - `auto`: The default option. Recreates only immortal PRs (default) -- `never`: No PR is recreated, doesn't matter if it is immortal or not +- `never`: No PR is recreated, does not matter if it is immortal or not We recommend that you stick with the default setting for this option. Only change this setting if you really need to. @@ -3432,8 +3432,8 @@ Must be valid usernames. **Required reviewers on GitHub** -If you're assigning a team to review on GitHub, you must use the prefix `team:` and add the _last part_ of the team name. -Say the full team name on GitHub is `@organization/foo`, then you'd set the config option like this: +If you are assigning a team to review on GitHub, you must use the prefix `team:` and add the _last part_ of the team name. +Say the full team name on GitHub is `@organization/foo`, then you would set the config option like this: ```json { @@ -3499,9 +3499,9 @@ every 3 months on the first day of the month !!! warning - For Cron schedules, you _must_ use the `*` wildcard for the minutes value, as Renovate doesn't support minute granularity. + For Cron schedules, you _must_ use the `*` wildcard for the minutes value, as Renovate does not support minute granularity. -One example might be that you don't want Renovate to run during your typical business hours, so that your build machines don't get clogged up testing `package.json` updates. +One example might be that you do not want Renovate to run during your typical business hours, so that your build machines do not get clogged up testing `package.json` updates. You could then configure a schedule like this at the repository level: ```json @@ -3548,18 +3548,18 @@ Renovate does not support scheduled minutes or "at an exact time" granularity. ## semanticCommitScope -By default, you'll see Angular-style commit prefixes like `"chore(deps):"`. +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'll see Angular-style commit prefixes like `"chore(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're using a semantic prefix for your commits, then you'll want to enable this setting. +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 `enabled`, then the `semanticCommitScope` and `semanticCommitType` fields will be used for each commit message and PR title. @@ -3573,12 +3573,12 @@ If you were to apply the minor update then Renovate would keep updating the 3.x 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 option 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. +For example, let's say in the above example that you decided you would not update to Webpack 3 for a long time and do not 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 _will not_ 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 get 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 the base branch 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. +i.e. if you close a major upgrade PR then it will not come back again, but once you make the major upgrade yourself then Renovate will resume providing you with minor or patch updates. This option also has priority over package groups configured by `packageRule`. So Renovate will propose separate PRs for major and minor updates of packages even if they are grouped. @@ -3586,14 +3586,14 @@ If you want to enforce grouped package updates, you need to set this option to ` ## 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're 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. +By default, Renovate does not 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 configure this option to `true`. ## separateMultipleMajor Configure this to `true` if you wish to get one PR for every separate major version upgrade of a dependency. -For example, if you're on webpack@v1 currently then default behavior is a PR for upgrading to webpack@v3 and not for webpack@v2. +For example, if you are on webpack@v1 currently then default behavior 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. ## statusCheckNames @@ -3658,7 +3658,7 @@ This is considered a feature flag with the aim to remove it and default to this ## updateInternalDeps Renovate defaults to skipping any internal package dependencies within monorepos. -In such case dependency versions won't be updated by Renovate. +In such case dependency versions will not be updated by Renovate. To opt in to letting Renovate update internal package versions normally, set this configuration option to true. @@ -3772,8 +3772,8 @@ Follow these steps: 1. Select "Code security and analysis" in the sidebar 1. Enable the "Dependency graph" 1. Enable "Dependabot alerts" -1. If you're running Renovate in app mode: make sure the app has `read` permissions for "Dependabot alerts". - If you're the account administrator, browse to the app (for example [the Mend Renovate App](https://github.com/apps/renovate)), select "Configure", and then scroll down to the "Permissions" section and make sure that `read` access to "Dependabot alerts" is mentioned +1. If you are running Renovate in app mode: make sure the app has `read` permissions for "Dependabot alerts". + If you are the account administrator, browse to the app (for example [the Mend Renovate App](https://github.com/apps/renovate)), select "Configure", and then scroll down to the "Permissions" section and make sure that `read` access to "Dependabot alerts" is mentioned Once the above conditions are met, and you got one or more vulnerability alerts from GitHub for this repository, then Renovate tries to raise fix PRs. diff --git a/docs/usage/configuration-templates.md b/docs/usage/configuration-templates.md index 60af4e7b809ccc..822340f3179440 100644 --- a/docs/usage/configuration-templates.md +++ b/docs/usage/configuration-templates.md @@ -14,16 +14,16 @@ If you change the `branchPrefix` while you have ignored some upgrades (closed PR `branchName` default value is `{{{branchPrefix}}}{{{additionalBranchPrefix}}}{{{branchTopic}}}`. -The most common branch name you'll see looks like this: `renovate/react-18.x`. +The most common branch name you will see, looks like this: `renovate/react-18.x`. In this example, the `branchPrefix` is the default `renovate/`, `additionalBranchPrefix` is empty, and `branchTopic` is `react-18.x`. -Most users will be happy with the default `branchPrefix` of `renovate/`, but you can change this if you don't like the default. -Say you don't want the forward slashes, in that case you would use `renovate-` as your `branchPrefix`. +Most users will be happy with the default `branchPrefix` of `renovate/`, but you can change this if you do not like the default. +Say you do not want the forward slashes, in that case you would use `renovate-` as your `branchPrefix`. The onboarding PR will always use `renovate/configure`. `additionalBranchPrefix` is optional and by default is empty. -`branchTopic` depends on the package manager and upgrade type, so you'll see a lot of variety. +`branchTopic` depends on the package manager and upgrade type, so you will see a lot of variety. This is probably a setting you want to change yourself. Be careful, and consider creating a new "config help" post at the [discussions tab in the Renovate repository](https://github.com/renovatebot/renovate/discussions) to get help from the Renovate team with your config. @@ -34,11 +34,11 @@ The `commitMessage` reflects the contents of the branch and is usually the same `commitMessage` has a default value of `{{{commitMessagePrefix}}} {{{commitMessageAction}}} {{{commitMessageTopic}}} {{{commitMessageExtra}}} {{{commitMessageSuffix}}}`, with the intention that you only edit some of those subcomponents. -You usually don't need to edit `commitMessagePrefix`, this option is used by Renovate if it needs to add a prefix to conform to the Semantic Commit convention. -Avoid editing the commit message, unless you know what you're doing. +You usually do not need to edit `commitMessagePrefix`, this option is used by Renovate if it needs to add a prefix to conform to the Semantic Commit convention. +Avoid editing the commit message, unless you know what you are doing. `commitMessageAction` is usually one word, like 'Update', 'Pin', 'Refresh', etc. -You're probably fine leaving this setting alone, though you can change it. +You are probably fine leaving this setting alone, though you can change it. e.g. if you prefer that Renovate uses the term 'Upgrade' instead of 'Update' then you could configure `"commitMessageAction": "Upgrade"`. `commitMessageTopic` is usually two to three words that show _what_ is being updated. @@ -48,7 +48,7 @@ If you think your new `commitMessageTopic` is helpful for others, please [open a `commitMessageExtra` refers to the version being updated to. e.g. `to v18` for a major upgrade, or `to v18.0.2` for a patch update. -It can be empty in some cases, like if the action/topic doesn't change a package version, e.g. `Pin Docker digests`. +It can be empty in some cases, like if the action/topic does not change a package version, e.g. `Pin Docker digests`. `commitMessageSuffix` defaults to empty but is currently used in two cases: diff --git a/docs/usage/dependency-pinning.md b/docs/usage/dependency-pinning.md index ec4668c6b2351b..3d7f4605bfe41b 100644 --- a/docs/usage/dependency-pinning.md +++ b/docs/usage/dependency-pinning.md @@ -8,16 +8,16 @@ description: The pros and cons of dependency pinning for JavaScript/npm 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", but we can certainly make some generalisations/recommendations to help you. -If you don't want to read the in-depth discussion, you can skip ahead to our recommendations in the ["So what's best?" section](#so-whats-best). +If you do not want to read the in-depth discussion, you can skip ahead to our recommendations in the ["Recommendations" section](#recommendations). ## 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". +To ensure we are 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'll see an entry like `"foobar": "^1.1.0"` added to your `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". -The project will automatically use `1.1.1` if it's released, or `1.2.0`, or `1.2.1`, etc. - meaning you'll get not only patch updates but also feature (minor) releases too. +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. @@ -27,14 +27,14 @@ If instead you "pin" your dependencies rather than use ranges, it means you use ## 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'll get the very latest version matching your SemVer - assuming you're not using a lock file, that is. +By "automatically", we mean that any time you run `npm install` you will get the very latest version matching your SemVer - assuming you are 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"`). +If you are 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'll miss out on the fix as there will never be a `1.1.1` once `1.2.0` is already released. +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 @@ -55,7 +55,7 @@ This benefits when upgrading versions as well as when rolling back in case of pr !!! note - We'll cover lock files later, don't worry. + We will cover lock files later, do not worry. ### Upgrading pinned versions @@ -65,9 +65,9 @@ If you were using default caret SemVer ranges, then your `main` branch is now "b 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 `main` branch would not be broken because it's pinned to `foobar@1.1.0` - instead you'd 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. -By pinning dependencies you know exactly what you're running, and you know exactly what failed. +Your `main` branch would not be broken because it's pinned to `foobar@1.1.0` - instead you would have a Pull Request for upgrading to `foobar@1.2.0` which would fail. +You would know not to merge it and can wait for `foobar@1.2.1` or later when it's fixed. +By pinning dependencies you know exactly what you are running, and you know exactly what failed. 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. @@ -78,10 +78,10 @@ Like before, you need to manually work out which dependency caused it - assuming Alternatively, if you were instead pinning `foobar` then you would get a PR for `foobar@1.2.0` which awaits your approval. So first of all, you can choose to read the changelogs 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're still better off with a pinned version. +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 `main`. -When the next release of `foobar` comes out (e.g. `1.2.1`) you'll be prompted with a new PR and hopefully inspect it carefully this time before merge! +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. @@ -98,10 +98,10 @@ To some extent this is simply a trade-off for having your dependencies pinned an ### 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. +There are some dependencies that either (a) do not 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're fine. +If your build/tests pass, then you are fine. Consider enabling automerge for all lint packages to save yourself the work of manually approving the update each time. In this case you might wake up to 5/10 of your overnight Pull Requests having already merged themselves. @@ -118,24 +118,24 @@ In that case, you could set `automergeType` to `branch`, which means Renovate wi - Push the commit directly to `main` if tests pass, or - Raise a PR only if tests failed -With this approach, updates will be essentially "silent" - causing no notifications - but you'll be able to see each commit on `main` of course. +With this approach, updates will be essentially "silent" - causing no notifications - but you will be able to see each commit on `main` of course. ### Scheduling -Although it can feel satisfying to get 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 get updates "immediately" when they are available, the reality is that you usually do not _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 have 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: - Update only on weekends? This way you update packages at most once per week, _and_ your CI build runners are likely to be idle anyway -- Update daily, but between midnight and 5am? This way developers aren't bothered by notifications when they're working, _and_ you're keeping the build machines free for the developers +- Update daily, but between midnight and 5am? This way developers are not bothered by notifications when they are working, _and_ you are keeping the build machines free for the developers To learn all about controlling Renovate's schedule, read the [key concepts, scheduling](./key-concepts/scheduling.md) docs. ### Grouping related packages -Although it's good to isolate each dependency update for ease of troubleshooting, there are times when the extra noise isn't worth it, or when packages naturally belong together anyway (such as all `babel` packages). -You can add a package rule in your Renovate configuration to group these together, and you'll get 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 is not worth it, or when packages naturally belong together anyway (such as all `babel` packages). +You can add a package rule in your Renovate configuration to group these together, and you will get one branch combined even if multiple packages have updates available. ## Pinning Dependencies and Lock Files @@ -152,7 +152,7 @@ When kept in sync with its associated `package.json`, a lock file will further l To reuse an earlier example, this means that you could have `foobar@^1.1.0` in your `package.json` and be locked to `1.1.0` in your lock file, so that when the broken `foobar@1.2.0` is released, nobody on the team installs it. -### What a lock file doesn't do for you +### What a lock file does not do for you If a lock file gets out of sync with its `package.json`, it can no longer be guaranteed to lock anything, and the `package.json` will be the source of truth for installs. @@ -163,11 +163,11 @@ The lock file has only delayed the inevitable problem, and provides much less vi If the `package.json` has 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'll discover the break eventually. +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 has, 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. +In this case, hopefully you will 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. @@ -176,7 +176,7 @@ This might require even manually looking through the lock file diffs line by lin 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. +You also may be missing out on really important patches you are not even aware of, because they are "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. @@ -186,8 +186,8 @@ You could even be running `yarn upgrade` regularly to be getting _indirect_ pack So the lock file does not solve the same SemVer problems that pinning solves - but it compliments it. For this reason our usual recommendation is 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. +Do not forget though that our motto is "Flexible, so you do not need to be", so go ahead and configure however you want. +Also, we are 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? @@ -206,28 +206,28 @@ 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. +Do not 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, and so on). 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 dependencies for breaks than I am, to use the example above. +e.g. I would hope that Express are even better at watching their dependencies 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. -## So what's best? +## Recommendations We recommend: -1. Any apps (web or Node.js) that aren't `require()`'d by other packages should pin all types of dependencies for greatest reliability/predictability +1. Any apps (web or Node.js) that are not `require()`'d by other packages should pin all types of dependencies for greatest reliability/predictability 1. Browser or dual browser/node.js libraries that are consumed/`required()`'d by others should keep using SemVer ranges for `dependencies` but can use pinned dependencies for `devDependencies` -1. 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 +1. 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, do not do that if your library is a micro one likely to be consumed in disk-sensitive environments 1. Use a lock file -As noted earlier, when you pin dependencies then you'll see an increase in the raw volume of dependency updates, compared to if you use ranges. +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. +This is a "living" document, and we plan to update it whenever we think of something new or someone makes a valid point we have missed or misunderstood. 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 31073baebb21bf..f5005db978583a 100644 --- a/docs/usage/docker.md +++ b/docs/usage/docker.md @@ -15,7 +15,7 @@ Renovate supports upgrading dependencies in various types of Docker definition f ## How It Works -1. Renovate searches in each repository for any files matching each manager's configured `fileMatch` pattern(s) +1. Renovate searches in each repository for any files matching the configured `fileMatch` pattern(s) for each manager 1. Matching files are parsed, Renovate checks if the file(s) has any Docker image references (e.g. `FROM` lines in a `Dockerfile`) 1. If the image tag in use "looks" like a version (e.g. `myimage:1`, `myimage:1.1`, `myimage:1.1.0`, `myimage:1-onbuild`) then Renovate checks the Docker registry for upgrades (e.g. from `myimage:1.1.0` to `myimage:1.2.0`) @@ -23,8 +23,8 @@ Renovate supports upgrading dependencies in various types of Docker definition f By default, Renovate preserves the precision level specified in the Docker images. For example, if the existing image is pinned at `myimage:1.1` then Renovate only proposes upgrades to `myimage:1.2` or `myimage:1.3`. -This means that you'll not get upgrades to a more specific versions like `myimage:1.2.0` or `myimage:1.3.0`. -Renovate does not yet support "pinning" an imprecise version to a precise version, e.g. from `myimage:1.2` to `myimage:1.2.0`, but it's a feature we'd like to work on one day. +This means that you will not get upgrades to a more specific versions like `myimage:1.2.0` or `myimage:1.3.0`. +Renovate does not yet support "pinning" an imprecise version to a precise version, e.g. from `myimage:1.2` to `myimage:1.2.0`, but it's a feature we would like to work on one day. ## Version compatibility @@ -64,7 +64,7 @@ Another example is the official `python` image, which follows `pep440` versionin } ``` -If traditional versioning doesn't work, try Renovate's built-in `loose` `versioning`. +If traditional versioning does not work, try Renovate's built-in `loose` `versioning`. Renovate will perform a best-effort sort of the versions, regardless of whether they have letters or digits. If both the traditional versioning, and the `loose` versioning do not give the results you want, try the `regex` `versioning`. @@ -81,9 +81,9 @@ For example, if you set a version like `2.0.1`, you and your colleagues always g Docker's tags are not immutable versions, even if tags _look_ like a version. You probably expect `myimage:1` and `myimage:1.2` to change over time, but you might incorrectly assume that `myimage:1.2.0` never changes. -Although it probably _shouldn't_, the reality is that any Docker image tag _can_ change content, and potentially break. +Although it probably _should not_, the reality is that any Docker image tag _can_ change content, and potentially break. -By replacing Docker tags with Docker digests as the image's primary identifier you'll get immutable builds. +By replacing Docker tags with Docker digests as the primary identifier of the image you will get immutable builds. Working with strings like `FROM node@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e` is hard. Luckily Renovate can update the digests for you. @@ -91,13 +91,13 @@ When pinning a digest, Renovate retains the Docker tag in the `FROM` line for re ## Digest Updating -If you follow our advice to replace a tag like `node:14` with a pinned digest like `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you'll get Renovate PRs whenever the `node:14` image is updated on Docker Hub. +If you follow our advice to replace a tag like `node:14` with a pinned digest like `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you will get Renovate PRs whenever the `node:14` image is updated on Docker Hub. Previously this update would have been "invisible" to you - one day you pull code that represents `node:14.15.0` and the next day you pull code that represents `node:14.15.1`. But you can never be sure, especially as Docker caches. Maybe some of your colleagues, or worse still your build machine, are stuck on an older version with a security vulnerability. -By pinning to a digest instead, you'll get these updates via Pull Requests, or even committed directly to your repository if you enable branch automerge for convenience. +By pinning to a digest instead, you will get these updates via Pull Requests, or even committed directly to your repository if you enable branch automerge for convenience. This makes sure everyone on your team uses the latest versions. ## Version Upgrading @@ -258,7 +258,7 @@ Renovate can authenticate with AWS ECR using AWS access key id & secret as the u ##### Using Application Default Credentials / Workload Identity (Self-Hosted only) Just configure [ADC](https://cloud.google.com/docs/authentication/provide-credentials-adc) / -[Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) as normal and _don't_ +[Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) as normal and _do not_ provide a username, password or token. Renovate will automatically retrieve the credentials using the google-auth-library. @@ -364,7 +364,7 @@ If you have dependencies on Google Container Registry (and Artifact Registry) yo ##### Using short-lived access tokens -Assume you're running GitLab CI in the Google Cloud, and you're storing your Docker images in the Google Container Registry (GCR). +Assume you are running GitLab CI in the Google Cloud, and you are storing your Docker images in the Google Container Registry (GCR). Access to the GCR uses Bearer token based authentication. This token can be obtained by running `gcloud auth print-access-token`, which requires the Google Cloud SDK to be installed. diff --git a/docs/usage/examples/self-hosting.md b/docs/usage/examples/self-hosting.md index d16f4bab2029ae..34f9b3dd8b0582 100644 --- a/docs/usage/examples/self-hosting.md +++ b/docs/usage/examples/self-hosting.md @@ -158,7 +158,7 @@ spec: Do you know how to get `daniel-shuy/renovate` version `3` working? Then please open a pull request to update the docs and close [Renovate issue #13428](https://github.com/renovatebot/renovate/issues/13428). -If you're using CircleCI, you can use the third-party [daniel-shuy/renovate](https://circleci.com/developer/orbs/orb/daniel-shuy/renovate) orb to run a self-hosted instance of Renovate on CircleCI. +If you are using CircleCI, you can use the third-party [daniel-shuy/renovate](https://circleci.com/developer/orbs/orb/daniel-shuy/renovate) orb to run a self-hosted instance of Renovate on CircleCI. By default, the orb looks for the self-hosted configuration file in the project root, but you can specify another path to the configuration file with the `config_file_path` parameter. @@ -216,7 +216,7 @@ Renovate's cache, and the caches(s) for npm, Yarn, Composer, and so on, are stor ### Overriding the default directory -If you don't want to use the default `tmp/renovate` directory you can: +If you do not want to use the default `tmp/renovate` directory you can: - Set a value for `baseDir` in `config.js` - Use an environment variable `RENOVATE_BASE_DIR` @@ -230,7 +230,7 @@ If you want to override the cache directory then set your own value for `cacheDi The following example uses the Renovate CLI tool, which you can install by running `npm i -g renovate`. -If running your own Renovate bot then you'll need a user account that Renovate will run as. +If running your own Renovate bot then you will need a user account that Renovate will run as. We recommend you create and use a dedicated account for the bot, e.g. name it `renovate-bot` if on your own instance. Create and save a PAT for this account. @@ -251,7 +251,7 @@ module.exports = { Here change the `logFile` and `repositories` to something appropriate. Also replace `gitlab-token` value with the one created during the previous step. -If you're running against GitHub Enterprise Server, then change the `gitlab` values in the example to the equivalent GitHub ones. +If you are running against GitHub Enterprise Server, then change the `gitlab` values in the example to the equivalent GitHub ones. You can save this file as anything you want and then use the `RENOVATE_CONFIG_FILE` environment variable to tell Renovate where to find it. @@ -275,7 +275,7 @@ Only add the script to `cron` after you checked it works. !!! note The GitHub.com token as an environment variable is needed to fetch changelogs that are usually hosted on github.com. - You don't need to add it if you're already running the bot against github.com, but you do need to add it if you're using GitHub Enterprise Server, GitLab, Azure DevOps, or Bitbucket. + You do not need to add it if you are already running the bot against github.com, but you do need to add it if you are using GitHub Enterprise Server, GitLab, Azure DevOps, or Bitbucket. ## Kubernetes for GitLab, using Git over SSH @@ -383,7 +383,7 @@ spec: ## Logging -If you're ingesting/parsing logs into another system then we recommend you set `LOG_LEVEL=debug` and `LOG_FORMAT=json` in your environment variables. +If you are ingesting/parsing logs into another system then we recommend you set `LOG_LEVEL=debug` and `LOG_FORMAT=json` in your environment variables. Debug logging is usually needed for any debugging, while JSON format will mean that the output is parseable. ### About the log level numbers @@ -420,7 +420,7 @@ On Ubuntu/Debian and many Linux-based systems, this can be done by copying the s ### Renovate Docker image -If you're using the official [Renovate Docker image](#docker) then we recommend you add the self-signed certificate and build your own modified Docker image. +If you are using the official [Renovate Docker image](#docker) then we recommend you add the self-signed certificate and build your own modified Docker image. ```dockerfile title="Example of a Dockerfile that uses a self-signed certificate" FROM renovate/renovate diff --git a/docs/usage/faq.md b/docs/usage/faq.md index a371da56643763..d1a136a2c9ac4a 100644 --- a/docs/usage/faq.md +++ b/docs/usage/faq.md @@ -26,13 +26,13 @@ The Renovate team only fixes bugs in an older version if: - the Mend Renovate App needs to stay on that older major version for a short time, or - some critical bug needs to be fixed and the new major is blocked -If you're using the Mend Renovate App, you don't need to do anything, as the Renovate maintainers update it regularly. -If you're self-hosting Renovate, use the latest release if possible. +If you are using the Mend Renovate App, you do not need to do anything, as the Renovate maintainers update it regularly. +If you are self-hosting Renovate, use the latest release if possible. ## When is the Mend Renovate App updated with new Renovate versions? The Renovate maintainers manually update the app. -The maintainers don't follow any release schedule or release cadence. +The maintainers do not follow any release schedule or release cadence. This means the Mend Renovate App can lag a few hours to a week behind the open source version. Major releases of Renovate are held back until the maintainers are reasonably certain it works for most users. @@ -60,7 +60,7 @@ When you create a new repository with Git, Git creates a base branch for you. The default branch name that Git uses is `master` (this will be changed to `main` later). The Git-hosting ecosystem decided to use `main` instead of `master`. -When you create a new repository on say GitHub or GitLab, you'll get a `main` branch as your base branch. +When you create a new repository on say GitHub or GitLab, you will get a `main` branch as your base branch. We replaced `master` with `main` in our documentation where possible. @@ -75,7 +75,7 @@ If you have problems with Renovate, or want to know where Renovate keeps the log ### Tell Renovate to ask for approval before creating a Pull Request -By default, Renovate creates a pull request right away whenever there's an update. +By default, Renovate creates a pull request right away whenever there is an update. But maybe you want Renovate to ask for your approval _before_ it creates a pull request. Use the "Dependency Dashboard approval" workflow to get updates for certain packages - or certain types of updates - only after you give approval via the Dependency Dashboard. @@ -121,7 +121,7 @@ Read our documentation on the [dependencyDashboardApproval](./configuration-opti Say your repository's default branch is `main` but you want Renovate to use the `next` branch as its PR target. You can configure the PR target branch via the `baseBranches` option. -Add this line to the `renovate.json` file that's in the _default_ branch (`main` in this example). +Add this line to the `renovate.json` file that is in the _default_ branch (`main` in this example). ```json { @@ -155,7 +155,7 @@ Set configuration option `separateMajorMinor` to `false`. Set configuration option `rangeStrategy` to `"replace"`. -### Keep lock files (including sub-dependencies) up-to-date, even when `package.json` hasn't changed +### Keep lock files (including sub-dependencies) up-to-date, even when `package.json` has not changed By default, if you enable lock-file maintenance, Renovate will update the lockfile `["before 4am on monday"]`. If you want to update the lock file more often, set the `schedule` field inside the `lockFileMaintenance` object. @@ -243,9 +243,9 @@ Nest it inside a `patch` or `minor` object if you only want to automerge certain By default, Renovate separates major and minor releases. Patch releases are treated as "minor". -Here's an example: +Here is an example: -Say you're using version `0.8.0` of the `foo` package. +Say you are using version `0.8.0` of the `foo` package. The `foo` maintainers release the following versions: - `0.8.1` (patch) @@ -265,7 +265,7 @@ To learn more read the section below. #### Overriding the default behavior for major/minor releases -You can see in the example above that Renovate won't normally create a PR for the `foo` patch release. +You can see in the example above that Renovate does not normally create a PR for the `foo` patch release. You can tell Renovate to create a separate PR for the patch release by setting `separateMinorPatch` to `true`. @@ -275,8 +275,8 @@ In both cases, Renovate will open 3 PRs: - Update dependency `foo` to `0.9.0` (minor) - Update dependency `foo` to `1.0.0` (major) -Usually you don't want more PRs though. -It can be nice to get patch PRs when you're using automerge: +Usually you do not want more PRs though. +It can be nice to get patch PRs when you are using automerge: - Get daily patch updates which are automerged once tests pass - Get weekly updates for minor and major updates diff --git a/docs/usage/getting-started/installing-onboarding.md b/docs/usage/getting-started/installing-onboarding.md index bd41ec4a800e9b..2b87d1c902dad3 100644 --- a/docs/usage/getting-started/installing-onboarding.md +++ b/docs/usage/getting-started/installing-onboarding.md @@ -23,16 +23,16 @@ The only choice you need to make is whether to run Renovate on all repositories ![The Mend Renovate App repositories](../assets/images/github-app-choose-repos.png){ loading=lazy } -Renovate will ignore any repositories that don't have known package files, as well as any forks, so you can enable Renovate for all your repositories with no problems. +Renovate will ignore any repositories that do not have known package files, as well as any forks, so you can enable Renovate for all your repositories with no problems. That said, most people run Renovate on selected repositories. -Unfortunately GitHub doesn't offer a "select all except X, Y, Z" option, so you must select each repository where you want Renovate to run. +Unfortunately GitHub does not offer a "select all except X, Y, Z" option, so you must select each repository where you want Renovate to run. -Once you're done selecting repositories for Renovate to run on, select the green _Install_ button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. +Once you are done selecting repositories for Renovate to run on, select the green _Install_ button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. !!! note - If you're using the Mend Renovate App then it has a custom behavior for forked repositories. - If you choose "All repositories" when installing then forked repositories will be skipped by default, while if you choose "Select repositories" then they will be processed by Renovate even if they're a fork. + If you are using the Mend Renovate App then it has a custom behavior for forked repositories. + If you choose "All repositories" when installing then forked repositories will be skipped by default, while if you choose "Select repositories" then they will be processed by Renovate even if they are a fork. ### Hosted GitLab.com App @@ -53,16 +53,16 @@ You can also set the line endings in your repository by adding `* text=auto eol= ## Repository onboarding -Once you have enabled Renovate on a repository, you'll get a "Configure Renovate" Pull Request looking something like this: +Once you have enabled Renovate on a repository, you will get a "Configure Renovate" Pull Request looking something like this: ![Onboarding](../assets/images/onboarding.png){ loading=lazy } ### No risk onboarding Conveniently, Renovate will not make any changes to your repository or raise any further Pull Requests until after you _merge_ the onboarding Pull Request. -If there is anything about the Pull Request that you don't like or understand, take your time to read the [documentation](../index.md) or ask questions on the [discussions forum on GitHub](https://github.com/renovatebot/renovate/discussions) and merge the PR only once you're satisfied with the result. +If there is anything about the Pull Request that you do not like or understand, take your time to read the [documentation](../index.md) or ask questions on the [discussions forum on GitHub](https://github.com/renovatebot/renovate/discussions) and merge the PR only once you are satisfied with the result. -You can edit your Renovate configuration **within the `renovate/configure` branch** and Renovate will keep updating the description in the PR to match, so you can work on the config until you're satisfied with the results. +You can edit your Renovate configuration **within the `renovate/configure` branch** and Renovate will keep updating the description in the PR to match, so you can work on the config until you are satisfied with the results. ### Check for warnings @@ -72,7 +72,7 @@ Warnings and errors should be fixed on the base branch (e.g. `main`) so that Ren ### 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 a `renovate.json` file in your repository you can use one of the following files instead: +If you do not want a `renovate.json` file in your repository you can use one of the following files instead: - `renovate.json5` - `.github/renovate.json` @@ -92,7 +92,7 @@ If you don't want a `renovate.json` file in your repository you can use one of t You can add the same settings to a `"renovate"` section in your `package.json` file instead. The `package.json` file must be located at the root of your repository. -This is handy if you're already using a `package.json` file anyway, e.g. when you're working on a JavaScript project. +This is handy if you are already using a `package.json` file anyway, e.g. when you are working on a JavaScript project. The configuration in your `package.json` will apply to the whole project (this includes other, nested `package.json` files). ### Customized defaults @@ -116,7 +116,7 @@ Renovate will update your PR description each time it finds changes. ### Merge -Once you're done checking and configuring in your Configure Renovate PR, it's time to merge it to enable the real Pull Requests to begin. +Once you are done checking and configuring in your Configure Renovate PR, it's time to merge it to enable the real Pull Requests to begin. ## Repository re-configuration @@ -140,11 +140,11 @@ If you want to make config edits directly, follow these steps: Perhaps you really liked the interactive onboarding PR and want to use it again. You can follow the steps below to nuke the config and get a new PR. -Any existing Renovate PRs will be closed after you've completed these steps. +Any existing Renovate PRs will be closed after you have completed these steps. 1. Find your original `Configure Renovate` PR 1. Rename the original PR to something else, e.g. `Configure Renovate - old` 1. Remove the current Renovate configuration file (e.g. `renovate.json`) from your mainline branch Following these steps will trick Renovate into thinking that your repository was _never_ onboarded, and will trigger a new "Configure Renovate" PR. -If you're using the Mend Renovate App and you don't get a new onboarding PR within a few hours, then please create a Discussions post to request staff trigger it manually. +If you are using the Mend Renovate App and you do not get a new onboarding PR within a few hours, then please create a Discussions post to request staff trigger it manually. diff --git a/docs/usage/getting-started/private-packages.md b/docs/usage/getting-started/private-packages.md index 2fd94a2d4e11a6..07a392b26070ef 100644 --- a/docs/usage/getting-started/private-packages.md +++ b/docs/usage/getting-started/private-packages.md @@ -14,7 +14,7 @@ By default, Renovate only has "platform" credentials, for GitHub, GitLab, and so If the token used has sufficient permissions, this will enable Renovate to lookup dependencies located in alternative repositories on the same host or any hosted on any embedded package registry on the same host. It's also quite common to need to look up packages on other protected hosts, including npmjs, Docker Hub, or private registries like Nexus or Artifactory. -Any time you need Renovate to access such registries with credentials then you'll need to provision them as part of your config. +Any time you need Renovate to access such registries with credentials then you will need to provision them as part of your config. There are four times in Renovate's behavior when it may need credentials: @@ -25,7 +25,7 @@ There are four times in Renovate's behavior when it may need credentials: !!! note - If you self-host Renovate, and have a self-hosted registry which _doesn't_ require authentication to access, then such modules/packages are not considered "private" to Renovate. + If you self-host Renovate, and have a self-hosted registry which _does not_ require authentication to access, then such modules/packages are not considered "private" to Renovate. ## Private Config Presets @@ -39,7 +39,7 @@ Credentials stored on disk (e.g. in `~/.npmrc`) are no longer supported. The recommended way of using local presets is to configure then using "local" presets, e.g. `"extends": ["local>myorg/renovate-config"]`, and ensure that the platform token has access to that repo. It's not recommended that you use a private repository to host your config while then extending it from a public repository. -If your preset doesn't have secrets then you should make it public, while if it does have secrets then it's better to split your preset between a public one which all repos extend, and a private one with secrets which only other private repos extend. +If your preset does not have secrets then you should make it public, while if it does have secrets then it's better to split your preset between a public one which all repos extend, and a private one with secrets which only other private repos extend. In summary, the recommended approach to private presets is: @@ -205,7 +205,7 @@ The environment variables used are: `GIT_CONFIG_KEY_0=url.https://${token}@githu ### helm -Maybe you're running your own ChartMuseum server to host your private Helm Charts. +Maybe you are running your own ChartMuseum server to host your private Helm Charts. This is how you connect to a private Helm repository: ```js title="Connecting to a private Helm repository" @@ -284,7 +284,7 @@ This merge approach is similar to how `npm` itself behaves if a `.npmrc`-file is #### Add npmToken to Renovate config -If you're using the main npm registry then you only need to configure the `npmToken` instead: +If you are using the main npm registry then you only need to configure the `npmToken` instead: ```json { @@ -294,7 +294,7 @@ If you're using the main npm registry then you only need to configure the `npmTo #### Add an encrypted npm token to Renovate config -If you don't want all users of the repository to see the plaintext token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. +If you do not want all users of the repository to see the plaintext token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. Go to , paste in your npm token, select "Encrypt", then copy the encrypted result. @@ -324,13 +324,13 @@ Renovate will then use the following logic: 1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry 1. If an `npmrc` string is present and has a `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token -1. If an `npmrc` string is present but doesn't have a `${NPM_TOKEN}` then the file will have `_authToken=` appended to it +1. If an `npmrc` string is present but does not have a `${NPM_TOKEN}` then the file will have `_authToken=` appended to it #### Encrypted entire .npmrc file into config Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at . -You'll then get an encrypted string that you can substitute into your `renovate.json` instead. +You will then get an encrypted string that you can substitute into your `renovate.json` instead. The end-result looks like this: ```json @@ -360,7 +360,7 @@ The end-result looks like this: #### Yarn 2+ -Renovate doesn't support reading `npmRegistries` and `npmScopes` from `.yarnrc.yml`, so `hostRules` (or `npmToken`) and `npmrc` should be configured like above. +Renovate does not support reading `npmRegistries` and `npmScopes` from `.yarnrc.yml`, so `hostRules` (or `npmToken`) and `npmrc` should be configured like above. Renovate updates `npmRegistries` in `.yarnrc.yml` with resolved `hostRules` before running Yarn. For Renovate to overwrite existing `npmRegistries` entry, the key should match the `matchHost` minus the protocol (`http:` or `https:`) plus the trailing slash. @@ -417,7 +417,7 @@ hostRules: [ { matchHost: 'https://pkgs.dev.azure.com//', hostType: 'nuget', - username: 'user', // doesn't matter for azure + username: 'user', // does not matter for azure password: '', }, ]; @@ -472,7 +472,7 @@ module.exports = { }; ``` -If you're self-hosting Renovate via the [GitLab Runner](../getting-started/running.md#gitlab-runner) and want to access packages from private GitLab registries, you can use the GitLab CI job token for authentication: +If you are self-hosting Renovate via the [GitLab Runner](../getting-started/running.md#gitlab-runner) and want to access packages from private GitLab registries, you can use the GitLab CI job token for authentication: ```js module.exports = { @@ -512,11 +512,11 @@ For example: ## Encryption and the Mend Renovate App Many users use [the Mend Renovate App](https://github.com/apps/renovate), which is hosted by Mend. -If you're a user of this app, and have private modules, then the following is applicable. +If you are a user of this app, and have private modules, then the following is applicable. ### Private presets with public repositories -If you have a preset in a private repo but reference ("extend") it from a public repository then it won't work. +If you have a preset in a private repo but reference ("extend") it from a public repository then it does not work. This is because public repositories are provided with a token scoped to only that particular repository, and not for all repositories within the organization. This is a security measure so that if the token is accidentally leaked publicly, the damage is limited to the public repository it leaked to and not to every repository within the organization. @@ -577,7 +577,7 @@ For instructions on this, see the above section on encrypting secrets for the Me !!! note - Encrypted values can't be used in the "Admin/Bot config". + Encrypted values can not be used in the "Admin/Bot config". ### hostRules configuration using environment variables diff --git a/docs/usage/getting-started/running.md b/docs/usage/getting-started/running.md index d4693d60b366b6..42c19508793328 100644 --- a/docs/usage/getting-started/running.md +++ b/docs/usage/getting-started/running.md @@ -6,20 +6,20 @@ As end user, you can choose from these ways to run Renovate: - You self-administer/host your own Renovate instance - Someone else is hosting Renovate, and you install/configure it for the repositories you choose -If you're using the Mend Renovate App, or if someone else is hosting Renovate for you, skip ahead to the [installing & onboarding](./installing-onboarding.md) page. +If you are using the Mend Renovate App, or if someone else is hosting Renovate for you, skip ahead to the [installing & onboarding](./installing-onboarding.md) page. ## Self-Hosting Renovate -When self-hosting Renovate you're the "administrator" of the bot, this means you: +When self-hosting Renovate you are the "administrator" of the bot, this means you: - provide the infrastructure that Renovate runs on, - provision Renovate's global config, - make sure Renovate bot runs regularly, - make sure Renovate bot itself is updated -If you're self-hosting Renovate on Windows, read [Self-hosting on Windows](./installing-onboarding.md#self-hosting-on-windows) to prevent line endings from confusing Renovate bot. +If you are self-hosting Renovate on Windows, read [Self-hosting on Windows](./installing-onboarding.md#self-hosting-on-windows) to prevent line endings from confusing Renovate bot. -If you're running Renovate Community Edition or Renovate Enterprise Edition, refer to the documentation on the [`mend/renovate-ce-ee` GitHub repository](https://github.com/mend/renovate-ce-ee). +If you are running Renovate Community Edition or Renovate Enterprise Edition, refer to the documentation on the [`mend/renovate-ce-ee` GitHub repository](https://github.com/mend/renovate-ce-ee). ### Available distributions @@ -28,7 +28,7 @@ If you're running Renovate Community Edition or Renovate Enterprise Edition, ref Renovate's Open Source CLI is built and distributed as the npm package `renovate`. You can run this package in any Node.js environment - even via `npx` - and it will process all the repositories it is configured with, before exiting. -When installing Renovate via npm you're responsible for installing any third-party tools or languages like Ruby, Python, Composer, Bundler, Poetry, etc. +When installing Renovate via npm you are responsible for installing any third-party tools or languages like Ruby, Python, Composer, Bundler, Poetry, etc. The `renovate` npm package is compatible with all of Renovate's supported platforms. @@ -38,7 +38,7 @@ Renovate is also distributed as Docker images on Docker Hub (`renovate/renovate` These Docker images work on all the hosting platforms that Renovate supports. Both `linux/amd64` and `linux/arm64` architectures are supported, but you may still find some bugs in the `arm64` image. -You can't run the Docker images in a Windows or macOS container. +You can not run the Docker images in a Windows or macOS container. In general, you can run Renovate natively on Windows as long as you have all tools it will need (e.g. `npm`, `pipenv`, etc.) preinstalled before you run Renovate. @@ -58,7 +58,7 @@ Renovate supports a persistent cache for downloaded tools, so that it only needs Use the [`containerbaseDir` config option](../self-hosted-configuration.md#containerbasedir) to control where Renovate stores its containerbase cache. If you want, you can map the Docker socket into the container so that Renovate can dynamically invoke "sidecar" images when needed. -You'll need to set `binarySource=docker` for this to work. +You will need to set `binarySource=docker` for this to work. Read the [`binarySource` config option docs](../self-hosted-configuration.md#binarysource) for more information. ##### The full image @@ -66,7 +66,7 @@ Read the [`binarySource` config option docs](../self-hosted-configuration.md#bin The `-full` image comes with most package managers that Renovate supports, but not _all_ package managers. Update your Docker images regularly to keep the preinstalled tools up-to-date. -The full image is for users who don't want to download or install things at runtime. +The full image is for users who do not want to download or install things at runtime. This image has some downsides, because it: - Comes preinstalled with _one_ version of each language/manager - usually the latest @@ -126,7 +126,7 @@ Forking Renovate needs only `read` level access to the code of any repository it ##### Drawbacks -If you use Forking Renovate, you'll miss out on these features of the regular Renovate app: +If you use Forking Renovate, you will miss out on these features of the regular Renovate app: - Automerge - The `baseBranches` config option @@ -136,7 +136,7 @@ If you use Forking Renovate, you'll miss out on these features of the regular Re After deciding on a Renovate distribution, you need to decide where and how to run it. For the GitHub Action and GitLab Runner approaches, they will naturally run on their respective CI infrastructure. -For the npm package approach or Docker images, you'll need some form of VM or container infrastructure to run Renovate on. +For the npm package approach or Docker images, you will need some form of VM or container infrastructure to run Renovate on. In all the above cases you must make sure that some form of cron-like capability exists to schedule when Renovate runs. We recommend that you run Renovate hourly, if possible. @@ -160,7 +160,7 @@ Your bot's global config can include both global and non-global configuration op We recommend that you keep as much of the non-global config as possible in repository config files. This way the Renovate end users can see as much of the bot's configuration as possible. -If you're configuring Renovate using environment variables, there are two possibilities: +If you are configuring Renovate using environment variables, there are two possibilities: - Upper-cased, camel-cased, `RENOVATE_`-prefixed single config options like `RENOVATE_TOKEN=abc123` or `RENOVATE_GIT_AUTHOR=a@b.com` - Set `RENOVATE_CONFIG` to a [stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) version of the full JSON config, for example: `RENOVATE_CONFIG='{"token":"abc123","gitAuthor":"a@b.com"}'` @@ -190,7 +190,7 @@ An example of a `config.js` that exports an `async` function (which is a functio ### Authentication Regardless of platform, you need to select a user account for `renovate` to assume the identity of, and generate a Personal Access Token. -We recommend you use `@renovate-bot` as username if you're on a self-hosted server where you can set all usernames. +We recommend you use `@renovate-bot` as username if you are on a self-hosted server where you can set all usernames. We also recommend you configure `config.gitAuthor` with the same identity as your Renovate user, for example: `"gitAuthor": "Renovate Bot "`. @@ -211,15 +211,15 @@ Read the platform-specific docs to learn how to set up authentication on your pl ### GitHub.com token for changelogs -If you're running on any platform except github.com, you should also set the environment variable `GITHUB_COM_TOKEN` and put the Personal Access Token for github.com in it. +If you are running on any platform except github.com, you should also set the environment variable `GITHUB_COM_TOKEN` and put the Personal Access Token for github.com in it. This account can be _any_ account on GitHub, and needs only `read-only` access. It's used when fetching changelogs 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 modules hosted on GitHub), we highly recommend that you add a `github.com` PAT (classic). - Otherwise, you'll exceed the rate limit for the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies. + If you are using Renovate in a project where dependencies are loaded from github.com (such as Go modules hosted on GitHub), we highly recommend that you add a `github.com` PAT (classic). + Otherwise, you will exceed the rate limit for the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies. ### Self-hosting examples diff --git a/docs/usage/getting-started/use-cases.md b/docs/usage/getting-started/use-cases.md index 6be6afc52ef193..c8d0aee6fc4442 100644 --- a/docs/usage/getting-started/use-cases.md +++ b/docs/usage/getting-started/use-cases.md @@ -29,7 +29,7 @@ The Pull Requests patch the package files directly, and include changelogs for t By default: -- You'll get separate Pull Requests for each dependency +- You will get separate Pull Requests for each dependency - Major updates are kept separate from non-major updates ### Package managers with lock files @@ -38,7 +38,7 @@ Many package managers support "lock files", which "freeze" the entire dependency npm, Yarn, Bundler, Composer, Poetry, Pipenv, and Cargo all support or use lock files. If you use a lock file then changes to your package file must come with a compatible change to the lock file. -Renovate can patch/update package files directly, but can't "reverse engineer" lock files. +Renovate can patch/update package files directly, but can not "reverse engineer" lock files. This is why Renovate lets the package manager do the lock file update. A simplified example: @@ -99,11 +99,11 @@ Renovate understands both formats and raises updates like these: #### Docker digests You can check and update versions like `14.17.4` yourself. -But looking up image digests like `341976f40d963a425d627a349a9b0034e1eafffbf4c82a173c1465ee403878d9` and updating them yourself doesn't scale. +But looking up image digests like `341976f40d963a425d627a349a9b0034e1eafffbf4c82a173c1465ee403878d9` and updating them yourself does not scale. So let Renovate update your Docker digests. You can even configure Renovate to "pin" your Docker digests. -When you're using tag+digest based images, you'll have immutable builds. +When you are using tag+digest based images, you will have immutable builds. ### Internal package updates @@ -147,12 +147,12 @@ We split our work over two repositories: ##### Benefits -The way we've set things up means we avoid: +The way we have set things up means we avoid: - reviewing PRs - manually merging PRs -In fact, we don't even get the update PR anymore! +In fact, we do not even get the update PR anymore! ## Advanced configuration @@ -170,7 +170,7 @@ You can configure batched updates by setting a `groupName` as part of `packageRu You may want to limit the times when Renovate is allowed to raise updates. This reduces "noise" during your working hours, and reduces the chance of CI contention. -You can tell Renovate to "not bother you" during times when you're using the CI resources, or want to focus on your work. +You can tell Renovate to "not bother you" during times when you are using the CI resources, or want to focus on your work. You can set the time ranges during which Renovate creates updates in the `schedule` field. @@ -201,7 +201,7 @@ Here's how it works: Benefits of using Dependency Dashboard Approval: -- By not raising PRs automatically, it allows you to request updates on-demand when you're ready, and +- By not raising PRs automatically, it allows you to request updates on-demand when you are ready, and - It offers you an alternative to permanently ignoring/disabling certain types of updates, like major updates When you use the Dependency Dashboard Approval workflow you have full visibility and control over your updates. diff --git a/docs/usage/gitlab-bot-security.md b/docs/usage/gitlab-bot-security.md index ea9b7e575d184a..c99fc8534cbe7e 100644 --- a/docs/usage/gitlab-bot-security.md +++ b/docs/usage/gitlab-bot-security.md @@ -30,10 +30,10 @@ Therefore, we stopped hosting Renovate on GitLab, and are waiting for a better s You should remember that when accounts are invited into projects or groups on GitLab, acceptance happens automatically. This was a useful feature to leverage for a shared service. -If you're running a self-hosted Renovate service, we recommend you: +If you are running a self-hosted Renovate service, we recommend you: -- Run a shared service only within projects which have shared visibility/security within the users, or which have a low risk that a user would try to gain access to a private project they don't otherwise have access to -- If running with `autodiscover`, also configure a value for `autodiscoverFilter` so that the bot can't be invited to projects or groups you don't intend +- Run a shared service only within projects which have shared visibility/security within the users, or which have a low risk that a user would try to gain access to a private project they do not otherwise have access to +- If running with `autodiscover`, also configure a value for `autodiscoverFilter` so that the bot can not be invited to projects or groups you do not intend ## Security solutions and workarounds @@ -45,7 +45,7 @@ If you only run a bot service on _public_ projects, the risk of unauthorized use But malicious users can still spoof or spam packages to any other public project they are not a member of, this rules out this approach for a public hosted service. A public-visibility-only bot service should be low risk for most self-hosted GitLab instances. -But you _can't stop users_ from inviting the bot into _private_ projects by accident, which is risky. +But you _can not stop users_ from inviting the bot into _private_ projects by accident, which is risky. ### Project Access Tokens @@ -68,7 +68,7 @@ Permissions and visibility _must_ be kept uniform throughout the group to preven Many GitLab users _do not_ have uniform permissions and visibility throughout groups today, so this is a risk of Group Access Tokens in general. The [`gitlab-org` organization on GitLab](https://gitlab.com/gitlab-org) shows how common it is to mix project visibility within a same group. -And the same as with PATs, if Group Access Tokens becomes a paid feature then users on a free plan can't use the feature. +And the same as with PATs, if Group Access Tokens becomes a paid feature then users on a free plan can not use the feature. ### Skipping CI @@ -91,7 +91,7 @@ Read the [renovate-bot/renovate-runner README on GitLab](https://gitlab.com/reno ## Status of the Renovate app for GitLab -We're trying to find a workable design for the GitLab app, so we can enable it safely again. +We are trying to find a workable design for the GitLab app, so we can enable it safely again. If you have any ideas, please open a [discussion](https://github.com/renovatebot/renovate/discussions) and let us know! GitLab introduced Group Access Tokens & API for paid & self-hosted instances, but a good permission setup/flow is still not possible. diff --git a/docs/usage/golang.md b/docs/usage/golang.md index 4e20f51b82512c..ae52031c8829ae 100644 --- a/docs/usage/golang.md +++ b/docs/usage/golang.md @@ -7,7 +7,7 @@ description: Go modules support in Renovate Renovate supports upgrading dependencies in `go.mod` files and associated `go.sum` checksums. -If you're self-hosting Renovate, you may use these environment variables: +If you are self-hosting Renovate, you may use these environment variables: - `GOPROXY` - `GONOPROXY` @@ -20,7 +20,7 @@ To learn what these variables do, read the [Go Modules Reference about the`GOPRO 1. Renovate searches in each repository for any `go.mod` files 1. Renovate extracts existing dependencies from `require` statements -1. Renovate resolves the dependency's source repository and checks for SemVer tags if found. Otherwise, commits and `v0.0.0-....` syntax will be used +1. Renovate resolves the source repository of the dependency and checks for SemVer tags if found. Otherwise, commits and `v0.0.0-....` syntax will be used 1. If Renovate finds an update, Renovate will update `go.mod` to the new value 1. Renovate runs `go get` to update the `go.sum` files (you can configure which directory are included using the `goGetDirs` option) 1. If the user has enabled the option `gomodUpdateImportPaths` in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions) array, then Renovate uses [mod](https://github.com/marwan-at-work/mod) to update import paths on major updates, which can update any Go source file diff --git a/docs/usage/java.md b/docs/usage/java.md index 51b0e7caf8f36b..513de7cc53b4ac 100644 --- a/docs/usage/java.md +++ b/docs/usage/java.md @@ -104,7 +104,7 @@ The manager for Gradle makes use of the `maven` datasource. Renovate can be configured to access more repositories and access repositories authenticated. This example shows how you can use a `config.js` file to configure Renovate for use with Artifactory. -We're using environment variables to pass the Artifactory username and password to Renovate bot. +We are using environment variables to pass the Artifactory username and password to Renovate bot. ```js title="config.js" module.exports = { @@ -138,7 +138,7 @@ There are multiple ways to configure Renovate to access Artifact Registry. #### Using Application Default Credentials / Workload Identity (Self-Hosted only) -Configure [ADC](https://cloud.google.com/docs/authentication/provide-credentials-adc) or [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) as normal and _don't_ provide a username, password or token. +Configure [ADC](https://cloud.google.com/docs/authentication/provide-credentials-adc) or [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) as normal and _do not_ provide a username, password or token. Renovate will automatically retrieve the credentials using the `google-auth-library`. #### Using long-lived service account credentials diff --git a/docs/usage/key-concepts/automerge.md b/docs/usage/key-concepts/automerge.md index 8905bebffc107d..15561e52a51bec 100644 --- a/docs/usage/key-concepts/automerge.md +++ b/docs/usage/key-concepts/automerge.md @@ -15,7 +15,7 @@ If you or others keep committing to the default branch then Renovate cannot find Once a branch is automerged, the "Git state" needs to be recalculated for every remaining branch. At times, merging one branch could result in another branch's updates being changed or even removed as unnecessary. Renovate's approach is to ensure that automerging branches are up-to-date with their target branch before automerging. -This means merging multiple branches in a row won't work reliably, so we prefer not to do that. +This means merging multiple branches in a row does not work reliably, so we prefer not to do that. What all this means is that Renovate will only automerge at most one branch/PR per target branch per run, before you need to wait for the next run. As a general guide, we recommend that you enable automerge for any type of dependency updates where you would select "merge" anyway. @@ -65,7 +65,7 @@ But in many cases the new version(s) will pass tests, and if so then there's rea ### Automerge non-major updates -Non-major updates in SemVer ecosystems shouldn't have breaking changes (if they follow the spec), so many users enable automerge for these too: +Non-major updates in SemVer ecosystems should not have breaking changes (if they follow the spec), so many users enable automerge for these too: ```json title="Example of automerging non-major updates in SemVer ecosystem" { @@ -100,7 +100,7 @@ Say you want to automerge `patch` and `minor` updates for packages in the `group ### Faster merges with platform-native automerge By default, Renovate uses platform-native automerge to speed up automerging. -If you don't want Renovate to use the platform-native automerge, then set `platformAutomerge` to `false`. +If you do not want Renovate to use the platform-native automerge, then set `platformAutomerge` to `false`. ```json title="Example of disabling platform-native automerge" { @@ -144,7 +144,7 @@ on: On `github.com`, go to your repository's "homepage", click on Settings, scroll down to the Pull Requests section and [enable the "Allow auto-merge" checkbox](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository#managing-auto-merge). Then go to your repository's branch protection rules for your base branch (usually `main`) and enable the "Require merge queue" setting. -Confirm you've set the correct "required checks" for your base branch. +Confirm you have set the correct "required checks" for your base branch. Finally, allow Renovate to automerge by setting `automerge=true` in your Renovate config file, for example: @@ -160,15 +160,15 @@ Finally, allow Renovate to automerge by setting `automerge=true` in your Renovat } ``` -#### If you don't use GitHub Actions +#### If you do not use GitHub Actions -If you _don't_ use GitHub Actions as your CI provider, follow these steps: +If you _do not_ use GitHub Actions as your CI provider, follow these steps: Update your CI provider's configuration, so it also runs tests on the temporary `gh-readonly-queue/{base_branch}` branches, read your CI provider's documentation to learn how to do this. On `github.com`, go to your repository's "homepage", click on Settings, scroll down to the Pull Requests section and [enable the "Allow auto-merge" checkbox](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository#managing-auto-merge). Go to your repository's branch protection rules for your base branch (usually `main`) and enable the "Require merge queue" setting. -Confirm you've set the correct "required checks" for your base branch. +Confirm you have set the correct "required checks" for your base branch. Finally, allow Renovate to automerge by setting `automerge=true` in your Renovate config file (see earlier example). @@ -189,7 +189,7 @@ This is a lot better than you waking up to two PRs and then having to deal with ## Branch vs PR automerging -Even if you automerge PRs, you're likely to still get notification noise - one when the PR is created and another when it is merged. +Even if you automerge PRs, you are likely to still get notification noise - 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 @@ -199,14 +199,14 @@ For this reason we recommend you consider setting `automergeType=branch` which w Add the `renovate/**` branch to your testing workflow files, or Renovate will not work properly with the `automergeType=branch` setting. The result is that passing updates are essentially "silent" - the only sign of them are the commits Renovate pushes to your base branch. -If you have enabled branch protection which prevents Renovate from automerging directly to the base branch, then this won't work, and you should stick with the default PR-based automerging instead. +If you have enabled branch protection which prevents Renovate from automerging directly to the base branch, then this does not work, and you should stick with the default PR-based automerging instead. ## Assignees and Reviewers When automerge is enabled on a PR, Renovate will _not_ add assignees or reviewers at PR creation time, in order to decrease notifications noise a little. If tests subsequently _fail_, making automerge not possible, then Renovate will add the configured assignees and/or reviewers. -Note: Renovate won't add assignees and reviewers to a PR with failing checks if the PR already has assignees or reviewers present. +Note: Renovate does not add assignees and reviewers to a PR with failing checks if the PR already has assignees or reviewers present. If there are accounts you wish to ignore (i.e. add assignees and reviewers regardless) then add them to `ignoreReviewers` to specify those which should be filtered out in such consideration. ## Frequent problems and how to resolve them @@ -224,11 +224,11 @@ If you have no tests but still want Renovate to automerge, you need to add `"ign !!! tip - We strongly recommend you have tests in any project where you're regularly updating dependencies. + We strongly recommend you have tests in any project where you are regularly updating dependencies. ### Committer restrictions -If you have protected your base branch with a list of allowed committers, and Renovate is not on that list, then naturally automerge can't work. +If you have protected your base branch with a list of allowed committers, and Renovate is not on that list, then naturally automerge can not work. ### Pull Requests Required @@ -236,9 +236,9 @@ If you have configured your project to require Pull Requests before merging, it ### Required Pull Request reviews -If you have mandatory Pull Request reviews then it means Renovate can't automerge its own PR until such a review has happened. +If you have mandatory Pull Request reviews then it means Renovate can not automerge its own PR until such a review has happened. -If you're on `github.com` or GitHub Enterprise Server (`>=3.4`) you can let Renovate bypass the mandatory Pull Request reviews using the "[Allow specified actors to bypass required pull requests](https://github.blog/changelog/2021-11-19-allow-bypassing-required-pull-requests/)" option in your branch protection rules. +If you are on `github.com` or GitHub Enterprise Server (`>=3.4`) you can let Renovate bypass the mandatory Pull Request reviews using the "[Allow specified actors to bypass required pull requests](https://github.blog/changelog/2021-11-19-allow-bypassing-required-pull-requests/)" option in your branch protection rules. Alternatively, if you use the Mend Renovate App, you can also install the helper apps [renovate-approve](https://github.com/apps/renovate-approve) and [renovate-approve-2](https://github.com/apps/renovate-approve-2) and they will mark all automerging Pull Requests by Renovate as approved. These approval helper apps are only available for GitHub. @@ -250,8 +250,8 @@ Depending on the platform, having a `CODEOWNERS` file could block automerging, b ### Overriding global automerge You might have set up a global configuration in a `.github` repository, that has a `renovate.json` file that turns on automerge for certain dependencies. -It does not matter where you've put the global config, the important point in this example is that you're extending from a global config that's somewhere else. -For this example we'll assume you put your config in a repository on GitHub, called `.github`. +It does not matter where you have put the global config, the important point in this example is that you are extending from a global config that's somewhere else. +For this example we will assume you put your config in a repository on GitHub, called `.github`. Repositories in the organization all extend from this global configuration, and so they "inherit" the automerge settings as well. diff --git a/docs/usage/key-concepts/changelogs.md b/docs/usage/key-concepts/changelogs.md index b21f943936d168..435e923f779817 100644 --- a/docs/usage/key-concepts/changelogs.md +++ b/docs/usage/key-concepts/changelogs.md @@ -32,11 +32,11 @@ For more details, see [Private packages, looking up changelogs](../getting-start Set to `off` if changelog fetching is causing a problem. -Set to `branch` if you have an advanced use case where you're embedding changelogs in the Git commit itself, we don't recommend this due to its potential size. +Set to `branch` if you have an advanced use case where you are embedding changelogs in the Git commit itself, we do not recommend this due to its potential size. ### [`customChangelogUrl`](../configuration-options.md#customchangelogurl) -This doesn't help with _fetching_ the changelogs, but if you configure it then Renovate will include a link to this URL in the PR body, so users can click through to read the changelog. +This does not help with _fetching_ the changelogs, but if you configure it then Renovate will include a link to this URL in the PR body, so users can click through to read the changelog. ## Platforms that Renovate can fetch changelogs from @@ -58,9 +58,9 @@ Follow these steps to find out why Renovate does not find a changelog: 1. The datasource for this package does not support sourceUrls. - If the registry fundamentally does not provide this data, then the only possibility is for it to be manually populated through PRs to Renovate's source code - If the registry provides source URLs in its response but Renovate does not understand the required fields, then raise a feature request with examples, or better yet a Pull Request to implement support for the source URL parsing/mapping yourself - - Sometimes self-hosted versions of registries don't include the full metadata compared to what the public registries do + - Sometimes self-hosted versions of registries do not include the full metadata compared to what the public registries do 1. The package was published without source URL information being included. - - For example, occasionally `npm` packages don't have `repository` fields included + - For example, occasionally `npm` packages do not have `repository` fields included - For example, Docker images regularly do not have the required `LABEL` entry 1. Renovate cannot access the source repository - This is typically a concern for private repositories only @@ -74,7 +74,7 @@ If none of these steps help, search the Renovate issues and discussions to see i This section is for package maintainers that want to make sure Renovate can see their changelogs. -There isn't much information to add other than what's already written above. +There is not a lot of information to add other than what's already written above. Make sure that you have the required source URL in your package metadata, not just in your repository but also in the final data which the registry returns. For example, we have seen cases where the `repository` field in the npm `package.json` is populated correctly in the repository, but stripped out as part of the publishing process. diff --git a/docs/usage/key-concepts/dashboard.md b/docs/usage/key-concepts/dashboard.md index a564d63dc9f41f..2a1b8fe973a4ee 100644 --- a/docs/usage/key-concepts/dashboard.md +++ b/docs/usage/key-concepts/dashboard.md @@ -73,9 +73,9 @@ You can mix and match these options as well. We do not recommend that you require approval for _all_ updates. When you require prior approval, you need to check the dashboard issue regularly to check for important updates. -You'll probably forget to check often enough, and out of sight means out of mind! +You will probably forget to check often enough, and out of sight means out of mind! -Maybe you find Renovate too noisy, and want to opt-out of getting automatic updates whenever they're ready. +Maybe you find Renovate too noisy, and want to opt-out of getting automatic updates whenever they are ready. In this case, you can tell Renovate to wait for your approval before making any pull requests. This means that you have full control over when you get updates. @@ -111,7 +111,7 @@ If you want to require approval for major updates, set `dependencyDashboardAppro Sometimes you only want to update specific packages when you say so. -Maybe a package doesn't follow Semantic Versioning, and has breaking changes on every new release, so you want to update on your terms. +Maybe a package does not follow Semantic Versioning, and has breaking changes on every new release, so you want to update on your terms. Or maybe you have a package that updates too rapidly for you to keep up with, and you want to update once in a while manually. diff --git a/docs/usage/key-concepts/presets.md b/docs/usage/key-concepts/presets.md index 2f43325a4e32df..33f8daf162582d 100644 --- a/docs/usage/key-concepts/presets.md +++ b/docs/usage/key-concepts/presets.md @@ -18,7 +18,7 @@ Use presets to: ## How to use presets -Let's say you're using the `config:recommended` preset, and want to pin your GitHub Action digests. +Let's say you are using the `config:recommended` preset, and want to pin your GitHub Action digests. Instead of writing your own Renovate config, you search through Renovate's built-in presets. You find the `helpers:pinGitHubActionDigests` preset and add it to the `extends` array: diff --git a/docs/usage/key-concepts/pull-requests.md b/docs/usage/key-concepts/pull-requests.md index f13629157c8e42..a712e5a8f0cab9 100644 --- a/docs/usage/key-concepts/pull-requests.md +++ b/docs/usage/key-concepts/pull-requests.md @@ -21,17 +21,17 @@ But if you group PRs and use titles like "All non-major updates", then multiple ## Normal PRs As explained above, Renovate PRs normally have some "uniqueness" in their title relating to the version in the upgrade. -When you close a "unique" PR, Renovate assumes you don't want to see that PR again in the future, for example: +When you close a "unique" PR, Renovate assumes you do not want to see that PR again in the future, for example: 1. You ignored `lodash@4.17.21` by closing Renovate's PR -1. Renovate assumes you don't want any updates to `4.17.21` of `lodash` +1. Renovate assumes you do not want any updates to `4.17.21` of `lodash` 1. Renovate creates a new PR when the branch + title "uniqueness" exists again, like when `lodash@4.17.22` releases Renovate behaves similarly for `major` updates, for example: 1. You ignored a `major` update for Lodash (pr title: "Update lodash to v4") by closing Renovate's PR -1. Renovate assumes you don't want any updates to `v4` of `lodash` -1. Renovate won't create any update PRs for `v4` of `lodash`, even if there are newer versions of `v4` +1. Renovate assumes you do not want any updates to `v4` of `lodash` +1. Renovate does not create any update PRs for `v4` of `lodash`, even if there are newer versions of `v4` ## Immortal PRs @@ -45,8 +45,8 @@ This document explains why we have immortal PRs, and how you can fix them. ### Why we have immortal PRs -First off, we don't have immortal PRs for some philosophical reason like: "don't ignore this update, it's good for you!". -We have no good way to ignore some PRs after they're closed. +First off, we do not have immortal PRs for some philosophical reason like: "do not ignore this update, it's good for you!". +We have no good way to ignore some PRs after they are closed. #### Branch name and PR title are cache keys @@ -70,7 +70,7 @@ Then the update becomes "Update react (major)", which is not safely ignorable, i ### Future plans for immortal PRs In the future we may embed metadata in each PR identifying the exact files and packages + versions that PR contains. -Then we could allow such PRs to be closed/ignored but then as soon as there's any chance to files/packages/versions being updated then we'd be cache busted and create a new PR. +Then we could allow such PRs to be closed/ignored but then as soon as there's any chance to files/packages/versions being updated then we would be cache busted and create a new PR. If you regularly wish to close immortal PRs, it's an indication that you may be grouping too widely. ### How to fix immortal PRs diff --git a/docs/usage/key-concepts/scheduling.md b/docs/usage/key-concepts/scheduling.md index 204bff8f1f2d24..fd4824cc23345a 100644 --- a/docs/usage/key-concepts/scheduling.md +++ b/docs/usage/key-concepts/scheduling.md @@ -62,7 +62,7 @@ Also read the [`timezone` config option docs](../configuration-options.md#timezo ### Scheduling syntax -After you've set your local timezone, you can define "days of the week" or "hours of the day" in which Renovate is allowed to make changes. +After you have set your local timezone, you can define "days of the week" or "hours of the day" in which Renovate is allowed to make changes. ```title="Examples of the kind of schedules you can create" every weekend diff --git a/docs/usage/known-limitations.md b/docs/usage/known-limitations.md index fd0757ec3f1c5b..df2a728ea844bb 100644 --- a/docs/usage/known-limitations.md +++ b/docs/usage/known-limitations.md @@ -5,16 +5,16 @@ Learn about the limitations of Renovate bot. ## Introduction Renovate, like any computer program has limitations. -Sometimes these are functionality limitations - perhaps something is impossible or too complex to do, or we simply haven't implemented it yet. +Sometimes these are functionality limitations - perhaps something is impossible or too complex to do, or we simply have not implemented it yet. At other times it may be a "performance" limitation, because jobs neither start nor complete instantly, even if the user may start with that expectation. -This document tries to list out the most commonly seen limitations and describe whether they're permanent and if there's any plans to improving the situation. +This document tries to list out the most commonly seen limitations and describe whether they are permanent and if there is any plans to improving the situation. ## Time/schedule based limitations When a user configures a schedule in their repo config, they may think that this schedule "controls" when Renovate runs. In actuality, Renovate may be running frequently, but skipping updates to the repo if the configured schedule is not met. -Additionally, the Renovate admin may have put the bot on its own schedule, or the job queue may be too long, so Renovate doesn't even get a chance to run on your repository during a certain scheduled time window. +Additionally, the Renovate admin may have put the bot on its own schedule, or the job queue may be too long, so Renovate does not even get a chance to run on your repository during a certain scheduled time window. For scheduled action to take place, both these need to happen: diff --git a/docs/usage/merge-confidence.md b/docs/usage/merge-confidence.md index 01a24c4633abbb..b6ee0fbb38e635 100644 --- a/docs/usage/merge-confidence.md +++ b/docs/usage/merge-confidence.md @@ -15,7 +15,7 @@ It analyzes test and release adoption data from the Mend Renovate App users. Merge Confidence adds the following badges to your pull requests: - **Age**: The age of the package -- **Adoption**: The percentage of this package's users (within Renovate) which are using this release +- **Adoption**: The percentage of users of this package (within Renovate) who are using this release - **Passing**: The percentage of updates which have passing tests for this package - **Confidence**: The confidence level for this update @@ -43,7 +43,7 @@ We plan to support more languages soon. If you use the Mend Renovate App then the badges are enabled automatically. -If you're self-hosting Renovate, you can enable the badges by adding the `mergeConfidence:all-badges` preset to the `extends` array in your Renovate config: +If you are self-hosting Renovate, you can enable the badges by adding the `mergeConfidence:all-badges` preset to the `extends` array in your Renovate config: ```json { @@ -68,8 +68,8 @@ If you want to disable the badges in the Mend Renovate App, add the `mergeConfid Merge Confidence uses the following confidence levels: - **Low**: We think the update contains breaking changes. Often this is expected because it's a `major` version update, but updates can have unknown breaking changes -- **Neutral**: We don't have enough data about the update, or we can't decide if the update should be Low or High confidence -- **High**: We rank updates as High confidence when the combination of `Age`, `Adoption` and `Passing` tests means there's a very low chance of breaking changes +- **Neutral**: We do not have enough data about the update, or we can not decide if the update should be Low or High confidence +- **High**: We rank updates as High confidence when the combination of `Age`, `Adoption` and `Passing` tests means there is a very low chance of breaking changes - **Very High**: We only use this for updates which are months old and have either high `Adoption` or have very high test `Passing` scores ## How it works @@ -81,7 +81,7 @@ This way we can find packages that have undeclared breaking changes. ### Algorithm The algorithm that decides on the values is private and is not something we plan to share. -Similar to a search engine's algorithm, we plan to adjust and improve it over time, for example by using historical data to set a baseline confidence level for packages. +Similar to a search engine algorithm, we plan to adjust and improve it over time, for example by using historical data to set a baseline confidence level for packages. ### Data @@ -97,8 +97,8 @@ This is why npm packages can only get the **High** Confidence badge when they ar ### Percentage values weighting The percentages for `Adoption` and `Passing` are weighted towards Organizations, private repositories, and projects with high test reliability. -This means those values aren't _raw_ percentages. +This means those values are not _raw_ percentages. ## Questions and feedback -You are invited to [start a discussion](https://github.com/renovatebot/renovate/discussions/new/choose) if you have anything you'd like to discuss. +You are invited to [start a discussion](https://github.com/renovatebot/renovate/discussions/new/choose) if you have anything you would like to discuss. diff --git a/docs/usage/modules/datasource/index.md b/docs/usage/modules/datasource/index.md index 63af0121af17d6..018f48a72e5b0e 100644 --- a/docs/usage/modules/datasource/index.md +++ b/docs/usage/modules/datasource/index.md @@ -7,7 +7,7 @@ title: Datasources After Renovate's manager scanned the files and extracted the dependencies, it assigns a `datasource` to each extracted package file or dependency. The `datasource` tells Renovate how to search for new versions. -You don't need to configure or override datasources. +You do not need to configure or override datasources. But you may use datasources in a `packageRules` array to configure Renovate's behavior, for example: ```json diff --git a/docs/usage/modules/manager/index.md b/docs/usage/modules/manager/index.md index 8cb9eeef2f9b52..7f56a26de46c59 100644 --- a/docs/usage/modules/manager/index.md +++ b/docs/usage/modules/manager/index.md @@ -48,10 +48,10 @@ If the default `fileMatch` regular expression for a manager does not match again #### Ignoring files that match the default fileMatch -Renovate will _extend_ the existing [`fileMatch`](../../configuration-options.md#filematch), meaning you don't need to include the default regular expressions like `Dockerfile` in your own array. +Renovate will _extend_ the existing [`fileMatch`](../../configuration-options.md#filematch), meaning you do not need to include the default regular expressions like `Dockerfile` in your own array. In other words, the regular expression are "additive". -If a manager matches a file that you _don't_ want it to, ignore it using the [`ignorePaths`](../../configuration-options.md#ignorepaths) configuration option. -Also, if you ever find that Renovate is _not_ matching a file name that you're certain it should, check your preset config isn't the cause of it. +If a manager matches a file that you _do not_ want it to, ignore it using the [`ignorePaths`](../../configuration-options.md#ignorepaths) configuration option. +Also, if you ever find that Renovate is _not_ matching a file name that you are certain it should, check your preset config is not the cause of it. The `config:recommended` preset ignores common test and example directory names, for example. ### Enabling and disabling managers @@ -59,7 +59,7 @@ The `config:recommended` preset ignores common test and example directory names, #### Enabling experimental managers Most managers are enabled by default. -For those that aren't, typically because they are considered experimental, you can opt in manually. +For those that are not, typically because they are considered experimental, you can opt in manually. If there was a manager called `some-new-manager` you would enable it like this: ```json @@ -84,7 +84,7 @@ Please check the [list of supported managers](#supported-managers). #### Limiting enabled managers -Say you only want to use Renovate for JavaScript packages, and to update your Dockerfile, and don't want any other updates. +Say you only want to use Renovate for JavaScript packages, and to update your Dockerfile, and do not want any other updates. You can use the `enabledManagers` array, to list the managers you want to use (`npm`, `dockerfile`): ```json diff --git a/docs/usage/modules/versioning.md b/docs/usage/modules/versioning.md index eab2373bcb1b40..95992d832d225e 100644 --- a/docs/usage/modules/versioning.md +++ b/docs/usage/modules/versioning.md @@ -11,20 +11,20 @@ For example, `npm` uses `1.0.0-beta.1` while `pip` uses `1.0.0b1`. ## Why you might need to manually configure versioning Renovate interprets versions correctly out-of-the-box most of the time. -But Renovate can't automatically detect **all** versioning schemes. +But Renovate can not automatically detect **all** versioning schemes. So sometimes you need to tell the bot what versioning scheme it should use. You can manually configure or override the `versioning` value for a particular dependency. -You generally won't need to override the defaults for ecosystems which enforce a strict version scheme like `npm`. +You generally do not need to override the defaults for ecosystems which enforce a strict version scheme like `npm`. Configuring or overriding the default `versioning` can be extra helpful for ecosystems like Docker, Kubernetes or Helm, where versioning is barely a "convention". ## General concepts behind overriding versioning -- Although you can reconfigure versioning per-manager or per-datasource, you probably don't need such a broad change +- Although you can reconfigure versioning per-manager or per-datasource, you probably do not need such a broad change - More commonly you would need to configure `versioning` for individual packages or potentially package patterns - The best way to do this is with `packageRules`, with a combination of `matchManagers`, `matchDatasources`, `matchPackageNames` and `matchPackagePatterns`. - Avoid configuring `versioning` in a rule that also uses `matchUpdateTypes`, as the update types aren't known at the time the `versioning` is applied + Avoid configuring `versioning` in a rule that also uses `matchUpdateTypes`, as the update types are not known at the time the `versioning` is applied ## Examples of versioning overrides diff --git a/docs/usage/node.md b/docs/usage/node.md index 5543401526bb21..e37178a5f708c0 100644 --- a/docs/usage/node.md +++ b/docs/usage/node.md @@ -6,7 +6,7 @@ description: Node.js versions support in Renovate # Node.js Versions Renovate can upgrade the [Node.js](https://nodejs.org/en/) runtime used by your project. -This way you're using the latest bug fixes, performance improvements, security mitigations, etc. +This way you are using the latest bug fixes, performance improvements, security mitigations, etc. ## LTS codenames diff --git a/docs/usage/noise-reduction.md b/docs/usage/noise-reduction.md index 3ccb1c09fbb650..d696c618b48337 100644 --- a/docs/usage/noise-reduction.md +++ b/docs/usage/noise-reduction.md @@ -7,7 +7,7 @@ description: How to reduce the "noise" associated with module updates 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'll get a lot of PRs and related notifications. +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 approach. Of course, please keep in mind that people's definitions of "noise" may differ. @@ -43,14 +43,14 @@ By setting `matchPackagePatterns` to "eslint", it means that any package with ES ### Be smart about grouping dependencies Grouping dependencies _may_ help you, but can also cause problems. -Sometimes you're better off getting a single PR per dependency! +Sometimes you are better off getting a single PR per dependency! Grouping dependencies versus single PRs: - Grouping dependencies increases the chance that the branch has an error ("break" your build) - When you upgrade multiple dependencies in one PR, it takes longer to find out which package broke the build -- If a group PR "breaks", you'll have to wait upgrading your other dependencies until _all_ updates in the PR pass -- You'll have less flexibility when one (or more) dependencies in the group have a major upgrade, but the other dependencies are good to go +- If a group PR "breaks", you will have to wait upgrading your other dependencies until _all_ updates in the PR pass +- You will have less flexibility when one (or more) dependencies in the group have a major upgrade, but the other dependencies are good to go ## Scheduling Renovate @@ -75,17 +75,17 @@ There are multiple reasons why Renovate may need to "recreate" PRs after you mer 1. Conflict with lock files (often) 1. If you have configured Renovate or GitHub that PRs must always be kept up-to-date with the base branch -Any of the above reasons can lead to a Renovate branch being considered "stale" and then Renovate needs to rebase it off the base branch before you can test and merge again, and Renovate won't do this until it's back in schedule. +Any of the above reasons can lead to a Renovate branch being considered "stale" and then Renovate needs to rebase it off the base branch before you can test and merge again, and Renovate will not do this until it's back in schedule. ### Selective scheduling -Don't think that you need to apply blanket rules to scheduling. +Do not think that you need to apply blanket rules to scheduling. Remember that Renovate's configuration is highly flexible, so you can configure `automerge` anywhere from globally (entire repo) right down to a package/upgrade type level. You could even configure a nonsensical rule like: "patch updates of `jquery` are for Mondays only". Remember our example of grouping all `eslint` packages? -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? +If you think about it, updates to `eslint` rules do not exactly need to be applied in real time! +You do not want to get too far behind, so how about we update `eslint` packages only once a month? ```json title="Update ESLint packages once a month" { @@ -113,7 +113,7 @@ Or perhaps at least weekly: } ``` -If you're wondering what is supported and not, under the hood, the schedule is parsed using [@breejs/later](https://github.com/breejs/later) using the `later.parse.text(scheduleString)` API. +If you are wondering what is supported and not, under the hood, the schedule is parsed using [@breejs/later](https://github.com/breejs/later) using the `later.parse.text(scheduleString)` API. Read the parser documentation at [breejs.github.io/later/parsers.html#text](https://breejs.github.io/later/parsers.html#text). Renovate does not support scheduled minutes or "at an exact time" granularity. Granularity must be at least one hour. @@ -124,7 +124,7 @@ Automerging is a Renovate feature that can save you a lot of time/noise directly In short: it means that Renovate can merge PRs or even branches itself if they pass your tests. We recommend that you enable automerge for any type of dependency update where you would select 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. +We all know that there are some types of updates that we (nearly) always verify manually before merging, and plenty of others that we do not bother looking at unless tests fail. Every time you select Merge on a Renovate PR without manually testing it, you should consider if you can enable automerge and save yourself the time in the future. Automerge works particularly well for `devDependencies` and for production `dependencies` that have great test coverage. @@ -135,7 +135,7 @@ If you have an API with 100% test coverage and `express` is updated: automerge i ### Branch automerging -Those of you familiar with GitHub might note that even if you automerge PRs, you're still going to get notifications (noise) anyway - one when the PR is created and another when it is merged. +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 diff --git a/docs/usage/nuget.md b/docs/usage/nuget.md index fdce327a595164..48d424d2d43037 100644 --- a/docs/usage/nuget.md +++ b/docs/usage/nuget.md @@ -57,7 +57,7 @@ You can set alternative feeds: } ``` -In the example above we've set three NuGet feeds. +In the example above we have set three NuGet feeds. The package resolving process uses the `merge` strategy to handle the three feeds. All feeds are checked for dependency updates, and duplicate updates are merged into a single dependency update. @@ -107,7 +107,7 @@ Credentials for authenticated/private feeds can be given via host rules in the c } ``` -If you're using Azure DevOps, you can set `matchHost` to `pkgs.dev.azure.com`. +If you are using Azure DevOps, you can set `matchHost` to `pkgs.dev.azure.com`. !!! note diff --git a/docs/usage/php.md b/docs/usage/php.md index e74d968b5061f1..358d14c0143981 100644 --- a/docs/usage/php.md +++ b/docs/usage/php.md @@ -21,7 +21,7 @@ Either install the [Renovate App](https://github.com/apps/renovate) on GitHub, o ## Private packages -If you're using a [privately hosted Composer package](https://getcomposer.org/doc/articles/authentication-for-private-packages.md) you can pass the credentials via the [`hostRules`](./configuration-options.md#hostrules) configuration. +If you are using a [privately hosted Composer package](https://getcomposer.org/doc/articles/authentication-for-private-packages.md) you can pass the credentials via the [`hostRules`](./configuration-options.md#hostrules) configuration. ```json { @@ -42,7 +42,7 @@ If you're using a [privately hosted Composer package](https://getcomposer.org/do ``` 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're using the Mend Renovate App then you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. +If you are using the Mend Renovate App then you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. Go to [https://app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt), paste in the secret string you wish to encrypt, select _Encrypt_, then copy the encrypted result. You may encrypt your `password` only, but you can encrypt your `username` as well. diff --git a/docs/usage/python.md b/docs/usage/python.md index 5213442cbe6663..d8f8f7007227e3 100644 --- a/docs/usage/python.md +++ b/docs/usage/python.md @@ -10,7 +10,7 @@ See [all supported managers](./modules/manager/index.md). ## Versioning support -We've written a JavaScript version of the [PEP440 specification](https://www.python.org/dev/peps/pep-0440/), so we can use it in Renovate bot. +We have written a JavaScript version of the [PEP440 specification](https://www.python.org/dev/peps/pep-0440/), so we can use it in Renovate bot. You can find this project in our [`renovatebot/pep440` repository](https://github.com/renovatebot/pep440). Our PEP440 implementation supports pinned versions and ranges. diff --git a/docs/usage/reading-list.md b/docs/usage/reading-list.md index ff9dd4fdb299c3..f9d103874ec3fb 100644 --- a/docs/usage/reading-list.md +++ b/docs/usage/reading-list.md @@ -15,11 +15,11 @@ We created reading lists for these types of users: - Advanced Start with the "Beginners" reading list. -If you're self-hosting or need to update private packages, complete the relevant reading lists for those. +If you are self-hosting or need to update private packages, complete the relevant reading lists for those. -## I don't know where to start +## I do not know where to start -If you're new to Renovate, you should: +If you are new to Renovate, you should: - Use the Mend Renovate App, or let someone else host Renovate for you - Stick with the `config:recommended` preset @@ -65,7 +65,7 @@ Then read: ## Self-hosting Renovate -If you're going to self-host Renovate then read: +If you are going to self-host Renovate then read: - [Running Renovate](./getting-started/running.md) - [Self-hosting examples](./examples/self-hosting.md) diff --git a/docs/usage/ruby.md b/docs/usage/ruby.md index 133d8d5dc51613..f05fd44ea5f07e 100644 --- a/docs/usage/ruby.md +++ b/docs/usage/ruby.md @@ -18,8 +18,8 @@ Renovate supports upgrading dependencies in Bundler's Gemfiles and associated `G When using `"rangeStrategy": "update-lockfile"`, all gems listed in the `Gemfile` will be updated, even if they do not have a version specified. -When using other `rangeStrategy` options, Renovate doesn't update dependencies without a version constraint. -Example: `gem 'some-gem', '~> 1.2.3'` will update `some-gem` if a new version matching the constraint is available, but `gem 'some-gem'` won't. +When using other `rangeStrategy` options, Renovate does not update dependencies without a version constraint. +Example: `gem 'some-gem', '~> 1.2.3'` will update `some-gem` if a new version matching the constraint is available, but `gem 'some-gem'` does not. If you always want to have the latest available version, consider specifying `gem 'some-gem', '> 0'`. ## Enabling diff --git a/docs/usage/rust.md b/docs/usage/rust.md index 594abea989aab8..4fb978be30b26b 100644 --- a/docs/usage/rust.md +++ b/docs/usage/rust.md @@ -34,7 +34,7 @@ Read the [Rust environment variables docs](https://doc.rust-lang.org/cargo/refer You as user can set authentication for private crates by adding a `hostRules` configuration to your `renovate.json` file. All token `hostRules` with a `hostType` (e.g. `github`, `gitlab`, `bitbucket`, etc.) and host rules without a `hostType` will be automatically setup for authentication. -You can also configure a `hostRules` that's only for Cargo authentication (e.g. `hostType: 'cargo'`). +You can also configure a `hostRules` that is only for Cargo authentication (e.g. `hostType: 'cargo'`). ```js title="Example of authentication for a private GitHub and Cargo registry:" module.exports = { diff --git a/docs/usage/security-and-permissions.md b/docs/usage/security-and-permissions.md index 00632af88d7a48..87eab0e83f2040 100644 --- a/docs/usage/security-and-permissions.md +++ b/docs/usage/security-and-permissions.md @@ -63,7 +63,7 @@ Self-hosted Renovate does not send or submit any package data to Mend for the pu According to a strict definition, Renovate may "send data" to third-party registries and source code hosts directly to look up new releases. For example, if you have an `npm` package and do not configure a private registry then Renovate will query URLs on `https://registry.npmjs.org` including names of packages used in your repositories. You could avoid this by configuring private registries but such registries need to query public registries anyway. -We don't know of any public registries which reverse lookup IP addresses to associate companies with packages. +We do not know of any public registries which reverse lookup IP addresses to associate companies with packages. ### Hosted/SaaS (the Mend Renovate App) diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index b09bf4af5f8a71..dffc58c471f0cd 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -93,7 +93,7 @@ If you use an environment variable or the CLI to set the value for `autodiscover Commas will be used as delimiter for a new filter. ``` -# DO NOT use commas inside the filter if you're using env or cli variables to configure it. +# DO NOT use commas inside the filter if you are using env or cli variables to configure it. RENOVATE_AUTODISCOVER_FILTER="/MyOrg/{my-repo,foo-repo}" @@ -124,7 +124,7 @@ All text inside the start and end `/` will be treated as a regular expression. ``` You can negate the regex by putting an `!` in front. -Only use a single negation and don't mix with other filters because all filters are combined with `or`. +Only use a single negation and do not mix with other filters because all filters are combined with `or`. If using negations, all repositories except those who match the regex are added to the result: ```json @@ -193,9 +193,9 @@ Renovate supports four possible ways to access those tools: - `hermit`: Uses the [Hermit](https://github.com/cashapp/hermit) tool installation approach. Starting in v36, Renovate's default Docker image (previously referred to as the "slim" image) uses `binarySource=install` while the "full" Docker image uses `binarySource=global`. -If you're running Renovate in an environment where runtime download and install of tools is not possible then you should use the "full" image. +If you are running Renovate in an environment where runtime download and install of tools is not possible then you should use the "full" image. -If you're building your own Renovate image, e.g. by installing Renovate using `npm`, then you'll need to ensure that all necessary tools are installed globally before running Renovate so that `binarySource=global` will work. +If you are building your own Renovate image, e.g. by installing Renovate using `npm`, then you will need to ensure that all necessary tools are installed globally before running Renovate so that `binarySource=global` will work. The `binarySource=docker` approach should not be necessary in most cases now and `binarySource=install` is recommended instead. If you have a use case where you cannot use `binarySource=install` but can use `binarySource=docker` then please share it in a GitHub Discussion so that the maintainers can understand it. @@ -265,7 +265,7 @@ This configuration will be applied after all other environment variables, so you The purpose of this config option is to allow you (as a bot admin) to configure manager-specific files such as a global `.npmrc` file, instead of configuring it in Renovate config. -This config option is disabled by default because it may prove surprising or undesirable for some users who don't expect Renovate to go into their home directory and import registry or credential information. +This config option is disabled by default because it may prove surprising or undesirable for some users who do not expect Renovate to go into their home directory and import registry or credential information. Currently, this config option is supported for the `npm` manager only - specifically the `~/.npmrc` file. If found, it will be imported into `config.npmrc` with `config.npmrcMerge` set to `true`. @@ -285,7 +285,7 @@ Periods (`.`) in host names must be replaced with a single underscore (`_`). !!! note - You can't use these prefixes with the `detectHostRulesFromEnv` config option: `npm_config_`, `npm_lifecycle_`, `npm_package_`. + You can not use these prefixes with the `detectHostRulesFromEnv` config option: `npm_config_`, `npm_lifecycle_`, `npm_package_`. In addition, platform host rules will only be picked up when `matchHost` is supplied. ### npmjs registry token example @@ -410,7 +410,7 @@ Set this to `1001:1002` to use UID 1001 and GID 1002. If you use `binarySource=docker|install` read the section below. -If you need to change the Docker user please make sure to use the root (`0`) group, otherwise you'll get in trouble with missing file and directory permissions. +If you need to change the Docker user please make sure to use the root (`0`) group, otherwise you will get in trouble with missing file and directory permissions. Like this: ``` @@ -470,9 +470,9 @@ This configuration option lets you choose an organization you want repositories It must be set to a GitHub Organization name and not a GitHub user account. When set, "allow edits by maintainers" will be false for PRs because GitHub does not allow this setting for organizations. -This can be used if you're migrating from user-based forks to organization-based forks. +This can be used if you are migrating from user-based forks to organization-based forks. -If you've set a `forkOrg` then Renovate will: +If you have set a `forkOrg` then Renovate will: 1. Check if a fork exists in the preferred organization before checking it exists in the fork user's account 1. If no fork exists: it will be created in the `forkOrg`, not the user account @@ -500,12 +500,12 @@ Replace the newlines with `\n` before adding the resulting single-line value to !!! note - The private key can't be protected with a passphrase if running in a headless environment. Renovate will not be able to handle entering the passphrase. + The private key can not be protected with a passphrase if running in a headless environment. Renovate will not be able to handle entering the passphrase. It will be loaded _lazily_. Before the first commit in a repository, Renovate will: -1. Run `gpg import` (if you haven't before) +1. Run `gpg import` (if you have not before) 1. Run `git config user.signingkey` and `git config commit.gpgsign true` The `git` commands are run locally in the cloned repo instead of globally. @@ -530,7 +530,7 @@ Possible values: By default, Renovate logs and displays a warning when the `GITHUB_COM_TOKEN` is not set. By setting `githubTokenWarn` to `false`, Renovate suppresses these warnings on Pull Requests, etc. -Disabling the warning is helpful for self-hosted environments that can't access the `github.com` domain, because the warning is useless in these environments. +Disabling the warning is helpful for self-hosted environments that can not access the `github.com` domain, because the warning is useless in these environments. ## globalExtends @@ -541,7 +541,7 @@ Use the `extends` field instead of this if, for example, you need the ability fo !!! warning - `globalExtends` presets can't be private. + `globalExtends` presets can not be private. When Renovate resolves `globalExtends` it does not fully process the configuration. This means that Renovate does not have the authentication it needs to fetch private things. @@ -580,13 +580,13 @@ In the above example any reference to the `@company` preset will be replaced wit !!! tip - Combine `migratePresets` with `configMigration` if you'd like your config migrated by PR. + Combine `migratePresets` with `configMigration` if you would like your config migrated by PR. ## onboarding Only set this to `false` if all three statements are true: -- You've configured Renovate entirely on the bot side (e.g. empty `renovate.json` in repositories) +- You have configured Renovate entirely on the bot side (e.g. empty `renovate.json` in repositories) - You want to run Renovate on every repository the bot has access to - You want to skip all onboarding PRs @@ -596,8 +596,8 @@ Only set this to `false` if all three statements are true: !!! note 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. +For example, if you configure `branchPrefix` to be `renovate-` then you would 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 will get onboarding PRs for repositories that had previously closed the onboarding PR unmerged. ## onboardingCommitMessage @@ -672,7 +672,7 @@ TTL is 15 minutes by default, and it is adjustable in [cacheTtlOverride](#cachet !!! warning - Doing so improves efficiency because shared presets don't need to be reloaded/resolved for every repository, however it also means that private presets can be "leaked" between repositories. + Doing so improves efficiency because shared presets do not need to be reloaded/resolved for every repository, however it also means that private presets can be "leaked" between repositories. You should only enable this when all repositories are trusted, such as a corporate environment. ## privateKey @@ -751,14 +751,14 @@ Instead, with scoped secrets it means that Renovate ensures that the organizatio !!! note You could use public key encryption with earlier versions of Renovate. We deprecated this approach and removed the documentation for it. - If you're _still_ using public key encryption then we recommend that you use private keys instead. + If you are _still_ using public key encryption then we recommend that you use private keys instead. ## privateKeyOld Use this field if you need to perform a "key rotation" and support more than one keypair at a time. Decryption with this key will be tried after `privateKey`. -If you're migrating from the legacy public key encryption approach to use GPG, then move your legacy private key from `privateKey` to `privateKeyOld` and then put your new GPG private key in `privateKey`. +If you are migrating from the legacy public key encryption approach to use GPG, then move your legacy private key from `privateKey` to `privateKeyOld` and then put your new GPG private key in `privateKey`. Doing so will mean that Renovate will first try to decrypt using the GPG key but fall back to the legacy key and try that next. You can remove the `privateKeyOld` config option once all the old encrypted values have been migrated, or if you no longer want to support the old key and let the processing of repositories fail. @@ -831,7 +831,7 @@ JSON files will be stored inside the `cacheDir` beside the existing file-based p !!! tip - If you're storing the repository cache on Amazon S3 then you may set a folder hierarchy as part of `repositoryCacheType`. + If you are storing the repository cache on Amazon S3 then you may set a folder hierarchy as part of `repositoryCacheType`. For example, `repositoryCacheType: 's3://bucket-name/dir1/.../dirN/'`. @@ -920,7 +920,7 @@ You may need to set a `username` if you: - use the Bitbucket platform, or - use a self-hosted GitHub App with CLI (required) -If you're using a Personal Access Token (PAT) to authenticate then you should not set a `username`. +If you are using a Personal Access Token (PAT) to authenticate then you should not set a `username`. ## writeDiscoveredRepos diff --git a/docs/usage/self-hosted-experimental.md b/docs/usage/self-hosted-experimental.md index a86c2acbbe78ed..05fd771b4d3310 100644 --- a/docs/usage/self-hosted-experimental.md +++ b/docs/usage/self-hosted-experimental.md @@ -26,7 +26,7 @@ If set to any integer, Renovate will use this integer instead of the default npm ## `RENOVATE_EXPERIMENTAL_NO_MAVEN_POM_CHECK` If set to any value, Renovate will skip its default artifacts filter check in the Maven datasource. -Skipping the check will speed things up, but may result in versions being returned which don't properly exist on the server. +Skipping the check will speed things up, but may result in versions being returned which do not properly exist on the server. ## `RENOVATE_PAGINATE_ALL` @@ -104,7 +104,7 @@ Default value: `5` (attempts results in max. 13.75 seconds timeout). Adjust default time (in milliseconds) given to GitLab to create pipelines for a commit pushed by Renovate. -Can be useful for slow-running, self-hosted GitLab instances that don't react fast enough for the default delay to help. +Can be useful for slow-running, self-hosted GitLab instances that do not react fast enough for the default delay to help. Default value: `1000` (milliseconds). diff --git a/docs/usage/semantic-commits.md b/docs/usage/semantic-commits.md index 781d30a5070fd8..9455fce2ba253b 100644 --- a/docs/usage/semantic-commits.md +++ b/docs/usage/semantic-commits.md @@ -65,7 +65,7 @@ For example: ## Changing the Semantic Commit scope -You can set your own word for the scope if you don't like the default "deps" scope. +You can set your own word for the scope if you do not like the default "deps" scope. For example, to set the scope to "package", add the preset `":semanticCommitScope(package)"` to your `extends` array: ```json diff --git a/docs/usage/templates.md b/docs/usage/templates.md index f355135754ea02..7d942f1a00f453 100644 --- a/docs/usage/templates.md +++ b/docs/usage/templates.md @@ -117,6 +117,6 @@ This is for security reasons. `HOME is {{env.HOME}}` -If you're self-hosting Renovate, you can expose more variables with the [`customEnvVariables`](./self-hosted-configuration.md#customenvvariables) config option. +If you are self-hosting Renovate, you can expose more variables with the [`customEnvVariables`](./self-hosted-configuration.md#customenvvariables) config option. You can also use the [`exposeAllEnv`](./self-hosted-configuration.md#exposeallenv) config option to allow all environment variables in templates, but make sure to consider the security implications of giving the scripts unrestricted access to all variables. diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md index b41bcc3d9469d4..7293d01bae6a18 100644 --- a/docs/usage/troubleshooting.md +++ b/docs/usage/troubleshooting.md @@ -5,19 +5,19 @@ Learn how to troubleshoot problems with Renovate, where to find the logging outp ## Getting the logs Renovate's debug-level logs are usually enough to help troubleshoot most problems. -Where you can find the logs depends on how you're running Renovate. +Where you can find the logs depends on how you are running Renovate. ### The Mend Renovate App Each pull request from the Mend Renovate App has a link to the [Mend Developer Portal](https://developer.mend.io/) in the PR body text. -The text you're looking for is: +The text you are looking for is: > This PR has been generated by Mend Renovate. View repository job log here. Select the blue text "here" to go to the Recent jobs page in the [Mend Developer Portal](https://developer.mend.io/). Sign in with your GitHub account. -Once you're logged in, you can see the logs for the Renovate jobs on your repository. +Once you are logged in, you can see the logs for the Renovate jobs on your repository. You should have access to any repository which you have write access to and which has Renovate installed. Renovate only provides the 10 most recent logs for each repository. @@ -63,9 +63,9 @@ If none of these steps have helped you, then create a new discussion post to get Please locate the relevant parts of the logs as described earlier before asking for help or posting a bug report. Do not expect the Renovate maintainers to read through the full logs when trying to help you, as that takes a lot of time on our part. -If later it turns out that the full logs are necessary, you'll be asked for them then. +If later it turns out that the full logs are necessary, you will be asked for them then. ## Validating configuration changes -Sometimes you'll have to change your Renovate configuration to solve a problem. +Sometimes you will have to change your Renovate configuration to solve a problem. The [`renovate-config-validator` program](config-validation.md) helps validate such configuration changes without committing them to your repository. diff --git a/docs/usage/updating-rebasing.md b/docs/usage/updating-rebasing.md index 9f79dfeda1bf9f..58d93f1e08fc75 100644 --- a/docs/usage/updating-rebasing.md +++ b/docs/usage/updating-rebasing.md @@ -21,7 +21,7 @@ Instead, Renovate reapplies all updates into a new commit based off of the head ## No rebasing if you have made edits -First of all, here is the one time when Renovate _won't_ update branches. +First of all, here is the one time when Renovate _will not_ update branches. If you push a new commit to a Renovate branch, for example to fix your code so the tests pass, then Renovate stops 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 over again. @@ -64,6 +64,6 @@ The label name is configurable via the `rebaseLabel` option. If you apply a rebase label then Renovate will regenerate its commit for the branch, even if the branch has been modified. The rebase label is useful in situations like: -- If a branch is behind the base branch, but you don't have `rebaseWhen=behind-base-branch` enabled +- If a branch is behind the base branch, but you do not have `rebaseWhen=behind-base-branch` enabled - If a branch has been edited, and you want to discard the edits and have Renovate create it again - If a branch was created with an error (e.g. lockfile generation) and you want Renovate to try again diff --git a/docs/usage/upgrade-best-practices.md b/docs/usage/upgrade-best-practices.md index 5b3ae4697cf225..7852653ef9766d 100644 --- a/docs/usage/upgrade-best-practices.md +++ b/docs/usage/upgrade-best-practices.md @@ -2,7 +2,7 @@ This page explains what we (the Renovate maintainers) recommend you do to update your dependencies. -We'll cover starting a new project, updating a year-old project, and updating a project with dependencies that are five years old. +We will cover starting a new project, updating a year-old project, and updating a project with dependencies that are five years old. We explain why you should update often, and how to nudge your team to update their dependencies. ## General recommendations @@ -32,7 +32,7 @@ You should extend from the `config:best-practices` preset: } ``` -If you're using `config:recommended` now, replace it with `config:best-practices`: +If you are using `config:recommended` now, replace it with `config:best-practices`: ```diff - "extends": ["config:recommended"] @@ -62,7 +62,7 @@ The next sections explain each part of the preset. Renovate creates a config migration PR to replace old config option names with their new replacements. This way your configuration file and the Renovate docs always use the same terms. -You'll get config migration PRs no matter _how_ you run Renovate: self-hosting or the Mend Renovate app. +You will get config migration PRs no matter _how_ you run Renovate: self-hosting or the Mend Renovate app. #### Extends `config:recommended` @@ -95,35 +95,35 @@ But updating regularly actually _saves_ you time, because: - Regular updates tend to be small - Applying `major` updates is easier -- You'll be ready for CVE patches -- You'll look for ways to automate the updates +- You will be ready for CVE patches +- You will look for ways to automate the updates #### Regular updates tend to be small Firstly, when you update regularly updates tend to be small. The update's changelogs are small, quick to read, and easy to understand. You probably only need to make changes in a few places (if at all) to merge the PR and get going again. -Because you're reading the changelogs regularly, you'll get a feel for the direction of the upstream project. +Because you are reading the changelogs regularly, you will get a feel for the direction of the upstream project. #### Applying `major` updates is easier -Secondly, when you're current with upstream, `major` updates are easier. +Secondly, when you are current with upstream, `major` updates are easier. This is because you already: - follow the latest best practices of upstream - use the latest names for features/variables - read the previous changelogs -#### You'll be ready for CVE patches +#### You will be ready for CVE patches -Thirdly, you'll be ready when an upstream package releases a patch for a critical CVE. -If you're current, you can review and merge Renovate's PR quickly. +Thirdly, you will be ready when an upstream package releases a patch for a critical CVE. +If you are current, you can review and merge Renovate's PR quickly. -When you're behind on updates, you'll have a bad time, because you must read _more_ changelogs and make _more_ changes before you can merge the critical patch. +When you are behind on updates, you will have a bad time, because you must read _more_ changelogs and make _more_ changes before you can merge the critical patch. -#### You'll look for ways to automate the updates +#### You will look for ways to automate the updates -Finally, when you're updating often, you'll start looking for ways to automate the updates. +Finally, when you are updating often, you will start looking for ways to automate the updates. You may start to [`automerge`](./configuration-options.md#automerge) development dependencies like Prettier, or ESLint when the linter passes. Or you may decide to automerge any `patch` type upgrades, by using the [`default:automergePatch`](./presets-default.md#automergepatch) preset. @@ -132,22 +132,22 @@ Renovate does not support GitLab's Merge Trains, see [issue #5573](https://githu ## Starting from a new project -Let's assume you're starting a new project. +Let's assume you are starting a new project. You created a new Git repository, installed the latest frameworks, libraries and development tools. After pushing the initial commit, you should enable and onboard Renovate. -Now you'll have to stay on the "update often" train. +Now you will have to stay on the "update often" train. ## Project with dependencies that are a year old -If you have a project that's a year behind on dependencies, you'll need to do some work. +If you have a project that's a year behind on dependencies, you will need to do some work. Let's assume that most dependencies need a `patch` or `minor` update, and at _least_ one dependency needs a `major` update. Start small, and get the `patch` and `minor` updates first. Read the changelogs for your updates. You may have to make small changes to get things working again. -When you have the latest `patch` and `minor` versions, you're ready for `major` updates. +When you have the latest `patch` and `minor` versions, you are ready for `major` updates. Start with `major` version updates for tools like Prettier or ESLint. Then work on `major` updates for your framework or library. @@ -156,7 +156,7 @@ Let multiple team members review your work before merging, it's easy to miss som Finally, update your development tools. -Now you're up-to-date, you should think how to make updating a regular habit. +Now you are up-to-date, you should think how to make updating a regular habit. ## Project with dependencies that are five years old @@ -171,7 +171,7 @@ If your project is this badly behind on updates, you have two problems: Fix the easier problem first: getting back up to date. Update any dependencies that have critical updates for CVEs or other security related improvements. -If you're on the GitHub platform: follow the steps listed in the [`vulnerabilityAlerts`](./configuration-options.md#vulnerabilityalerts) docs to make sure Renovate is reading GitHub's Vulnerability Alerts. +If you are on the GitHub platform: follow the steps listed in the [`vulnerabilityAlerts`](./configuration-options.md#vulnerabilityalerts) docs to make sure Renovate is reading GitHub's Vulnerability Alerts. You may want to enable the experimental `osvVulnerabilityAlerts` config option, to get OSV-based vulnerability alerts for _direct_ dependencies. Read the [`osvVulnerabilityAlerts` config option docs](./configuration-options.md#osvvulnerabilityalerts) to learn more. @@ -189,9 +189,9 @@ Then update all dependencies to their latest `minor` or `patch` version, to prep ### Take `major` updates in sequence Take `major` updates in sequence. -This way you'll read the changelogs for each `major` version, and learn _why_ upstream made certain breaking changes. +This way you will read the changelogs for each `major` version, and learn _why_ upstream made certain breaking changes. -Say you're on version `1` of a dependency, and the latest `major` version is at `4`. +Say you are on version `1` of a dependency, and the latest `major` version is at `4`. You should update to `2`, then `3` and finally `4`. Avoid updating from `1` directly to `4`. @@ -203,7 +203,7 @@ Finally, update development tools like Prettier, ESLint, TSLint, Cypress, and so ### Improve the human side -You're done with the _technical_ side. +You are done with the _technical_ side. Now comes the harder part, fixing the _human_ side. There are probably a number of reasons why the project got this badly out of date. @@ -221,7 +221,7 @@ Some common reasons: - The test suite is slow - Releasing a new version of the project must be done by hand - Updating must be done by hand -- The company doesn't allow developer time for updates +- The company does not allow developer time for updates - The company has complex rules about updates If updating is painful, or takes a lot of time, developers tend to avoid it. @@ -241,7 +241,7 @@ Respect your developer's time and brains: - Building the project _must_ be as fast as possible - Have automated tests for the critical path of your project - Run the automated tests on _every_ pull request -- If you're on GitHub: use [GitHub's Merge Queue](./key-concepts/automerge.md#github-merge-queue) to speed up merges +- If you are on GitHub: use [GitHub's Merge Queue](./key-concepts/automerge.md#github-merge-queue) to speed up merges - Follow SemVer versioning - Use the [`semantic-release` bot](https://github.com/semantic-release/semantic-release) to automate the release process - Refactor existing code to make future changes easier diff --git a/docs/usage/user-stories/maintaining-aur-packages-with-renovate.md b/docs/usage/user-stories/maintaining-aur-packages-with-renovate.md index abdc119a870992..827354156ce583 100644 --- a/docs/usage/user-stories/maintaining-aur-packages-with-renovate.md +++ b/docs/usage/user-stories/maintaining-aur-packages-with-renovate.md @@ -20,7 +20,7 @@ title: Maintaining AUR packages with Renovate One big advantage that Arch Linux has over other distributions, apart from being able to say “BTW I use Arch.”, is the Arch User Repository (AUR). It’s a community-driven repository with over 80,000 packages. -If you’re looking for a package, chances are you'll find it in the AUR. +If you’re looking for a package, chances are you will find it in the AUR. Keeping all those packages up to date, takes a lot of manual effort by a lot of volunteers. People have created and used tools, like [`urlwatch`](https://github.com/thp/urlwatch) and [`aurpublish`](https://github.com/eli-schwartz/aurpublish), to let them know when upstream releases are cut and automate some parts of the process. From aaacc264d80d2c243dae69f5a2831b40214be79b Mon Sep 17 00:00:00 2001 From: Rhys Arkins Date: Tue, 7 May 2024 06:59:45 +0200 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> --- docs/development/new-package-manager-template.md | 2 +- docs/usage/config-presets.md | 2 +- docs/usage/examples/self-hosting.md | 2 +- docs/usage/golang.md | 2 +- docs/usage/known-limitations.md | 2 +- docs/usage/self-hosted-configuration.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/development/new-package-manager-template.md b/docs/development/new-package-manager-template.md index 2bb1f202b966ad..e5a07aabda79d5 100644 --- a/docs/development/new-package-manager-template.md +++ b/docs/development/new-package-manager-template.md @@ -2,7 +2,7 @@ Did you read our documentation on adding a package manager? -- [ ] I have read the [adding a package manager](adding-a-package-manager.md) documentation. +- [ ] I read the [adding a package manager](adding-a-package-manager.md) documentation. ## Basics diff --git a/docs/usage/config-presets.md b/docs/usage/config-presets.md index 7c764426e610ac..84135298e0bc6d 100644 --- a/docs/usage/config-presets.md +++ b/docs/usage/config-presets.md @@ -94,7 +94,7 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c !!! tip - You ca not combine the path and sub-preset syntaxes. + You can not combine the path and sub-preset syntaxes. This means that anything in the form `provider>owner/repo//path/to/file:subsubpreset` is not supported. One workaround is to use distinct files instead of sub-presets. diff --git a/docs/usage/examples/self-hosting.md b/docs/usage/examples/self-hosting.md index 34f9b3dd8b0582..5e302b9846cd90 100644 --- a/docs/usage/examples/self-hosting.md +++ b/docs/usage/examples/self-hosting.md @@ -416,7 +416,7 @@ This means Renovate can safely connect to systems using that certificate or cert Helper programs like Git and npm use the system trust store. For those programs to trust a self-signed certificate you must add it to the systems trust store. -On Ubuntu/Debian and many Linux-based systems, this can be done by copying the self-signed certificate (e.g. `self-signed-certificate.crt`) to `/usr/local/share/ca-certificates/` and running [`update-ca-certificates`](https://manpages.ubuntu.com/manpages/xenial/man8/update-ca-certificates.8.html) to update the system trust store afterward. +On Ubuntu/Debian and many Linux-based systems, this can be done by copying the self-signed certificate (e.g. `self-signed-certificate.crt`) to `/usr/local/share/ca-certificates/` and running [`update-ca-certificates`](https://manpages.ubuntu.com/manpages/xenial/man8/update-ca-certificates.8.html) to update the system trust store afterwards. ### Renovate Docker image diff --git a/docs/usage/golang.md b/docs/usage/golang.md index ae52031c8829ae..17e504282f3a32 100644 --- a/docs/usage/golang.md +++ b/docs/usage/golang.md @@ -38,7 +38,7 @@ To install Renovate Bot itself, either enable the [Renovate App](https://github. ### Replace massaging -Renovate can massage `replace` statements it finds prior to running `go` commands, and then massage them back afterward. +Renovate can massage `replace` statements it finds prior to running `go` commands, and then massage them back afterwards. This capability was added - and originally default behavior - because relative `replace` statements outside the current repo will not work when Renovate clones the repo locally. On the other hand, this massaging of `replace` statements may lead to unexpected results, especially because `go mod tidy` may not fully tidy the `go.sum` if it is missing the `replace` directives in `go.mod`. diff --git a/docs/usage/known-limitations.md b/docs/usage/known-limitations.md index df2a728ea844bb..908480fab3a5e0 100644 --- a/docs/usage/known-limitations.md +++ b/docs/usage/known-limitations.md @@ -8,7 +8,7 @@ Renovate, like any computer program has limitations. Sometimes these are functionality limitations - perhaps something is impossible or too complex to do, or we simply have not implemented it yet. At other times it may be a "performance" limitation, because jobs neither start nor complete instantly, even if the user may start with that expectation. -This document tries to list out the most commonly seen limitations and describe whether they are permanent and if there is any plans to improving the situation. +This document lists some common limitations, describes whether they are permanent and if there are any plans to improve the situation. ## Time/schedule based limitations diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index 9543da9e1c0101..21d1c8e941c292 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -632,7 +632,7 @@ Use the `extends` field instead of this if, for example, you need the ability fo !!! warning - `globalExtends` presets can not be private. + `globalExtends` presets must be public. When Renovate resolves `globalExtends` it does not fully process the configuration. This means that Renovate does not have the authentication it needs to fetch private things. From 2e8e030be7473d6c00cf5c61182766e68be59997 Mon Sep 17 00:00:00 2001 From: Rhys Arkins Date: Tue, 7 May 2024 07:01:30 +0200 Subject: [PATCH 9/9] Update docs/usage/configuration-options.md Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> --- docs/usage/configuration-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index e9af42d0cfc2f6..7dc419a3b9185a 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -82,7 +82,7 @@ With the above config: ## additionalBranchPrefix By default, the value for this config option is an empty string. -Normally you d not need to set this config option. +Normally you do not need to set this config option. Here's an example where `additionalBranchPrefix` can help you. Say you are using a monorepo and want to split pull requests based on the location of the package definition, so that individual teams can manage their own Renovate pull requests.