diff --git a/docs/usage/key-concepts/pull-requests.md b/docs/usage/key-concepts/pull-requests.md index b930aa8c7a244ae04c6265e6b08ec197141fc65f..75164c5fd95906fbca73d5ac3ec7c1d5eba773e0 100644 --- a/docs/usage/key-concepts/pull-requests.md +++ b/docs/usage/key-concepts/pull-requests.md @@ -7,23 +7,31 @@ This page describes how Renovate pull requests work. ## How Renovate finds existing PRs -Renovate does not keep any kind of database/state of its own about open or closed Pull Requests. +Renovate does not need to maintain any database/state about open or closed Pull Requests. Instead, it uses the code platform's APIs to search and find such PRs. -Locating of existing PRs - whether open or closed - is done by matching both the branch name (e.g. `renovate/lodash-4.x`) and Pull Request title (e.g. `Update lodash to v4.17.21`). +Renovate finds existing PRs (open or closed) by matching both: -In cases like the above, there is typically at most one existing PR with the desired branch + title combination. -When grouping is enabled by users, and PRs have titles like "All non-major updates", then there may be multiple past PRs which match. +- the branch name, for example: `renovate/lodash-4.x`, +- _and_ the Pull Request title, for example: `Update lodash to v4.17.21` + +In cases like the above, there is typically one existing PR with a matching branch name and PR title. +But if you group PRs and use titles like "All non-major updates", then multiple past PRs may match. ## Normal PRs -As described above, Renovate PRs normally have some uniqueness in their title relating to the version in the upgrade. -In such cases, if a user closes such a PR, it can be inferred that they don't want to see it again in future. -For example, they wish to ignore `lodash@4.17.21`. +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: + +1. You ignored `lodash@4.17.21` by closing Renovate's PR +1. Renovate assumes you don't want any updates to `4.17.21` of `lodash` +1. Renovate creates a new PR when the branch + title "uniqueness" exists again, like when `lodash@4.17.22` releases -In such cases, new PRs won't be created until the branch+title uniqueness exists again, such as if there is a `lodash@4.17.22`. +Renovate behaves similarly for `major` updates, for example: -Similarly in the case of major updates (such as "Update lodash to v4") then it can be inferred that the user wishes to ignore all of v4 of `lodash`, even when newer v4 versions are available. +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` ## Immortal PRs @@ -62,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 cached 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'd 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