GitHub Stacked PRs

The idea is that it allows you to better handle working on top of stuff that's not merged yet, and makes it easier for reviewers to review pieces of a larger stack of work independently.

It's really useful in larger corporate environments.

I've used stacked PRs when doing things like upgrading react-native in a monorepo. It required a massive amount of changes, and would be really hard to review as a single pull request. It has to be landed all at once, it's all or nothing. But being able to review it as smaller independent PRs is helpful.

Stacking PRs is also useful even when you don't need to merge the entire stack at once.

Especially since you get all of the same advantages with plain old stream on consciousness commits and merges using:

git merge --no-ff

git log --first-parent

git bisect --first-parent

https://www.gerritcodereview.com/

Surprisingly it never gained the adoption it deserved.

PR/MR is an "atomic" change (ideally the smallest change that can be landed separately - smallest makes it easier to review, bisect and revert)

Individual commits (or what "versions" are in Phabricator) are used for the evolution of the PR/MR to achieve that change.

But really I have 2 use cases for the commits:

1. the PR/MR is still too big, so I split it into individual commits (I know they will land together)

2. I keep the history of the evolution of the PR/MR in the commits ("changed foo to bar cause its a better approach")

I mean a branch is just jamming a flag into a commit with a polite note to move the flag along if you're working on it. You make a long trail, leave several flags and merge the whole thing back.

Of course leaving multiple waypoints only makes sense if merging the earlier parts makes any sense, and if the way you continue actually depends on the previous work.

If you can split it into several small changes made to a central branch it's a lot easier to merge things. Otherwise you risk making a new feature codependent on another even if there was no need to.

  git rebase --onto <new_commit_sha_generated_by_squash> <original_commit_sha_from_tip_of_merged_branch> <branch_name>

  PR1: main <- A, B              (branch1)
  PR2: main <- A, B, C, D        (branch2)
  PR3: main <- A, B, C, D, E, F  (branch3)

  S1 (squash of A+B), S2 (squash of C+D)

  git rebase --onto S2 D branch3

  S1, S2, E, F

No idea if this feature fixes this.

