Mastering Efficient Git Workflows with Stacked PRs

In the fast-paced world of software development, the speed of your engineering team is often bottlenecked by the efficiency of your Pull Request (PR) merges. As seasoned engineers, it's our responsibility to streamline this process, especially in the context of remote-first organizations, large meta-repos, and the non-negotiable need for thorough code reviews. Today, I'm excited to share a game-changing approach that has revolutionized our team's workflow: Stacked PRs.

It's not uncommon to come across discussions like this where someone is unhappy with PR review times in their org, or this , where there is data to measure PR review wait times rising in Open source projects.

The PR Predicament: Big, Bloated, and Bottlenecked

Before we dive into the solution, let's dissect the problem that plagues many engineering teams.

The Burden of Big PRs

According to a study by GitClear ¹ , senior developers spend an average of 4 hours per day reviewing code, with larger PRs taking disproportionately more time. This statistic is alarming, especially when we consider the cognitive load that comes with reviewing extensive changes.

PR Size vs. Review Time

Big PRs are notoriously difficult to make sense of, primarily because they often violate the KISS (Keep It Simple, Stupid) principle. Google's engineering guidelines suggest that a "big" PR contains more than 400 lines of changes ² . However, the real issue isn't just the size, but the complexity that arises from mixing different types of changes:

Chores : Routine maintenance tasks
Features : New functionalities
Hotfixes : Urgent bug fixes
Bugfixes : Non-urgent corrections
Improvements : Enhancements to existing features

When a single PR combines these various change types, it becomes a Herculean task for reviewers to maintain context and ensure quality.

"The responsibility of a PR reviewer is directly proportional to the clarity and manageability of the changes they're reviewing."

This axiom highlights a critical issue: PR reviewers can only be held accountable if they fully understand what they're signing off on. Large, complex PRs often lead to delayed reviews or superficial "code-read" approvals, as the effort required to pull, run, and verify extensive changes becomes prohibitive.

The Meta-Repo Maze

The rise of meta-repositories has added another layer of complexity to the PR review process. These repos often include:

Infrastructure-as-code
Documentation-as-code
Client-side components
Microservice backends
Multiple programming languages

In this context, code ownership becomes fragmented, and when a PR touches multiple components, it dilutes responsibility among various owners. This fragmentation often results in a focus on the most changed component, neglecting equally important but less modified parts.

The CI/CD Conundrum

Complex PRs also pose challenges for Continuous Integration and Continuous Deployment (CI/CD) pipelines. It becomes increasingly difficult to:

Write workflows that accurately test all affected components
Ensure that Quality Assurance (QA) processes provide a robust safety net
Maintain velocity without compromising on thorough testing

Stacked PRs: A Paradigm Shift

Enter Stacked PRs – a workflow that addresses these challenges head-on by breaking down large changes into smaller, more manageable pieces.

Stacked PRs Visualization

The Core Idea

Stacked PRs involve creating a series of dependent PRs, each building upon the changes of the previous one. This method allows for:

Incremental Reviews : Reviewers can focus on smaller, more digestible chunks of code.
Parallel Work : Developers can continue working on subsequent changes while waiting for reviews.
Easier Rollbacks : If issues are found, it's simpler to revert or fix specific parts of the change.

Benefits of Stacked PRs

Enhanced Review Process : Smaller, focused PRs are easier to review, reducing the time spent on each PR and increasing the quality of the reviews.
Improved Accountability : With smaller PRs, reviewers can better understand and take responsibility for the changes they approve.
Streamlined CI/CD : CI/CD pipelines can process smaller changes more efficiently, providing quicker feedback and reducing the risk of integration issues.

Evidence of Efficacy

FAANG Adoption : Companies like Facebook and Google have long used variations of this approach, contributing to their ability to maintain high-velocity development in large codebases ³ .
Open Source Success : Popular open-source projects like Linux kernel development utilize a similar concept with patch series, enabling rapid iteration and thorough review processes ⁴ .
Improved Metrics : Teams adopting stacked PRs often report:
Reduced time-to-merge for complex features
Increased reviewer engagement
Higher code quality due to more focused reviews

