Table of contents

• 1. Incremental development and review
• 2. Sustained development momentum
• 3. Conflict resolution and code integration
• 4. Improved traceability and accountability
• 5. Support from modern tools
• Example scenario
• How Graphite can help
• Conclusion
• Frequently asked questions

Stacked diffs, or stacked PRs, introduce a more structured, incremental approach to integrating code changes. This methodology not only preserves quality standards but also ensures continuous, uninterrupted progress throughout a project's lifecycle. In this guide, we'll take a look at some challenges that stacking addresses and the benefits of implementing this kind of workflow for your development teams.

1. Incremental development and review

Challenge: Conventional pull requests often span numerous features or bug fixes. As a result, code reviews become cumbersome, leading to delays, incomplete assessments, or quality compromises.

Advantage of stacking: By subdividing changes into smaller, logically distinct units, each diff can be examined with precision and care. Reviewers engage with manageable portions of code, leading to more thorough evaluations and a superior codebase. This step-by-step approach transforms a daunting process into a series of manageable, incremental reviews.

2. Sustained development momentum

Challenge: When a large pull request stalls during review, developers may be forced to wait, resulting in downtime and disrupted workflows.

Advantage of stacking: With stacked PRs, a developer can continue advancing subsequent tasks while earlier changes await review. This parallelization minimizes idle time, enhances overall productivity, and maintains a steady cadence of feature delivery.

3. Conflict resolution and code integration

Challenge: Integrating extensive code updates into an active main branch can trigger a cascade of conflicts and regressions, complicating the release process.

Advantage of stacking: Smaller, discrete diffs simplify rebasing and conflict resolution. When conflicts occur, they are confined to a narrower scope, making them quicker and less error-prone to fix. This efficiency results in a more reliable and predictable integration cycle.

4. Improved traceability and accountability

Challenge: Within large, monolithic pull requests, it can be difficult to identify the origin of specific changes or assign responsibility for them.

Advantage of stacking: Each stacked diff corresponds to a well-defined, self-contained modification. This granularity makes it simpler to trace the evolution of a particular change, isolate issues, and assign accountability to the appropriate contributors. The result is greater transparency and improved maintainability of the codebase.

5. Support from modern tools

Challenge: Manually managing interdependent changes and updates can be time-consuming and prone to errors.

Advantage of stacking: Modern tools, such as Graphite, facilitate stacked diffs by tracking dependencies between changes, streamlining updates, and allowing developers to focus on coding rather than administrative overhead. These tools simplify the workflow and reinforce its benefits.

Example Scenario

Consider a new feature spanning multiple layers of an application: backend logic, an API endpoint, and a user interface component. Using stacked diffs:

1. Introduce and merge the backend changes first.
2. Build the new API endpoint atop the updated backend and submit that as the second diff.
3. Implement the UI component based on the completed API, and submit this as a third diff.

Each component of the feature undergoes independent review. This compartmentalized scrutiny makes the process more manageable and increases the likelihood of identifying and resolving issues before they compound.

How Graphite can help

Graphite makes the stacked diff/PR workflow much smoother by adding automation, visibility, and collaboration tools that reduce friction and manual work. Here are key features that teams should know about:

• Automatic rebase after partial stack merges When you merge part of a stack of PRs (for example, the first few of several), Graphite will now automatically rebase the remaining “upstack” pull requests. That means you don’t have to manually run commands to get diffs correct or avoid stale bases.

• Pull request inbox Graphite provides a unified inbox for pull requests (across repos, or within a repo), showing you status (CI results, reviewer comments, stack relationships, etc.). You can filter by author, CI status, labels, review stage, and more, so you can quickly see what needs your attention.

• Insights and metrics dashboards Graphite’s Insights feature gives visibility into PR metrics: time to merge, review wait times, reviewer load, throughput, PR size, and more. This helps teams identify bottlenecks and opportunities for improvement in their review and merge workflows.

• Merge queue and stack-aware merging Graphite supports a merge queue that respects stack order, so PRs are merged in dependency order, with automatic rebasing as needed. This reduces the risk of conflicts or failed CI due to outdated bases.

• Shared and collaborative stacks with better local sync Graphite has improved handling for stacks being worked on by multiple contributors. Remote changes (like Graphite-initiated rebases) are more seamlessly synced locally: gt sync picks up rebased branches from remote, so local development stays aligned with upstream stack updates.

Conclusion

Stacked diffs represent a strategic shift towards modular, efficient, and quality-centric development. Learning and implementing this workflow can significantly enhance the code review process, reduce integration headaches, and maintain a smooth, uninterrupted development pipeline. Plus, tools like Graphite make adopting stacked PRs easy, providing powerful features to accelerate your code review cycles.

Frequently asked questions

What are stacked diffs and why should you know about them?

Stacked diffs (also called stacked PRs) are a development methodology where you break down large features or changes into smaller, sequential pull requests that build upon each other. Each diff in the stack represents a logical, reviewable unit of work. You should know about them because they solve common problems in software development: they make code reviews more manageable, reduce integration conflicts, improve development velocity, and enhance code quality through better traceability and accountability.

What is the difference between stacked diffs and git?

Git is a version control system that tracks changes to files over time, while stacked diffs are a workflow methodology that uses git as the underlying technology. Git provides the fundamental tools for branching, merging, and tracking changes, but stacked diffs add a structured approach on top of git. Instead of creating one large branch with many changes, stacked diffs create multiple small branches that depend on each other, making the development and review process more organized and efficient.

What are diffs in software engineering?

In software engineering, a "diff" (short for "difference") is a comparison between two versions of code that shows what has changed. It displays additions (new lines marked with +), deletions (removed lines marked with -), and modifications. Diffs are fundamental to code review processes, as they allow developers and reviewers to quickly understand what changes were made, why they were made, and assess their impact on the codebase. In the context of stacked diffs, each "diff" refers to a complete pull request containing a set of related changes.