Stacked diffs, also known as stacked changes or stacked pull requests, is a workflow concept that involves stacking a series of small, dependent changes atop one another. This method allows developers to review and merge small changes independently, making the code review process more efficient and manageable.
The idea behind stacked diffs is that you can keep working on your main branch, and worry about reviews later
The Pragmatic Engineer
Historical Context and Evolution
The idea of stacked diffs originated from open-source software development practices, where developers would submit a stack of patches for review. Over time, this practice was formalized into various tools and platforms such as Phabricator (with its Differential tool) and Critique (Google's internal code review tool). These platforms allowed developers to easily manage and review stacks of changes.
What are Stacked Diffs?
Stacked diffs refer to a series of changes where each change depends on the previous one. Each 'diff' in the stack is a small, self-contained change that builds upon the change before it. This contrasts with the traditional model where large changes are reviewed in a single, monolithic pull request.
Benefits of Stacked Diffs
The stacked diffs approach offers several advantages over traditional code review methods:
Improved Focus: Reviewers can focus on small parts of the codebase, making it easier to spot issues and understand the context of changes.
Faster Feedback Loop: Smaller changes can be reviewed and merged more quickly, leading to a faster feedback loop between developers and reviewers.
Easier Management: Dependencies between changes are explicitly defined, making it easier to manage and track the progression of features or fixes.
Reduced Merge Conflicts: By frequently merging small changes, the likelihood of significant merge conflicts is reduced.
Incremental Testing: Each change can be tested independently, which helps in identifying the cause of regressions or bugs.
Implementing Stacked Diffs Workflow
To implement a stacked diffs workflow, developers must understand how to break down their work into small, incremental changes. Tools like Graphite, which extend the functionality of version control systems like Git, provide command-line interfaces (CLIs) to facilitate this process.
Key Components and Concepts:
Branch Stacking: Creating branches for each diff that are based on the branch of the previous diff.
Pull Requests (PRs): Each diff in the stack corresponds to a PR, which is reviewed independently.
Automatic Rebasing: Tools can automatically rebase the stack as diffs are merged, ensuring that each PR is up to date with the base branch.
Testing: Each diff should pass all tests before it is merged, ensuring that the main branch remains stable.
Popular Tools for Stacked Diffs
Graphite: Provides a CLI that works with GitHub, automating many aspects of the stacked diffs workflow.
Phabricator: An open-source tool suite that includes Differential, a code review tool that supports stacked diffs.
Best Practices for Stacked Diffs
Keep Diffs Small: Each diff should represent a single, coherent change.
Ensure Dependencies are Clear: Make sure that the dependency chain is clear and logical.
Maintain a Stable Base Branch: The base branch should always be in a deployable state.
Frequent Communication: Developers and reviewers should communicate frequently to ensure that diffs are reviewed in a timely manner.
Conclusion
Stacked diffs represent a powerful paradigm shift in the code review process, promoting faster, more focused, and efficient workflows. By implementing a stacked diffs workflow, teams can improve their productivity and code quality, ultimately leading to a more agile development process. Tools like Graphite are at the forefront of this shift, providing the necessary infrastructure to support stacked diffs in modern development environments.
