We are pleased to announce the release of a new tool aimed at simplifying the management of stacked pull requests (PRs) on GitHub - stack-pr. This tool is still in its early development days, but we are excited to share it with the community and welcome your contributions.
What are stacked PRs?
Stacked PRs are a way to structure pull requests in a way when one PR depends on another in a sequence. Instead of submitting one large PR, you can break your changes into smaller, more manageable PRs that build on each other. As each PR in the stack is reviewed and merged, the remaining PRs are automatically updated, ensuring a smooth integration process.
What are the benefits of using stacked PRs?
Stacked PRs offer a structured way to manage multiple interdependent changes in a codebase. By breaking down large changes into smaller, more focused PRs, developers can benefit from:
- Better code reviews: Each PR can be reviewed independently, making it easier to identify issues and understand changes.
- Parallel work: You can proceed with work on a next change before another required change is fully reviewed and merged.
- Cleaner history: The commit history remains more organized, reflecting the logical progression of changes.
In the diagram below, the first graph demonstrates a typical workflows without stacked PRs. In the second graph, you can see the updated and simplified workflow with stacked PRs:
What is stack-pr and how to use it?
stack-pr is a CLI tool for managing stacked PRs from the comfort of your terminal. With a simple interface it allows you to create, update and merge stacked PRs.
stack-pr offers a simple mental model for managing stacks of PR - each commit in your local git branch becomes a separate PR dependent on the PR from the previous commit. When you want to update the stack - e.g. either include some changes to existing PRs, reorder them, drop some of them, or add new PRs - you simply make the corresponding changes in your local git branch (usually you’ll be using git rebase -i for this) and then run a single command stack-pr export to update the PRs on GitHub correspondingly. When you are ready to merge your PRs, you can use the stack-pr land command, which would land the bottommost PR and rebase the rest of the stack.
You can find a more detailed manual on how to use the tool in README.md.
Acknowledging similar tools
stack-pr is not the first tool in the space, and we’d like to acknowledge other existing tools - specifically ghstack which heavily inspired stack-pr. ghstack is also a great tool for working with PR stacks, however it has some limitations which we worked around in stack-pr. For example, ghstack requires you to allow force pushes to your repo, and also it generates 3x more branches when constructing a stack compared to our tool. Nevertheless, we highly recommend giving it a shot too!
Why are we open-sourcing stack-pr?
Our company believes in giving back to the community. By open-sourcing this tool, we hope to contribute to the ecosystem and encourage collaboration and improvement. We invite developers, teams, and open-source enthusiasts to try out our tool, provide feedback, and contribute to its development. stack-pr is in its early days and there are many things that can be improved, and while you can use it as-is right now, we also welcome contributions to the tool to make it better for everyone!
Thank you for your support, and we look forward to seeing how this tool evolves with your contributions! You can get stack-pr on GitHub, and be sure to check out the rest of the Modular community, which includes an active Discord where you can share feedback and connect with other devs.
