diff --git a/docs/contributing/dependencies/index.md b/docs/contributing/dependencies/index.md index eb9e55e57..483124ea9 100644 --- a/docs/contributing/dependencies/index.md +++ b/docs/contributing/dependencies/index.md @@ -300,18 +300,21 @@ A typical dependency workflow involves the following steps: #### Changing a generated PR -When reviewing the PR, you may rarely have to make changes to the branch yourself. - -However, caution should be taken when doing so. If a non-Renovate user pushes changes to the -Renovate-generated PR, Renovate assumes that it is no longer responsible for maintaining the PR. -**This means that further updates to the package(s) included in the PR will be blocked until the -modified PR has been merged.** - -What this means is that if you do need to make changes during review, you should maintain ownership -of the PR through the rest of the workflow and not leave the PR open for an extended period. - -If you do want Renovate to take over managing the dependencies in the PR again, you can request that -by selecting the "rebase/retry" checkbox on the PR description. +Let Renovate manage its own branches whenever possible. Renovate keeps its branches current with +`main` on its own schedule, so the general guidance on +[keeping your branch up to date](../pull-requests/branching.md#keeping-your-branch-up-to-date) does +not apply here. If you need Renovate to rebase or recreate a PR immediately, select the +corresponding checkbox on the Dependency Dashboard or the PR itself; no manual intervention on the +branch is usually needed. + +If you need to push additional changes to a Renovate branch, e.g. to resolve a breaking change +introduced by the update, you can do so. However, **once a non-Renovate user pushes to the branch, +Renovate will stop updating that PR entirely.** Further updates to the package(s) included in the PR +will be blocked until the modified PR has been merged. + +If you do push changes to a branch you should maintain ownership of the PR through the rest of the +workflow and not leave it open for an extended period. Also keep in mind that if you use the above +Renovate update process on the branch it will remove any work you performed yourself. ![Updating a PR](image.png) diff --git a/docs/contributing/pull-requests/branching.md b/docs/contributing/pull-requests/branching.md index 778c2abff..24ecf3169 100644 --- a/docs/contributing/pull-requests/branching.md +++ b/docs/contributing/pull-requests/branching.md @@ -106,6 +106,26 @@ It can be helpful to think of this exercise in terms of two dimensions: - Introducing changes to one component or page independently others. - Introducing changes on a client-by-client basis. +### Keeping your branch up to date + +It is usually unnecessary to merge the base branch (e.g. `main`) into a short-lived PR branch. +Frequent merges add commits that don't represent your work and consume build and test resources +without meaningful benefit. Once the PR is merged, CI on `main` will surface any conflicts or +incompatibilities introduced by other work that landed in parallel. + +Reserve syncing your branch with `main` for situations where you genuinely need upstream changes to +continue your work, such as depending on a newly merged API, working through a non-trivial conflict, +or coordinating ordering-sensitive changes -- database migrations are the canonical example, as two +PRs adding migrations in parallel will need the second one rebased before merge. + +When you do need to sync, either rebasing or merging is acceptable. Rebasing more closely matches +how the branch will appear in `main` after squash-merge, but force-pushing can disrupt an in-flight +review; merging is the safer option once reviewers are engaged. + +This guidance applies to human-authored branches. Renovate manages its own branches and will sync +them as needed -- see [Dependency Management](../dependencies/index.md) for how to interact with +Renovate PRs. + ### Additional considerations for long-lived feature branches :::note