Stacked PRs are now live on GitHub

There's an internal system we have called CPRMC (Create Pull Request Merge Commit) that is used to evaluate whether a PR is "ready" to merge. This covers everything from mergeability (checking for merge conflicts) to rule evaluations (ensuring that approvals match the potential commit that will be created by merge) and more.

This becomes particularly difficult when squash merging a stack of multiple PRs because we have to calculate a series of squashed commits, then associate those back to the rules/reviews. This is relatively easy for the first PR, but for the second PR onwards this gets more complicated because the ancestor commits are squashed and don't exist on the branch as-is. And I won't get into how much more complicated it gets for multi-parent situations lol.

It's something we need to fix and it's the top priority for the team. Our numbers show that 99% of stack merges go through successfully, but we need to get that much higher.

Thank you for being an early user in the preview and bearing with us while we work out these issues!

> You can merge one by one, but if you're using squash and merge, you need a re-approval for each PR in the stack if you require reviews. This makes you lose out on arguably the biggest gain of stacked PRs.

I'm struggling to imagine what it offers at all if that doesn't work! Is it just a way of manually marking another MR as a dependency in the UI so that it shows up with a red X if the other one isn't merged yet?

* I often used it as a way to make reviews significantly easier for the reviewer. If I split something more complex into smaller units where the small change seems obviously correct, it's much more likely i'll get a faster accept than with a very large change.

* Critically, once a unit of the stack has been approved, the approval will still stay with rebases of the whole stack.

* You can keep building up a stacs and once you think you have enough for whatever you are doing, ship the whole stack.

* Suppose you have a 'hole' in the reviews and you're missing a review for a middle part of the stack. You can still merge the bottom part up to where all are reviewed.

* Let's assume you're the reviewer: smaller changes is much easier to review. Also, each part of the stack builds incrementally on the previous one. With your example, suppose you're reviewing 'api changes' part of the stack, but it has failing tests because something is broken with the lower 'db schema changes' change - but otherwise, the 'api changes' diff looks fine - you can then accept it and this part of the stack is already reviewed. The author can now whenever fix their bottom-most change (db schema change) to have tests passing, and get someone to review that (perhaps someone completely different more familiar with db), and then rebase the 'api changes' diff, and _it will not_ require review because you haven't changed anything, just updated the diff underneath it. In this way you parallelized your approvals. Right now at work, using github, I have to serialize my PRs and can't effectively get things reviewed until the previous PR is approved.

I think in my ideal world there would be a clean history and I could review a PR commit-by-commit. But, you can't just approve a single commit, so there's a tooling problem there. And most CI runs on an entire push rather than individual commits. And increasingly I see devs using git as an offsite backup for whatever change they just made, rather than breaking commits up into logical chunks. In that workflow, squashed merges make the most sense.

It's probably flawed, but the mental model I came up with is each stacked PR collapses into what would have been an individual commit in a clean PR, with the advantage of being able to be reviewed separately from the other changes and forced to clear CI. And then the whole stack becomes what would have been a clean PR in the old model. That, I can kinda see the benefit of. But, merging only part of the stack into trunk is the mental hurdle I can't clear; it'd be like merging only some commits from a PR. It kinda reminds me of when projects used CVS.

I've really only seen stacked PRs used on projects where history is little more than an audit log. I'm keen to see how this gets employed by open source projects. I think there's a disconnect and it's likely I'm not going to really get it until I see it.

For the people who work with stacked diffs (in phab/otherwise) this is exactly what they'd consider reviewing a well-curated set of commits one-by-one.

One distinction is that cognitively a unit of review (a PR, a diff) remains a single bound change. Comments are focused on that change and the PR does not grow with size of the feature

Another distinction is the ability to focus each part of the stack to a particular audience. One change may require review from an external team, another may be just your team mate, a third might be the consuming team. By focusing the stack to the different reviewers you can avoid ambiguity about "what a person is signing off on" in the stack.

aside: one thing that would be great for github reviews is the adoption of change ids such that comments persist across reviews with a rebase workflow.

