Clarify upstream merge and Renovate actions on PRs

[withinfocus]

🎟️ Tracking

Internal discussions after seeing some Renovate activity.

📔 Objective

Adds guidance around not continually merging the upstream into Renovate branches given the effects and limitations, as well as in general.

[cloudflare-workers-and-pages]

Deploying contributing-docs with    Cloudflare Pages

Latest commit:	de4725d
Status:	✅  Deploy successful!
Preview URL:	https://70fed9dc.contributing-docs.pages.dev
Branch Preview URL:	https://nomain.contributing-docs.pages.dev

View logs

[github-actions]

Checkmarx One – Scan Summary & Details – 779e0ec9-07b2-42e6-8386-f1e7388999c2

Great job! No new security vulnerabilities introduced in this pull request

[eliykat]

I wasn't in the internal discussions, but some input from the tech lead perspective.

[eliykat]

"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.

[withinfocus]

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.

[eliykat]

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...

[withinfocus]

It's true that every push fires the same notifications and CI runs regardless of whether the new commit is a merge or a rebase, so "noise" wasn't the right framing. The argument I should have led with is squash-semantics: a rebased branch more closely resembles what main will see after the squash-merge, so the pre-merge state matches the post-merge state.

Your "reviewers lose their history" concern is also real, and the section's actual point is "don't sync often" rather than "rebase vs merge" so I dropped the preference and now present both options neutrally with the tradeoff called out.

[eliykat]

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.

[withinfocus]

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.

[eliykat]

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.)

[withinfocus]

The sentence as I wrote it was ambiguous: I was describing post-merge CI on main, not a pre-merge check, and the way I worded it doesn't make that clear. I also added a caveat for the cases that need a pre-merge sync since "CI will catch it after merge" is actively wrong in that scenario.

The intent is to push toward smaller PRs that land quickly so syncing rarely becomes necessary, rather than treating "merge main in weekly" as a default habit.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

This PR adds a new "Keeping your branch up to date" section to branching.md and rewrites the "Changing a generated PR" section in dependencies/index.md to clarify Renovate branch interaction. The two files are cross-linked, and the new dependencies content correctly defers to the new branching section for general guidance while documenting Renovate-specific behavior. The author has already incorporated reviewer feedback to present rebase and merge neutrally with the force-push tradeoff called out, and to clarify that CI on main (post-merge) is the safety net rather than pre-merge sync. Two earlier grammar suggestions have been resolved in the current diff.

Code Review Details

No new findings. Cross-link slug #keeping-your-branch-up-to-date resolves to the new heading, terminology is consistent with the rest of the file, and prior inline suggestions are reflected in the current text.