From 665b77b4f86488a736ce3b42aefa09dc7528084e Mon Sep 17 00:00:00 2001 From: Matt Bishop Date: Thu, 19 Feb 2026 14:51:30 -0500 Subject: [PATCH 1/4] Clarify Renovate actions on PRs --- docs/contributing/dependencies/index.md | 26 ++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/contributing/dependencies/index.md b/docs/contributing/dependencies/index.md index eb9e55e57..4852a7fba 100644 --- a/docs/contributing/dependencies/index.md +++ b/docs/contributing/dependencies/index.md @@ -300,18 +300,26 @@ 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. +Let Renovate manage its own branches whenever possible. 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. -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.** +:::warning Avoid merging the upstream into Renovate branches -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. +Merging the base branch (e.g. `main`) into a Renovate branch is often unnecessary. Renovate will +rebase the branch on its own schedule and CI will catch any conflicts. Resist the urge to keep +Renovate branches up-to-date with the upstream manually. -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. +::: + +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 that it will remove any work you performed yourself. ![Updating a PR](image.png) From 01f8fc490869a39e7a9138f0d9c621c1a2317e9c Mon Sep 17 00:00:00 2001 From: Matt Bishop Date: Thu, 19 Feb 2026 17:10:27 -0500 Subject: [PATCH 2/4] Expand guidance --- docs/contributing/dependencies/index.md | 8 -------- docs/contributing/pull-requests/branching.md | 12 ++++++++++++ 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/contributing/dependencies/index.md b/docs/contributing/dependencies/index.md index 4852a7fba..aa93b913c 100644 --- a/docs/contributing/dependencies/index.md +++ b/docs/contributing/dependencies/index.md @@ -304,14 +304,6 @@ Let Renovate manage its own branches whenever possible. If you need Renovate to PR immediately, select the corresponding checkbox on the Dependency Dashboard or the PR itself; no manual intervention on the branch is usually needed. -:::warning Avoid merging the upstream into Renovate branches - -Merging the base branch (e.g. `main`) into a Renovate branch is often unnecessary. Renovate will -rebase the branch on its own schedule and CI will catch any conflicts. Resist the urge to keep -Renovate branches up-to-date with the upstream manually. - -::: - 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 diff --git a/docs/contributing/pull-requests/branching.md b/docs/contributing/pull-requests/branching.md index 778c2abff..aee1811c7 100644 --- a/docs/contributing/pull-requests/branching.md +++ b/docs/contributing/pull-requests/branching.md @@ -106,6 +106,18 @@ 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 from the upstream add noise to the commit history without meaningful benefit; CI +will surface any conflicts or incompatibilities when the PR is ready to merge. If a rebase is +needed, prefer rebasing over merging so the branch history stays clean. + +Reserve merging `main` into a branch for situations where you genuinely need changes from the +upstream to continue your work, such as depending on a newly merged API or resolving a non-trivial +conflict. In most cases, the branch will be merged shortly and keeping it in sync is wasted effort, +especially on our build and test workflows. + ### Additional considerations for long-lived feature branches :::note From 67744c831465394eea65e0b3717065f5437f651d Mon Sep 17 00:00:00 2001 From: Matt Bishop Date: Wed, 13 May 2026 16:39:57 -0400 Subject: [PATCH 3/4] Improve language --- docs/contributing/dependencies/index.md | 9 +++++--- docs/contributing/pull-requests/branching.md | 24 +++++++++++++------- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/contributing/dependencies/index.md b/docs/contributing/dependencies/index.md index aa93b913c..30832b410 100644 --- a/docs/contributing/dependencies/index.md +++ b/docs/contributing/dependencies/index.md @@ -300,9 +300,12 @@ A typical dependency workflow involves the following steps: #### Changing a generated PR -Let Renovate manage its own branches whenever possible. 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. +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, diff --git a/docs/contributing/pull-requests/branching.md b/docs/contributing/pull-requests/branching.md index aee1811c7..24ecf3169 100644 --- a/docs/contributing/pull-requests/branching.md +++ b/docs/contributing/pull-requests/branching.md @@ -109,14 +109,22 @@ It can be helpful to think of this exercise in terms of two dimensions: ### 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 from the upstream add noise to the commit history without meaningful benefit; CI -will surface any conflicts or incompatibilities when the PR is ready to merge. If a rebase is -needed, prefer rebasing over merging so the branch history stays clean. - -Reserve merging `main` into a branch for situations where you genuinely need changes from the -upstream to continue your work, such as depending on a newly merged API or resolving a non-trivial -conflict. In most cases, the branch will be merged shortly and keeping it in sync is wasted effort, -especially on our build and test workflows. +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 From de4725d5657b49f97467a92b34e7b00e09ed0163 Mon Sep 17 00:00:00 2001 From: Matt Bishop Date: Wed, 13 May 2026 16:50:53 -0400 Subject: [PATCH 4/4] Claude grammar --- docs/contributing/dependencies/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/dependencies/index.md b/docs/contributing/dependencies/index.md index 30832b410..483124ea9 100644 --- a/docs/contributing/dependencies/index.md +++ b/docs/contributing/dependencies/index.md @@ -307,14 +307,14 @@ not apply here. If you need Renovate to rebase or recreate a PR immediately, sel 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, +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 that it will remove any work you performed yourself. +Renovate update process on the branch it will remove any work you performed yourself. ![Updating a PR](image.png)