Implementing Stacked PRs: A Practical Playbook

Adopting a stacked PR workflow involves several key components and considerations. Let's break down the solution into its core aspects before diving into the implementation checklist.

Key Aspects of Stacked PRs

Branch Management : Stacked PRs require a disciplined approach to branch creation and management. Each "stack" typically consists of a series of branches, each building upon the previous one.
Tooling : While stacked PRs can be managed manually, specialized tools can significantly streamline the process. These tools help with branch creation, rebasing, and PR management.
Code Review Process : Reviewers need to understand the context of each PR within the stack and review them in order. This often requires a shift in the review mindset.
CI/CD Integration : Continuous Integration and Deployment pipelines need to be adapted to handle interdependent PRs effectively.
Team Communication : Clear communication about the status and dependencies of stacked PRs is crucial for smooth collaboration.

Tools for Stacked PRs

Several tools have emerged to support stacked PR workflows:

Graphite : A comprehensive tool designed specifically for managing stacked PRs, offering features like automatic rebasing and dependency tracking ⁵ .
gh-stack : A GitHub CLI extension that helps manage PR stacks directly from the command line ⁶ .
spr (Stacked Pull Requests) : A tool that integrates with GitHub to facilitate the creation and management of stacked PRs ⁷ .
Stacked Pull Requests by Aviator : A GitHub app that provides a visual interface for managing PR stacks ⁸ .
git-branchless : An experimental tool inspired by the Linux kernel development process, offering advanced history editing and stack management features ⁹ .

Now, let's dive into the implementation checklist:

Implementation Checklist

One-time Setup

Recurring Tasks

Onboarding Engineers

Develop training materials for the stacked PR workflow
- Create video tutorials or written guides
- Include hands-on exercises for practicing the workflow
Pair experienced developers with newcomers
- Schedule pairing sessions for creating and managing stacked PRs
- Encourage questions and provide real-time guidance
Conduct regular refresher sessions
- Address common pitfalls and share best practices
- Showcase successful examples from the team's work

Bootstrapping Projects

Create PR description templates
- Include sections for describing the PR's place in the stack
- Prompt for information on dependencies and testing considerations
Set up project-specific GitHub labels
- Create labels like "stack-base", "stack-middle", "stack-top" for easy identification
Configure branch protection rules
- Ensure base branches of stacks are protected
- Set up required reviews and status checks appropriate for stacked PRs

CI/CD/QA/DevOps

Code Review Process

Update code review guidelines
- Provide instructions on how to review stacked PRs effectively
- Emphasize the importance of reviewing in stack order
Create a review checklist specific to stacked PRs
- Include items like "Verified changes in context of previous stack PRs"
- Prompt reviewers to consider the impact on subsequent PRs in the stack
Set up review assignment automation
- Configure tools to automatically assign the same reviewers to all PRs in a stack
- Ensure primary reviewers are consistent across the stack for context retention

By following this expanded playbook, teams can more effectively implement and maintain a stacked PR workflow. Remember, the key to success is continuous improvement – regularly solicit feedback from your team and iterate on the process to find what works best in your specific context.

Embracing the Stacked PR Future

Adopting Stacked PRs isn't just about changing a workflow; it's about fostering a culture of incremental improvement and focused collaboration. By breaking down large changes into manageable, reviewable pieces, we not only accelerate our development process but also enhance the quality of our codebase.

"The best code is not just written well, but reviewed well. Stacked PRs make great reviews not just possible, but inevitable."

As we continue to refine this approach, I'm eager to hear your thoughts and experiences. Have you implemented Stacked PRs in your team? What challenges did you face, and what unexpected benefits did you discover?

Let's continue this conversation and push the boundaries of efficient software development together. Share your insights, suggestions, or questions with me on Twitter @wiresurfer . Together, we can stack our way to software engineering excellence!