Stacked PRs are now live on GitHub(github.blog) |
Stacked PRs are now live on GitHub(github.blog) |
For example, merging an entire stack is completely broken in many cases: https://github.com/github/gh-stack/discussions/212
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.
The command line tooling (gh stack) helps to make things slightly less manual, but you still need to be very aware of how git rebase works, the tooling just helps automate it across multiple branches. For example, just running the "gh stack rebase" commands that the UI suggests won't work if your local branches are not in sync with the remote ones, and the tooling won't point that out to you.
I do find the stack UI quite nice. It's quite minimal compared to standalone PRs, but it's enough to show the relationship between them.
(My comments all assume you already have a good reason to stack PRs. This tooling just help to make the workflow easier, it does not give any new capabilities)
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!
By the way could there be a way to disable that when doing integrations externally? It seems to be quite costly (which makes sense), and the pull/ refs kinda bloat the reflist.
I’m sure that external integration is not exactly beloved internally but there’s really just a small handful of big annoyances which would make it so much nicer and more comfortable.
Excited to release this more broadly so anyone can start stacking: https://gh.io/stacks
Would love to hear any feedback, especially with the UI and CLI. We've got a lot more updates to the PR experience in store!
Also happy to answer questions about the design decisions we made. There's a bunch happening behind the scenes, and it's one of the largest launches in GitHub history covering almost every service from Actions and protection rules to the CLI and mobile apps.
If you buy the idea that stacking produces better software, then this also has the opportunity to really help out quite a few people.
I think the bigger problem is that big AI PR's need a different way of reviewing. For example, the order in which the diff's are shown can make a big difference in how easy the commits are to read (e.g., function definition change first, then all call sites, then the tests).
Or maybe we should go to a system where diffs & comments are intertwined, a bit like how "Literate Programming" intertwines code and prose.
Literate diffs / literate pull requests... I haven't found anything like that yet.
When you click merge, does a 3 stack PR show up as 1 PR in the Dx metrics or 3?
Pre-approval the CLI tooling effectively enables easier automations around splitting a task into multiple atomic PRs - really great locally but then when you push they just show up as independent unlinked PRs.
Post-approval... they still show up as independent PRs. There's a small nav drop down up top listing the other PRs in the stack but that's it. Literally no meaningful UI changes.
The dropdown also allows you to perform a limited subset if the CLI functionality but this is similar to the ability to edit files in the UI - an optional extra casual use feature that won't be a part of dev workflows: the CLI (or IDE plugins I guess) would be the primary way to perform these actions.
It all left me wondering what the big deal with the preview not being a general release - it's extremely minor optional UI. The stacks cli has been general release since this was announced.
Whimsy is fine but that change made me super suspicious about what I was looking at.
1. The PRs are across different related repos, so they literally can't be combined into one PR.
2. You want to keep producing work while the first PR is in review. So you stack subsequent PRs onto the same branch. Basically just pipelining.
But this feature doesn't seem to hit either use case, and instead just seems to be a different form of stacking commits into a single PR. The standard advice has always been to make atomic and meaningful commits (using e.g. rebase to tell a nice story for the reviewer). And reviewers can go through commit by commit if they like.
What am I missing?
Stacked pull requests break large changes into small, reviewable pull requests.
With stacks, you can independently review and check each pull request, then merge everything together in one click.
No more opening a single large pull request that takes forever to review, or splitting work across multiple branches you have to keep manually rebasing.
It's like responsibility is shifted from the author to the tool. That has been tried before, and every time it seem to consistently produce a similarly shaped mess in a different area of a process, but with an added bonus of the tool's own problems and restrictions.
Happy to see something in the right direction. I think they've woken up a bit. Still surprising how slow things can move at big companies.
Companies like Linear, Vercel, Zed and Cursor all seem to be looking at GitHub more aggressively though. I do suspect there will be more competition shortly.
Both are an improvement (GH's seems a little better, with their one-button merge that GL lacks) ... bit both are so incredibly "meh".
When are we going to see the major hosts give tools designed to help facilitate human code review? Simple example: lets say I want to leave notes in my PR (MR on GitLab). I can use the review comments to do so, but then I have a million comments to resolve at the end before I can merge, my comments look just like the reviewer comments (with extra UI for replying that's unecessary), etc.
It'd be so easy to just have a "sign post" feature to let authors annotate their code before reviewers review it ... and nobody offers this, or any other features focused on actually helping humans review. It's all just new command line features that save a bit of rebasing (which Claude can do just fine on its own).
...but if the end result is more popularity of 'stacked' logical changes, yay anyway?
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.
> . By focusing the stack to the different reviewers you can avoid ambiguity about "what a person is signing off on" in the stack.
That can be easily done with comments. If the PR are orthogonal, they could have been split. And if they're not, I would really like to know how the part that I'm reviewing interacts with the rest of the changes.
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.
Can't you run your CI locally? I know it's not feasible for some codebase, but at least the linting, formatting, unit tests, some integration tests should be able to be done locally.
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.
- 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 commits in a PR are already a stack of patches, and so PRs are already "stacked" as they are.
If feature X depends on the refactoring (cannot be rebased on the un-refactored upstream), it's part of the change; you can't just merge the feature and not the refactoring.
If the two are separable that way then, sure, it makes sense to ask for them to be separate PRs.
and the changes depend on each other so I can't open multiple independent PRs
> 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.
Except you can’t really do that on GitHub, the “unit if review” is the PR so reviewing commits is adhoc, inconsistent, and awkward, and tracking their changes as they get fixed up is a pain. “Splatting” that as PRs is not the nicest way to do it green field, but it’s an evolution that makes sense in GitHub’s model.
git-spice is specifically targeted to be useful for PR stacking and doesn't require you to do anything differently from normal git operations that you likely use already. It has a bunch of really nice flows and doesn't try to step outside the bounds of what is needed to easily stack PRs
Not every project requires this, but for those that do, it's impossible.
Also, it is much harder to enforce "everyone must run each commit through the CI equivalent properly" than it is when it's on your forge.
Why can't you? That's what VMs are for. And even then, most cross-platform codebases have an abstraction layer that rarely changes. So even testing on one platform can raise your confidence very high.
> Also, it is much harder to enforce "everyone must run each commit through the CI equivalent properly"
Again why? I wouldn't care about the dev's local branch. But what is send to the main repo can be easily scripted to run the CI on every commit. You just send the result back with each commit that fails. They can replicate the same workflow on their local workspace as a pre-push process.
A set of stacked PRs is exactly the same as a line of commits. The only difference is the UI, but the UI is the important bit here because lack of UI is what's stopping folk from doing that today.
Even when I've developed my changes as a stack of commits, I'll feed them to my team one commit (and one PR) at a time so they're easier to review — and I discovered that GitHub had turned on stacked commits UI because for one particular project I'd manually created a set of PRs in advance (with the right bases) and GitHub offered to create a stack out of them.
So instead of solving that problem, GitHub developed tooling around a workaround for that problem (targeting a PR at another branch that also has a PR).
Expanding reviews to allow per-commit reviews avoids the need for managing additional branches and all the headache that comes with it.
Comments are ad-hoc and don't scale, relying on the author to interpret and adhere to the extent of the reviewers approval.
> And if they're not, I would really like to know how the part that I'm reviewing interacts with the rest of the changes.
you are free to look up, down, and around the stack; nobody is hiding the code from you. But in many cases this is just unnecessary.
I strongly believe that PR should be compared to the main branch, and not rely on unmerged code. Unless you merge everything together in one go. And in the latter case, everything should be reviewed together.