DECISION NODE

In the field of software development, we have several common expressions about the benefits of agility and efficiency: "commit early, commit often," "deploy daily," "small batches for quick feedback," and "incremental changes for easier review," to name a few. These expressions aren't mere catchphrases, but foundational principles that guide developers towards best practices in code management and deployment. The underlying philosophy is clear—smaller, more frequent Pull Requests (PRs) are not just a preference, but a strategic approach to software development.

The rationale for this approach is well-supported by empirical evidence. Studies have consistently shown that smaller PRs not only facilitate a faster code review process but can also significantly reduce the number of bugs, thereby streamlining the path from development to deployment. In a fast-paced development environment, this ability to ship code efficiently and reliably is crucial, but not easy to achieve in practice.

Enter stacked workflows—a pragmatic solution designed to offer a structured method to manage and integrate changes in a way that promotes making small, frequent PRs. By enabling developers to build upon previous PRs and work incrementally, stacked workflows not only enhance collaboration but also optimize the review process, eliminating lots of wasted time and frustration. More on this later in the article.

To add: A bit about my experience—I got into stacked workflows around a year and a half ago using a tool called Graphite. I wanted to find ways to make my team's work better, and this system was really eye opening for me. It made those best practices possible in our day-to-day work. Stay tuned for more details on the tools that can help with this.

What are Stacked Workflows?

Understanding Stacked Workflows

At its core, a stacked workflow is a version control strategy tailored for collaborative software development projects. It allows developers to "stack" changes atop one another, forming a cascade of dependent changes. Each of these sets of changes is encapsulated within its own mini-branch - a small feature branch, usually with one commit or a few small commits per branch. These branches can be reviewed and merged independently into the main branch.  

This kind or sequential layering fosters a more organized and simpler review process. Each PR is small so it can quickly be reviewed. The developer working on the feature doesn't need to be blocked waiting for a reviewer either, they can keep branching off of the previous branch as many times as they need to. Once the first PR on the stack gets merged into main, the subsequent PRs can all be updated from main.

Let's look at an analogy to make this concept more clear. Imagine constructing a tower, where each block represents a discrete change. Just as each block supports the next, every change in a stacked workflow lays the foundation for subsequent modifications. This methodical stacking ensures that every piece is meticulously examined and validated, maintaining the integrity of the development process and preventing bugs from slipping through.

Contrast with Traditional Feature Branching

Traditional feature branching, a familiar strategy in software development, involves diverging from the main codebase to develop features or fixes in isolation. Each feature branch creates a parallel timeline of changes, which, upon completion, merges back into the main or development branch. While this approach offers a degree of separation and focus for individual features, it is not without its problems.

Feature branching often leads to long-lived branches that diverge significantly from the main codebase over time (large changes can occur in just days or a week). This divergence can introduce complexities when merging, especially if multiple feature branches are being developed concurrently. The longer a branch remains separate, the greater the potential for merge conflicts and integration headaches. Additionally, the isolation of feature branches can delay critical feedback, as changes are not integrated and reviewed in the context of the evolving main codebase. This slows down the iterative improvement of the code.

Pros and cons of stacked workflows

Pros of Adopting Stacked Workflows

In contrast to traditional feature branching, stacked workflows mitigate these challenges by encouraging more frequent, incremental integrations. Each change, being a small, manageable increment, reduces the likelihood of severe merge conflicts and facilitates a smoother, more continuous development process.

This not only accelerates the feedback loop but also enhances collaboration among team members, as dependencies between changes are clearly defined and easier to navigate. Developers can work in parallel on interconnected features without the bottlenecks typically encountered in traditional workflows. No more getting upset at each other when another develop made significant changes to a file you have been working on!

Developers can also keep themselves more organized with just a small amount of code changes per branch which leads to more mental clarity, lower stress, and increased speed of development. A faster iteration cycle can allow for better refinement of code, making it easier to ensure that improvements are continuously integrated and tested.

For code reviewers, the clarity brought about by focused, bite-sized changes is invaluable. Sometimes reviewers will put off a code review that is difficult or large, and thus time consuming. If each PR targets a specific change, it's easier to comprehend, assess, and integrate. This reduces reviewer procrastination by incentivising reviewers to review immediately for a quick win (PR approval/merge). It can also reduce the need for extra rounds of feedback or questions about a PR.

One final possible benefit is that it can help keep a clean commit history. If you have targeted PRs with one, or a few, small commits, then it's easier to scrub back through the commit timeline and see which changes happened where. Building a linear progression of features or fixes (aka a clean commit history) into a development process by default, will especially help for bug investigations or rollbacks.

Cons of Adopting Stacked Workflows