What I can see is that you can easily append commits to e.g. the first PR in a stack, which would insert them into the middle of sequence of commits.

This will require rebasing and fixing the subsequent PRs in a stack the same way you'd need to rebase and fix the subsequent commits in a mega-PR. But it makes the right thing easy (keeping all the commits to the foundation of the change together) rather than makin the wrong thing easy (appending fixup commits across the entire change in a random order so that the actual foundational change is lost).

Keeping all the foundational commits together also keeps all the discussion over the foundational change together.

You could argue that you'd want to only do the foundational PR and stop, but doing the whole stack of PRs gives the reviewers more information about where you're going, and allows work to continue asynchronously.

As far as I can tell, the biggest benefit of stacked PRs over just making a coherent series of commits, is that it might make it easier to start work on your second PR before you merge the first one?

With human-in-the-loop coding, that sounds like it could lead to a lot of wasted work if the first PR gets substantial feedback. But with agentic coding, I can imagine how it might be desirable to keep the agent chugging while the first PR is under review.

Interested in learning more about it and generally agree that AI is stressing the current review paradigms a lot of us are accustomed to.

If GitHub's unit of change were a diff, and not a branch, then that would work pretty well.

So the idea is you can much more cleanly isolate changes for large features.

Even if the reviewer does the review commit-by-commit, all the comments and discussions will be on the same PR leading to multiple ongoing conversations about different topics that would be split if the PR are stacked. Also, all the new commits addressing the comments with spoil this commit-by-commit design, as the previous commits will be outdated and the new changes will be on top of those. I think it's beneficial for new changes to be a separate commit and not rewriting history, to not force the reviewers to re-read everything but just the latest changes.

2. It also can't merge subsets of commits from a single PR. E.g. if you have two commits, A and B, where B depends on A... sure you can make a PR containing A and B, but if A gets approved and B doesn't, then you can't merge A.

3. The thing you want to do with a set of commits and reviewing each commit IS stacked PRs.

This is nothing to do with AI.

The fundamental issue with GitHub -- really, its original sin -- is that the review model is wrong. It encourages a new commit + merge workflow, which is simply worse than an amend + rebase workflow. Basically every other review system in existence -- Gerrit, Phabricator, what Google and Meta have internally, the LKML -- works around stacks where people amend and rebase their commits when changing them. All of these have some notion of a "diff", with "versions" that are each tracked separately, and the ability in the review tool to do diffs between those versions. My hope with stacked PRs was that for once GitHub would use this as an opportunity to modernize its review system and bring it in line with all of these other ones. But sadly that just doesn't seem like it's on the cards.

Why did you choose extra pull requests as the division of work instead of building out a decent UI for reviewing/applying/reworking at the commit level? I assume there's some extra insight that made you ignore the mailing list "series of patches" workflow that inspired this whole thing and go with "series of series of patches" instead.

We worked with Sameen over the last month to add support for GitHub stacks into our mergequeue, and I'm excited to announce support for it today: https://trunk.io/blog/trunk-merge-queue-now-supports-github-...

Am I right this is only available through the CLI?

If so it’s a no go for me and my team. Which is too bad because it looks quite useful.

An addition ability I would love, which is a MUCH bigger feature and I recognize that, would be multi-repo stacks.

My company doesn’t use a monorepo, and I like that. But as we’ve been breaking monoliths sometimes a logical feature touches multiple repos.

Being able to have them all in a stack, each building on the previous logically though in different repos, would be amazing.

Maybe it should have a different name. PR Trains? PR Chains? IDK. But being able to have multiple projects in one logical review is the one benefit of a monorepo I’d like, and if I could get it a different way I’d love it.

> With stacks, you can independently review and check each pull request, then merge everything together in one click.

Consider:

"With pull requests, you can independently review and check each commit inside the pull request, and then merge the entire pull request in one click."

Pull requests are stacked commits. This does not have to recurse; you don't need stacked pull requests, not to mention stacked pull request stacks.

