Idea: Local Merge Queue

[abhinav]

For repositories that use Merge for PRs, merging a stack of PRs is very easy.
Given a stack main -> feature1 -> feature2, you can merge feature1, and then feature2.
No additional work is needed.

For repositories that use Squash or Rebase for PRs, the workflow is:
merge feature1, then rebase feature2 on new main, push, wait for CI, press merge again.
This is annoying.

It's worth exploring a merge command that acts as a local merge queue:
it merges the bottom-most PR, waits for the merge (e.g. if a GitHub Merge Queue is in use), rebases the next PR, pushes, merges, and so on.

Obviously, it stops as soon as the build fails (maybe with a build retry option for known flaky builds), or if there's a conflict rebasing, but otherwise it would be useful. e.g. hypothetically,

> gs downstack merge
Merging feature1 (#42)
Waiting for Merge Queue...
Rebasing feature2 (#43)
Waiting for builds...
Merging feature2 (#43)
Waiting for Merge Queue...
All PRs merged!

---

Progress

• gs downstack merge Add 'downstack merge' command to merge stacks #1152
• Commands
  • gs branch merge: merge a single branch (feat(branch): Add branch merge command #1279)
  • gs stack merge: needs to handle non-linear stacks (refactor(merge): Add merge queue scheduler #1282, feat(merge): Add stack merge command #1283, mergequeue: Schedule dependent merges in phases #1315)
• UX
  • merge progress widget (ui: Add downstack merge progress widget #1232, merge: Render downstack progress in terminals #1234, merge: Run progress widget in scroll region #1274)
  • merge: show individual status checks, not just binary state deferred
• Customizability
  • merge: merge command configuration option (run arbitrary command instead of server-side merge). may be used for non-standard merge instructions (merge: Add merge command hook #1323)
  • merge: customization on definition of mergeable (maybe just a command that takes JSON information?) deferred
• Documentation doc: add Merging stacks #1326

[matthiasr]

If feasible, it would be ideal if this could run in the background without depending on the local workspace state. That way, I could set a stack to merge, while continuing to work on other things (either on top of or in parallel to this stack).

[jarviliam]

Running in the background would be ideal but it may need to run in the foreground to report errors when it's unable to merge due to failing pr checks/conditions.
Having a flag that controls if the merge queue is background tasked or not seems to be a good idea 👍

[matthiasr]

I don't need it to run in the background, I would open another terminal for parallel work, as long as that doesn't mess up the merge process.

[abhinav]

Let me prefix this by saying that this feature is currently in just-an-idea phase, so implementation details are super undecided.

The way I imagined this working, it would need access to a working copy of the repository so that it could restack upstack branches after the bottom-most PR merged. So it would need to hold onto the working tree while it's waiting to merge everything. However, it doesn't have to take over the working tree that you're working inside. We would be able to use the git-worktree command to get a secondary tree. So depending on how the implementation looked, the command could either always create a temporary working tree for rebasing or make it opt-in/opt-out with a flag¹.

Footnotes

1. Populating a new working tree can take long for really really large monorepos. ↩

[matthiasr]

With #94 would a checkout still be needed? I've never used git replay but it seems like a good match here, and in case of conflicts you'd probably need to stop and tell the user anyway.

[abhinav]

Yeah, that's correct. If #94 is implemented, and the system has a recent enough version of Git, we would not need a worktree. Although the rebase-based workflow would still be something to do as a fallback when git isn't recent enough.

[kalbasit]

I decided to solve this via a GitHub workflow and I created https://github.com/kalbasit/stackmerge-action for this purpose. To merge a stack, just add a merge-stack label to the top-most pr that you want to merge (does not have to be the top of the stack) and it will merge it and all prs under it (no prs above it will be merged).

If you decide to try it out please be advised that I just finished testing it for the first time, I recommend you do not try it out on repositories you care about..

[abhinav]

gs downstack merge is now available as an experimental feature thanks to @ed-irl.
I have some immediate-term plans for this that I would like to address before I release the feature, but if anyone wants to build from source and try, it's available.