Despite their benefits, stacked workflows are not without challenges. Teams accustomed to traditional feature branching may face an initial learning curve, requiring time to adapt to the nuances of this approach.

Part of the learning curve includes learning related tooling and systems to streamline this workflow. For example, making frequent PRs into main branch, also called "trunk-based development", will force many teams to rethink their CI/CD setup. A lot of teams that use an intermediate long-standing branch like "dev" or "staging", will want to remove that to allow features to branch directly from "main".

Removing these long-standing intermediate branches does reduce complexity and increase development speed. However, it also means that the team will need a way to account for all of the partially complete features to be merged into main without breaking the app for users. Many teams will use some kind of feature flag system, sometimes called "feature flag development", to handle this. Feature flags are basically a way to hide feature behind a boolean that can be toggled to denote whether to display the feature or not. The feature flag can be set to false for all users until the feature is ready to launch, at which time the flag will simple be set to true.

This is a very basic overview of feature flags. They allow for a lot more useful things like AB testing, paywalls, and incremental rollouts, to name a few. You can set up a simple system on your own, or there are popular tools like Launch Darkly and Statsig that can help and also give you a web dashboard to manage all of your flags.

One more challenge is that it can be a pain to manually update every single branch in a stack every time one PR is merged into main (and presumably, this system will promote frequent merges into main from all developers on the project). Regular Git clients and developer platforms like Github and Gitlab don't have features that can help in this situtation. This is where tooling comes into play. There are a several developer tools that are either built specifically for this workflow, or that are have built in support for it.

• Stacked PR Workflow-Specific Tools
  • Graphite
  • Stacked Git
  • GH Stack
• Tools with Support for Stacked PRs
  • Git Town
  • Sapling

All of these tools provide utilities to help update a whole stack of branches and keep them in sync with a constantly changing main branch. If you use the terminal to manage your Git workflow, then you are in luck because all of the popular tools have CLIs you can integrate with your current workflow. If you use a Git GUI client for local development, it might be a little bit more challenging to adapt since the tools aren't supported by the major Git clients.

One alternative for a regular GUI is using Git plugins for your code editor. Some of the tools have plugins for your code editor, like Graphite which has a VSCode plugin. With tools that don't have a plugin, you can use a regular Git plugin in your editor and add shortcuts for some stacked workflow terminal commands.

You can see from the previous few paragraphs that this workflow can add complexity in the forms of new process and tools. It can take some time to set everything up and get used to using it as a team.

Why Aren't More Teams Adopting Stacked PRs?

Some teams hesitate to adopt stacked PRs for a few reasons. First, there's a belief that stacked PRs are complicated. People often prefer to stick with what they know, and the switch to stacked PRs can seem daunting if you're comfortable with a traditional style of Git. Secondly, there's a lack of understanding about how stacked PRs work, which can make people wary of trying them out.

Lastly, some hold the optimistic view that quickly merging branches will eliminate the need for a stacked workflow. They, rightly, say that if branches can just be reviewed and merged almost immediately, then there is no need for stacking. However, this is almost impossible to do in the real world unless the team is made up of just one or two people. Idealism can make people grossly overestimate what can (and will) be done in practice.

How to Get Started with Stacked Workflows

To begin using stacked workflows, focus on a small project that won't cause major disruptions if you encounter hiccups. This way, you can get familiar with the process and the tools without too much pressure. Try out one of the free tools listed available and follow their guides to get started. They typically offer features that simplify branch management and updating processes, fitting in nicely with the version control systems you’re already using.

When you're ready to transition at a company, it's best to start with a small group of people. This allows you to establish guidelines for managing your stacks and make it easier to keep track of changes and adjustments. It's also important to regularly review how the stacked workflow is going, so you can spot areas that need refinement and keep improving the process. Don't forget to track metrics like number of bugs, developer satisfaction, time to launch, etc.

TL;DR

Stacked workflows are transforming the way development teams collaborate and manage code changes. By enabling smaller, more frequent PRs and merges, they pave the way for enhanced productivity and higher-quality software. These workflows facilitate a more refined code review process, ensuring each contribution is thoroughly vetted and integrated.

Consider trying stacked workflows if you're looking to streamline your development process. There are many great, free tools available to assist you in making the transition smoother. They offer a suite of features that cater to the unique dynamics of stacked workflows, including seamless branch management and updates.

In summary, here’s what stacked workflows can offer your team:

• Smaller PRs: Manageable changes that are easier to review.
• Frequent Updates: Regular integration leading to a continuous improvement loop.
• Improved Quality: Detailed attention to each change enhances overall code quality.
• Productivity Boost: Efficient workflows mean less waiting and more doing.

Take the time to evaluate how stacked workflows might fit into your development practices. The right approach and tools can significantly boost your team's efficiency and the quality of your product.

‍