diff --git a/docs/development/adding-a-package-manager.md b/docs/development/adding-a-package-manager.md index 75ee581750e8b5..5b280da7303b8c 100644 --- a/docs/development/adding-a-package-manager.md +++ b/docs/development/adding-a-package-manager.md @@ -38,20 +38,20 @@ 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 -- dependency type (dependencies, devDependencies, etc) +- dependency type (dependencies, devDependencies, etc.) - 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. @@ -102,7 +102,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 3b1e3f265e085a..efd62bf0018735 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. 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 1e420b232ed7e8..2c07e0555081b4 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 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. 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. @@ -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`. @@ -83,14 +83,14 @@ 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. +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 @@ -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..d0bee9219062a3 100644 --- a/docs/development/help-us-help-you.md +++ b/docs/development/help-us-help-you.md @@ -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 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 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 e294b2745eddf0..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. @@ -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. @@ -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 e5cb889a2a811c..9bf2b48981f3ee 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 @@ -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,7 +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` -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. +You will configure the token properly a little later, so keep reading. You only need to do these steps once. @@ -111,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. @@ -132,9 +133,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. @@ -157,7 +158,7 @@ e.g. `pnpm jest composer -u` would update the saved snapshots for _all_ tests in ### 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. @@ -169,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 @@ -209,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 @@ -222,19 +223,17 @@ 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 -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 = { - 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 +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/development/minimal-reproductions.md b/docs/development/minimal-reproductions.md index 8ed9259f1a297e..e43e238cf9a6ed 100644 --- a/docs/development/minimal-reproductions.md +++ b/docs/development/minimal-reproductions.md @@ -58,7 +58,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: @@ -107,4 +107,4 @@ Then 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..e5a07aabda79d5 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 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 d3f6c4ca0f3683..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 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 12b33d82d9c94f..b9b5aef123de5c 100644 --- a/docs/development/triage-guide.md +++ b/docs/development/triage-guide.md @@ -13,7 +13,7 @@ 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. 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. @@ -23,7 +23,7 @@ Take the following steps on an incoming bug report: 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. 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. @@ -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 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 are 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) @@ -116,11 +116,11 @@ 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. -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 86fc86e3acd87f..f406b306913058 100644 --- a/docs/development/zod.md +++ b/docs/development/zod.md @@ -66,7 +66,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. @@ -99,7 +99,7 @@ const Box = z.object({ red: z.number(), green: z.number(), blue: z.number(), - }) + }), weight: z.number(), }); @@ -108,7 +108,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/bazel.md b/docs/usage/bazel.md index 4a95e19c55e2e1..e63054570e36cf 100644 --- a/docs/usage/bazel.md +++ b/docs/usage/bazel.md @@ -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 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/bot-comparison.md b/docs/usage/bot-comparison.md index fb49fdd802fc3b..d9ddc01fe66859 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,7 +161,7 @@ Learn more by reading the: 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` @@ -169,4 +169,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 2357a5a8cdf554..a29253b9438258 100644 --- a/docs/usage/config-presets.md +++ b/docs/usage/config-presets.md @@ -55,7 +55,7 @@ If you wish to have an alternative file name, you need to specify it (e.g. `gith | 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 @@ -67,7 +67,7 @@ If you wish to have an alternative file name, you need to specify it (e.g. `gith | 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 @@ -79,7 +79,7 @@ If you wish to have an alternative file name, you need to specify it (e.g. `gith | 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 @@ -92,11 +92,11 @@ If you wish to have an alternative file name, you need to specify it (e.g. `gith | 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 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. @@ -116,7 +116,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. @@ -128,8 +128,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: @@ -174,9 +174,9 @@ Or if you think your preset would be valuable for others, please contribute a PR 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: +- In other repos, reference it in an extends array like `github>owner/name`, for example: ```json { @@ -193,7 +193,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" @@ -201,7 +201,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"` @@ -279,7 +279,7 @@ If you are proposing a "monorepo" preset addition then it's OK to raise a PR dir ## 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 fc18c2a30051f6..c8e36accf30e39 100644 --- a/docs/usage/config-validation.md +++ b/docs/usage/config-validation.md @@ -45,7 +45,7 @@ $ npx --yes --package renovate -- renovate-config-validator --strict ### 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 @@ -65,7 +65,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: @@ -73,5 +73,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 90be5223c044b6..063df084f9de9e 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 do 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 @@ -207,13 +207,13 @@ 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! +If you do not select any status check, and you use platform automerge, then GitHub might automerge PRs with failing tests! ## automergeComment @@ -245,8 +245,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: @@ -259,7 +259,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 @@ -282,7 +282,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 @@ -330,8 +330,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 @@ -339,7 +339,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. @@ -363,19 +363,19 @@ 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) -- 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 +- 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 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 -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,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 recommend 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 @@ -425,14 +425,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. @@ -440,7 +440,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 @@ -514,7 +514,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. @@ -523,7 +523,7 @@ This can result in updated dependencies that are not compatible with your platfo To customize this behavior, 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 behavior. @@ -539,7 +539,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 @@ -550,7 +550,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`. @@ -576,13 +576,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 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 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 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 @@ -625,7 +625,7 @@ 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. Additionally, the "datasource" within Renovate must be capable of returning `constraints` values about each package's release. @@ -654,13 +654,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: @@ -683,7 +683,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: @@ -693,7 +693,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. @@ -971,7 +971,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: @@ -1209,10 +1209,10 @@ 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. -If you're self-hosting Renovate, you may download and edit the form, to use your own PGP public key. +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 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: @@ -1268,7 +1268,7 @@ Behavior: ## 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: @@ -1295,7 +1295,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 { @@ -1347,7 +1347,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: @@ -1360,7 +1360,7 @@ If you are running on any platform except `github.com`, you need to [configure a !!! 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 @@ -1374,12 +1374,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 { @@ -1402,7 +1402,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 use case is to follow a pre-release tag of a dependency, say TypeScripts's `"insiders"` build: +The main use case is to follow a pre-release tag of a dependency, say TypeScript's `"insiders"` build: ```json { @@ -1415,10 +1415,10 @@ The main use case 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 @@ -1440,7 +1440,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** @@ -1451,7 +1451,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** @@ -1469,7 +1469,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 @@ -1491,8 +1491,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: @@ -1505,7 +1505,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). @@ -1522,7 +1522,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 @@ -1571,7 +1571,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 @@ -1675,7 +1675,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: @@ -1723,7 +1723,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: @@ -1777,7 +1777,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 @@ -1870,7 +1870,7 @@ For example: ### 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 @@ -1924,10 +1924,10 @@ Supported artifactAuth and hostType combinations: 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. +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 { @@ -2007,15 +2007,15 @@ 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. ## 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 { @@ -2039,7 +2039,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: @@ -2069,7 +2069,7 @@ Setting this field to `true` in GitLab will also mean that all Issues will be fe ## 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 are extending a complex preset but do not want to use every "sub preset" that it includes. For example, consider this config: ```json @@ -2100,15 +2100,15 @@ 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. +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`). +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`. @@ -2127,14 +2127,14 @@ 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. ## 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 @@ -2158,10 +2158,10 @@ The setting `keepUpdatedLabel` is best used in this scenario: ## 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. +However, you can also fully override them on a per-package basis. Consider this example: @@ -2275,13 +2275,13 @@ 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. 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. @@ -2347,7 +2347,7 @@ It also does not prune/close any which already exist. ## 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 @@ -2416,7 +2416,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 @@ -2434,7 +2434,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 { @@ -2448,7 +2448,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 { @@ -2555,7 +2555,7 @@ Instead you should do `> 13 months`. ### 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 @@ -3068,7 +3068,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. @@ -3123,12 +3123,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: @@ -3195,7 +3195,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. @@ -3269,11 +3269,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. @@ -3286,7 +3286,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. @@ -3362,7 +3362,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 @@ -3465,11 +3465,11 @@ 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. -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. @@ -3483,7 +3483,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. @@ -3498,8 +3498,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 @@ -3525,7 +3525,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. @@ -3534,7 +3534,7 @@ This is why we configured an upper limit for how long we wait until creating a P ## 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 @@ -3556,7 +3556,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 @@ -3579,10 +3579,10 @@ Renovate's `"auto"` strategy works like this for npm: 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 are 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. +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`. @@ -3594,13 +3594,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 @@ -3608,7 +3608,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. @@ -3621,7 +3621,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 @@ -3631,7 +3631,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](./key-concepts/pull-requests.md#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. @@ -3682,7 +3682,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 @@ -3699,8 +3699,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 { @@ -3772,9 +3772,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 @@ -3821,13 +3821,13 @@ 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 will see Angular-style commit prefixes like `"chore(deps):"`. If you wish to change it to something else like `"package"` then it will look like `"chore(package):"`. You can also use `parentDir` or `baseDir` to namespace your commits for monorepos e.g. `"{{parentDir}}"`. ## semanticCommitType -By default you will see Angular-style commit prefixes like `"chore(deps):"`. +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 @@ -3846,12 +3846,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. @@ -3873,7 +3873,7 @@ Getting separate updates from Renovate can be handy when you want to, for exampl ## 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. +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. ## separateMultipleMinor @@ -3953,7 +3953,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. @@ -3962,14 +3962,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 only want updates _within_ the scheduled hours, then set 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 @@ -4058,13 +4058,13 @@ Finally, once updates are decided, Renovate restores the compatibility part to t ## 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 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. @@ -4080,8 +4080,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 c37f45a28e2bce..822340f3179440 100644 --- a/docs/usage/configuration-templates.md +++ b/docs/usage/configuration-templates.md @@ -14,11 +14,11 @@ 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 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. @@ -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 2503bb40bfdd38..694b0e54c05d87 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 generalizations/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 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 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 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,11 +27,11 @@ 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 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 will miss out on the fix as there will never be a `1.1.1` once `1.2.0` is already released. @@ -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? @@ -55,21 +55,21 @@ 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 -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`. 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. +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 realize you need to fix it. @@ -98,7 +98,7 @@ 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 are fine. @@ -122,20 +122,20 @@ With this approach, updates will be essentially "silent" - causing no notificati ### 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 our 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,11 +152,11 @@ 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. -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 } @@ -167,7 +167,7 @@ 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,11 +176,11 @@ 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. -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. @@ -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, 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. +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 -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. 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, 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 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 9657770455a777..3eea02c099cbfc 100644 --- a/docs/usage/docker.md +++ b/docs/usage/docker.md @@ -16,7 +16,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`) @@ -25,12 +25,12 @@ 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 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'd like to work on one day. +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 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. @@ -65,7 +65,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`. @@ -82,9 +82,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. @@ -259,7 +259,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. @@ -370,7 +370,7 @@ Assume you are running GitLab CI in the Google Cloud, and you are storing your D 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 42d25404146694..643c3fa2baf231 100644 --- a/docs/usage/examples/self-hosting.md +++ b/docs/usage/examples/self-hosting.md @@ -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` @@ -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,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 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 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/)). +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: @@ -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 parsable. ### About the log level numbers @@ -423,7 +423,7 @@ On Ubuntu/Debian and many Linux-based systems, this can be done by: ### 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 3a99ed4d42c54c..4faf08372df96f 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 @@ -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. @@ -83,14 +83,14 @@ 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. 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 @@ -98,7 +98,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. @@ -129,7 +129,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 { @@ -144,7 +144,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 { @@ -178,7 +178,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. @@ -204,9 +204,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. @@ -266,9 +266,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) @@ -288,7 +288,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`. @@ -298,8 +298,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 75ccffebc1246f..2b87d1c902dad3 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 } @@ -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 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're a fork. + 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 @@ -60,9 +60,9 @@ Once you have enabled Renovate on a repository, you will get a "Configure Renova ### 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 are 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 75d400aa17d990..80383833c71dc8 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. @@ -25,21 +25,21 @@ 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 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 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. 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: @@ -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` @@ -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" @@ -229,7 +229,7 @@ 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 +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. @@ -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 are using the main npm registry then you only need to configure the `npmToken` instead: ```json { @@ -294,7 +294,7 @@ If you are using the main npmjs registry then you can configure only the `npmTok #### 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,7 +324,7 @@ 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 @@ -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. @@ -423,7 +423,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: '', }, ]; @@ -507,7 +507,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 = { @@ -551,9 +551,9 @@ If you are a user of this app, and have private modules, then the following is a ### 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 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. @@ -612,7 +612,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 5abf351cd7ebed..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 @@ -38,14 +38,14 @@ 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. 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`) @@ -58,18 +58,18 @@ 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 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. +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 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 @@ -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 @@ -151,12 +151,12 @@ 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. @@ -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 "`. @@ -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) @@ -218,8 +218,8 @@ 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. + 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 932b0d00b0ced9..66e562a57a44c6 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: @@ -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. @@ -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. @@ -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: @@ -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 1fd31351cc129c..c99fc8534cbe7e 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,15 +25,15 @@ 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: -- 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 b4a6554406b036..17e504282f3a32 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 @@ -39,7 +39,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 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. +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/java.md b/docs/usage/java.md index bec5049480a017..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 @@ -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/automerge.md b/docs/usage/key-concepts/automerge.md index 43095d66b7ded7..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 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. -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). @@ -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 @@ -228,7 +228,7 @@ If you have no tests but still want Renovate to automerge, you need to add `"ign ### 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. @@ -249,9 +249,9 @@ 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. -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`. +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 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 ddf5d60983e69c..b49a64dc548ce8 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 @@ -68,16 +68,16 @@ Follow these steps to find out why Renovate does not find a changelog: 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 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 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 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/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/how-renovate-works.md b/docs/usage/key-concepts/how-renovate-works.md index 2f2f4608e81dbd..20d3e3eef3d653 100644 --- a/docs/usage/key-concepts/how-renovate-works.md +++ b/docs/usage/key-concepts/how-renovate-works.md @@ -35,8 +35,8 @@ Renovate uses these modules in order: 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/presets.md b/docs/usage/key-concepts/presets.md index 4ffaa25de680f0..33f8daf162582d 100644 --- a/docs/usage/key-concepts/presets.md +++ b/docs/usage/key-concepts/presets.md @@ -18,9 +18,9 @@ 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 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 456f3566f58cf9..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 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 5912b1556964e8..908480fab3a5e0 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 lists some common limitations, describes whether they are permanent and if there are any plans to improve 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: @@ -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..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 237c33194a4ee6..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/index.md b/docs/usage/modules/versioning/index.md index eab2373bcb1b40..95992d832d225e 100644 --- a/docs/usage/modules/versioning/index.md +++ b/docs/usage/modules/versioning/index.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 468c5383dc5747..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 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 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,13 +43,13 @@ 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 +- 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. -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. +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,8 +124,8 @@ 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. -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. +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. diff --git a/docs/usage/nuget.md b/docs/usage/nuget.md index 151da12225bb96..3547b0ed024e54 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 syntax +- `.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/). @@ -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 @@ -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. @@ -118,7 +118,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/python.md b/docs/usage/python.md index 031d49640dfda8..01bbe3f723ede0 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. @@ -25,7 +25,7 @@ Legacy versions with the `===` prefix are ignored. ## 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..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,11 +65,11 @@ 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) -- 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..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 3509847d322958..4759e7710e679a 100644 --- a/docs/usage/security-and-permissions.md +++ b/docs/usage/security-and-permissions.md @@ -44,7 +44,7 @@ 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 | @@ -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. #### Security awareness for self-hosted Renovate instances diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index 0a0bd42b6bb530..9f9a2f0552d4d8 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -159,7 +159,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 are using env or cli variables to configure it. RENOVATE_AUTODISCOVER_FILTER="/MyOrg/{my-repo,foo-repo}" @@ -190,7 +190,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 @@ -247,8 +247,8 @@ The sort method for autodiscover server side repository search. ## 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. +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: @@ -260,7 +260,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: @@ -301,7 +301,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. @@ -353,11 +353,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. !!! warning @@ -388,9 +388,9 @@ The above configuration approach will mean the values are redacted in logs like 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. +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 @@ -408,7 +408,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 @@ -503,7 +503,7 @@ Read the [Docker Docs, configure runtime resource constraints](https://docs.dock ## 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`. @@ -533,7 +533,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: ``` @@ -558,7 +558,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 defaults to 15 minutes. ## exposeAllEnv @@ -599,9 +599,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 @@ -633,16 +633,16 @@ 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. -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 @@ -663,7 +663,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 @@ -674,7 +674,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 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. @@ -808,13 +808,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 @@ -824,8 +824,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 @@ -845,7 +845,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 @@ -900,7 +900,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 @@ -908,7 +908,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 PGP key pair with GPG use the following commands: @@ -1005,7 +1005,7 @@ 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 @@ -1047,7 +1047,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`. @@ -1100,12 +1100,12 @@ Read more about the default credential provider chain for AWS SDK for JavaScript !!! 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/'`. !!! 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 @@ -1120,11 +1120,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 @@ -1193,7 +1193,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 b1800d4b6af51b..1018421c9c7964 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` @@ -58,7 +58,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 mergeable 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 `RENOVATE_X_GITLAB_MERGE_REQUEST_DELAY * attempt * attempt` milliseconds. Default value: `5` (attempts results in max. 13.75 seconds timeout). @@ -67,7 +67,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 70de8c64e9143c..6468bc05873dc3 100644 --- a/docs/usage/templates.md +++ b/docs/usage/templates.md @@ -123,6 +123,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 f97a58d7d68ac3..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. @@ -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. diff --git a/docs/usage/updating-rebasing.md b/docs/usage/updating-rebasing.md index 67d50660edc42d..562dfd56ebb742 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 you have set `keepUpdatedLabel` and included the label on a PR - When a newer version of the dependency is released @@ -22,7 +22,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. @@ -65,6 +65,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 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 9f95f0714aac0a..02cda2732d8cad 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 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` @@ -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 blog post 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 blog post about the GitHub Actions worm](https://www.paloaltonetworks.com/blog/prisma-cloud/github-actions-worm-dependencies/). #### Extends `:pinDevDependencies` @@ -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 a 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,15 +132,15 @@ 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 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. +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. @@ -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 are 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: @@ -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`. @@ -199,11 +199,11 @@ 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 -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. @@ -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: @@ -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. @@ -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 @@ -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 @@ -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 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.