See https://stackoverflow.com/questions/20756320/how-to-prevent-...

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

Perhaps a future iteration of this feature will at least allow us to do something like merge just steps of it if they can be reordered.

  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)

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.

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.

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?

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!

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.

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.

To me, stacked PRs seems overly complicated. It seems to boil down to propagating git rebases through stacks of interdependent branches.

I'm fine with that as long as I don't have to deal with people force pushing changes and routinely rewriting upstream history. It's something you probably should do in your own private fork of a repository that you aren't sharing with anyone. Or if you are, you need to communicate clearly. But if the goal is to produce a stack of PRs that in the end merge cleanly, stacked PRs might be a good thing.

As soon as you have multiple collaborators working on a feature branch force pushing can become a problem and you need to impose some rules. Because otherwise you might end up breaking people's local branches and create work for them. The core issue here is that in many teams, people don't actually fork the main repository and have push access to the main repository. Which emulates the central repository model that people were used to twenty years ago. Having push access is not normal in most OSS projects. I've actually gotten the request from some rookie developers that apparently don't get forking to "please give me access to your repository" on some of my OSS projects.

A proper pull request (whether stacked or not) to an OSS project needs to be clean. If you want to work on some feature for weeks you of course need mechanisms to stay on top of up stream changes. OSS maintainers will probably reject anything that looks overly messy to merge. That's their job.

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.

...or you don't bother with all that and simply do:

- gh stack init

- gh stack push

- gh stack submit

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.

The traditional tools (mailing-lists, git branches, Phabricator) represented each change as a difference between an old version of the code and the proposed new version. I believe Phabricator literally stored the diff. They were called “diffs” and you could make a new one by copying and pasting into a <textarea> before pressing save*.

The new fangled stuff (GitHub and its clones) recorded your change as being between branches A and B, showed you the difference on the fly, and let you modify branch B. After fifteen years of this we are now seeing the option for branch A to be something other than main, or at least for this to be a well supported workflow.

In traditional git land, having your change as a first class object — an email or printout or ph/D1234 with the patch included — was the default workflow!

*Or some other verb meaning save.

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.

I've just written those smaller PRs at once, or in quick enough succession that the previous PRs weren't merged before the later ones were ready. And the later ones relied on the previous ones because that's how working on a feature works.

The earlier PRs are absolutely reviewable and testable without relying on the later ones. The later ones are just treating the earlier ones as part of the codebase. I.e. everything here looks like two different PRs except the timing.

An obvious example would be "implement API for a feature" and then "implement UI that uses that API". Two different PRs. The second fundamentally relies on the first.

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

for example, this stack adds a search bar: https://tangled.org/tangled.org/core/pulls/1287

- the first PR in the stack creates a search index.

- the second one adds a search API handler.

- the last few do the UI.

these are all related. you are right that you can do this by breaking a change into commits, and effectively that is what i do with jujutsu. when i submit my commits to the UI, they form a PR stack. the commits are individually reviewable and updatable in this stacking model.

gh's model is inherently different in that they want you to create a new branch for every new change, which can be quite a nuisance.

have written more about the model here: https://blog.tangled.org/stacking/

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.

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

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

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.

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.

In the tool I wrote, you have a single branch with linear history. PRs in the chain are demarcated via commit messages. You then don't need any special rebase / sync commands -- you can use regular `git rebase -i` to reorder commits or edit a commit in the middle of a stack. Literally the only special command I need is "push this branch to github as multiple PRs".

Anyway I hope that alongside the branch-based you've built tool in `gh` that there will be an API that I can target.