A commit can already contain changes to multiple files. In many cases, even a complex change can be just one commit. A sequence of multiple commits handles all the remaining cases.

Stacked PRs sound like a use case for someone who never wants a PR to be a container for multiple commits, such that if a unit of work is best done as three commits, they want them in separate PRs. Oh, but now they are not related together, the way a stack of commits is related under one PR, so we need a meta-PR to contain PRs or something.

This could be a consequence of commits being sort of second class citizens in the GitHub UI compared to PRs. If you want a commit to be treated as PR, on the same level, you must create a PR with nothing but that commit. So then, what would have been a single PR with four commits that you could merge with one click is now four PRs. Which you want to be able to merge them with one click.

- I want to build feature X

- Ah, but it would work better if I refactored the module first

- I refactor then build feature X

- There's then some additional (and optional) cleanup work

As a reviewer I wouldn't want to see all this in a single PR, and the changes depend on each other so I can't open multiple independent PRs. Manual rebasing is fine but navigating the GitHub UI is then annoying, I have to mentally keep track of where I am in the stack.

The problem I sometimes have is when I queue up 4 or 5 PRs in the afternoon and expect someone to take a look in the morning.

The diff of A into master looks OK, but then the diff of B looks like AB, and the diff of C looks like ABC - each PR has changes that will have already been merged once earlier PRs have been accepted.

My way around it was to raise E as a PR into D, raise D as a PR into C, etc. Then once approved, I change their destinations back to master for the actual merges.

It really confuses reviewers though, even though it's meant to make it so they only see the appropriate changes.

It was new leadership back in October that decided to build this, so it took them 9 months or so. To be clear, I am not saying this is a long amount of time, they had a LOT of work to do to get it to this point, just being clear about timelines.

If one wants to keep it to vanilla git.

Instead of using the same branch, make new branches from that parent and commit there.

The cool thing about that approach is that (at least in git-tower app) is when you edit a parent branch after pr comments, all those new commits will be automatically “restacked” on descended branch (children branches will be rebased on new state or parent, incorporating the hew fixes)

This would be such a insanely useful features for a small subset of power users that they will never deliver.

Say you do change A, add a protocol buffer API definition, then implement the server logic (B) and the front end code (C) so that both depend on A but not each other. That can be in a tree. But now you want to add an integration test (D) that depends on B and C. The tree doesn't help you there, and you were better off making it a linear chain by arbitrarily picking one of B or C to be dependant on the other so that you have a code state with all of A,B and C applied to create D on top of.

Yes, GitHub could have made the UI allow a “per commit” comments somehow, then allow you to select the set of commits to include in the merge somehow, then write a blog post on how to manage “Address PR comments #1” commits. But the stacked PRs solve all that. Not to mention how people treat commits as their own internal save states. I always enable “squash and merge” option because I think it makes a lot more sense to have 1 commit on main per PR where all the context of the change is either in the commit message or the linked PR.

Also LLM providers charge per token. Charging per “work unit” is still not a solved problem. You can’t charge per “review” when your cost is per token. Just like airlines can’t charge “per ticket”, they have to charge differently depending on the destination. Unless you invent some bs arbitrage to lure users and eventually bait and switch on them.

1. The whole review interface isn't set up for reviewing individual commits.

2. You can't merge changes progressively.

3. CI doesn't run on each commit.

4. If you have linear history (good idea IMO) you'll lose your nice commit history when you merge it.

This is much better.

In the scenario you described of your team splitting the tickets, this gives you a UI to manage the PRs of the multiple tickets so you are no longer blocked on merging PR#1 before you can proceed to PR#2. Yes you might have to deal with conflicts, but you would have had to deal with that regardless.

but note line 111:

> This section describes what to do if you're in a Jujutsu (jj) repository. If the user is not using jj, good luck and try your best.

(The whole skill kind of assumes jj. I think you'd need to make a git version if you actually wanted to use it.)

That's literally all it's supposed to do. Make that dev flow less awful so you don't have to say "by the way this PR depends on #123, I will change the target branch when that is merged" and nonsense like that.