Edit: Hopefully `gh stack sync` does the rebasing correctly (rebase --onto with the PR A's last commit as base)

That said, after the squash merge of A and git fetch origin, you want something like git rebase --update-refs --onto origin/main A C (or whatever the tip of the chain of branches is)

The --update-refs will make sure pr B is in the right spot. Of course, you need to (force) push the updated branches. AFAICT the gh command line tool makes this a bit smoother.

All you need to do is pull main, then do an interactive rebase with the next branch in your stack with ‘git rebase -i main’, then drop all the commits that are from the branch you just merged.

I don't see how there is any other way to achieve this cleanly, it's not a git thing, it's a logic thing right?

I mean if you've got a feature set to merge into dev, and it suddenly merges into main after someone merged dev into main then that's very annoying.

The github UI may change the target to main but your local working branch doesn't, and that's where you `rebase --onto` to fix it, before push to origin.

It's appropriate for github to automatically change the target branch, because you want the diff in the ui to be representative. IIRC gitlab does a much better job of this but this is already achievable.

What is actually useful with natively supported stacks is if you can land the entire stack together and only do 1 CI/actions run. I didn't read the announcement to see if it does that. You typically can't do that even if you merge PR B,C,D first because each merge would normally trigger CI.

EDIT: i see from another comment (apparently from a github person) that the feature does in fact let you land the entire stack and only needs 1 CI run. wunderbar!

As we have it designed currently, you would have to wait for CI to pass on the bottom two and then you can merge the bottom two in one step. The top of the stack would then get rebased, which will likely trigger another CI run.

Thanks for the callout - we'll update those docs to make it clear multiple PRs can be merged at once.

Then the commits in the PR are not held to the standard of being acceptable to apply, and they are squashed together when the PR is merged.

This allows for a work flow in which up until the PR is merged the “history of developing the PR” is preserved but once it is merged, the entire PR is applied as one change to the main branch.

This workflow combined with stacked PRs allows developers to think in terms of the “smallest reviewable and applicable change” without needing to ensure that during development their intermediate states are safe to apply to main.

Stacked PRs are not breaking up a set of commits into divisible units. Like you said, you can already do that yourself. They let you continue to work off of a PR as your new base. This lets you continue to iterate asynchronously to a review of the earlier PRs, and build on top of them.

You often, very often, need to stage your work into reviewer-consumable units. Those units are the stack.

Also the rationale for having a chain of branches pointing to each other was so the diff in a PR shows just the relevant changes from the specific branch, not the entire set of changes going back to the parent/trunk.

Curious how you're thinking about it?

Graphite (which they seem to be inspired by) has frozen branches exactly for that use case:

https://graphite.com/blog/introducing-frozen-branches

Imagine you have some task you are working on, and you wish to share your progress with people in bite sized chunks that they can review one at a time, but you also don’t want to wait for their reviews before you continue working on your task.

Using a stacked set of PRs you can continue producing new work, which depends on the work you’ve already completed, without waiting for the work you’ve already completed to be merged, and without putting all your work into one large PR.

> The time of other devs is quite valuable and I can't imagine wasting it by having them review something that doesn't even make it in.

this is now what stacked diffs are for. stacked diffs doesn't mean putting up code that isn't ready. for example you are updating some library that needs an API migration, or compiler version that adds additional stricter errors. you need to touch hundreds of files around the repository to do this. rather than putting up one big diff (or PR) you stack up hundreds of them that are trivial to review on their own, they land immediately (mitigating the risk of merge conflicts as you keep going) then one final one that completes the migration.

So, when I saw this announcement seemed interesting but don’t see the point of it yet.

> If they’re not, why do you want to review them independently?

For this example, you may want review from both a backend engineer and a frontend engineer. That said, see this too though:

> that seems like something you can already do by just breaking a PR into commits and letting people look at one of those at a time.

If you do this in a PR, both get assigned to review the whole thing. Each person sees the code that they don't care about, because they're grouped together. Notifications go to all parties instead of the parties who care about each section. Both reviews can proceed independently in a stack, whereas they happen concurrently in a PR.

> If you approve change A and reject change B, then the feature is only half done.

It depends on what you mean by "the feature." Seen as one huge feature, then yes, it's true that it's not finished until both land. But seen as two separate but related features, it's fine to land the independent change before the dependent one: one feature is finished, but the other is not.

you have hundreds or thousands of files to fix. that is unreviewable as a single commit, but as a per-file, per-library, per-oncall, etc. commit it is not that bad.

The feature is also half done in this case. The author can fix up the concerns the reviewer had in A and then both can be merged at the same time.

I use jj to stack branches so i'll just be using the UI to do github pr stacks.

In this model, you tend to want to amend, rather than add more commits. And so:

> they might start with 5 for backend, then 5 commits to each branch to iron out the interface and communication,

You don't add more commits here, you modify the commits in your stack instead.

> Now I need to rebase my frontend branch to sit on B6?

Yes, when you change something lower in the stack, the things on top need to be rebased. Because your forge understands that they're stacked, it can do this for you. And if there's conflicts, let you know that you need to resolve them, of course.

But in general, because you are amending the commits in the stack rather than adding to it, you don't need to move anything around.

> And wouldn't this separation normally be obvious e.g. by paths?

In the simplest case, sure. But for more complex work, that might not be the case. Furthermore, you said you have five commits for each; within those sets of five, this separation won't exist.

They also allow reviewing commits individually, which is very frustrating to do without dedicated support (unless you devolve back to mailing list patch stacks).

I'm not a huge fan, since stacked PRs mean the underlying issues don't get addressed (reviews clearly taking too long, too much content in there), but it seems they want something that works for their customers, right now, as they work in real life.

It's a big improvement (assuming they've done it right).

Plus there's no review that's instant. Being able to continue working is always better.

Stacked PRs are a development method, for managing changes which are separate but dependent on one another (stacked).

The two are orthogonal they can be used together or independently (or not at all).

There’s a special case where certain official orgs can continue to use github.com instead of github.io for their Pages domain, and that’s how you end up with:

https://github.github.com/gh-stack/

from the code:

Should Pages owned by this user be regarded as “Official GitHub properties”?

def github_owned_pages? GitHub.github_owned_pages.include?(login) end

# Orgs/users that are owned by GitHub and should be allowed to use # `github.com` URLs. # # Returns an Array of String User/Organization logins. ...

A stacked PR allows you to construct a sequence of PRs in a way that allows you to iterate on and merge the isolated commits, but blocks merging items higher in the stack until the foundational changes are merged.

I've done this manually by building a big feature branch and asking an LLM to extract out functionality for a portion of it.

For the former, it would seem to split based on frontend/backend, etc. rather than what semantically makes the most sense and for the latter it would include changes I don't want and forget some I do want. But I haven't tried this a lot.