Skip to content

Clarify upstream merge and Renovate actions on PRs #771

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
withinfocus wants to merge 3 commits into
base: main
Choose a base branch
from
+24 −12
Open

Clarify upstream merge and Renovate actions on PRs #771

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
665b77b
Clarify Renovate actions on PRs
withinfocus Feb 19, 2026
64e1322
Merge remote-tracking branch 'origin' into nomain
withinfocus Feb 19, 2026
01f8fc4
Expand guidance
withinfocus Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/contributing/dependencies/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,18 +300,18 @@ 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. 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 that it will remove any work you performed yourself.

![Updating a PR](image.png)

Expand Down
12 changes: 12 additions & 0 deletions docs/contributing/pull-requests/branching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +112 to +113
Copy link
Copy Markdown
Member

@eliykat eliykat Feb 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI will only surface conflicts or incompatibilities with main if you merge main into your feature branch so that tests (etc) can run. Is the advice here to update from main only immediately before merging, and not before? (I would be OK with that, but it's unclear here and I might be misunderstanding.)

Otherwise it is possible to merge to main and then have failures in main. e.g. because your database migrations have been overtaken.

Copy link
Copy Markdown
Contributor Author

@withinfocus withinfocus Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am speaking about CI on main; the advice is to not do it at all and to work in isolation. There are long-term issues here where the individual causing a failure doesn't actually respond to it, but assuming that becomes a true requirement I would want failures there to create backpressure on working differently so that it's avoided altogether. We're currently skipping past why there's failures at all.

Copy link
Copy Markdown
Member

@eliykat eliykat Feb 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would want failures there to create backpressure on working differently so that it's avoided altogether

That is - you want to push developers to keep PRs small and merge into main frequently, rather than having larger PRs that become out of date?

In terms of the wording - would this be more accurate?

CI will surface any conflicts or incompatibilities after the PR is merged to main.

("when the PR is ready to merge" implies the PR hasn't been merged to main yet.)

needed, prefer rebasing over merging so the branch history stays clean.
Copy link
Copy Markdown
Member

@eliykat eliykat Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"If a rebase is needed, prefer rebasing over merging" - what is this trying to express? If a rebase is needed then a rebase is needed.

That said, generally our advice among devs is to avoid rebasing, because reviewers lose their history of what commits they've already reviewed. Github has gotten a little better at showing this but merging (rather than rebasing) still avoids the issue altogether. Also, a tidy branch history is nice to have during review, but we squash commit everything to main it's less important for us.

Copy link
Copy Markdown
Contributor Author

@withinfocus withinfocus Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm also trying to make this more of the norm because the review experience already handles that and having a commit -- therefore notifications, more builds, and so on -- isn't representative of what actually happens when the PR is closed (the squash). Squashing is an operational (GitHub repo) setting and while generally expected does have to be enabled.

I'm not fixated on this and can drop the language here but I feel merge commits create noise.

Copy link
Copy Markdown
Member

@eliykat eliykat Feb 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rebasing creates the same noise, because you get notifications/CI on the rebased commits, and (imo) merge commits are easy enough to navigate. But perhaps rebasing/force-pushing better represents the semantics of what you're doing (resetting the state of the branch) rather than merges.

Thinking about it more, I'm used to one way of doing it, but realistically we could do either. I would've argued against it before the Github review experience handled it, but I believe it can diff before & after a force push now, so if this is the desired direction then we can work towards it.

For wording, maybe

If you need to update your branch, prefer rebasing over merging...


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
Expand Down