Turn one giant AI-generated pull request to a reviewable stack

In recent years, software development teams have grappled with the dilemma of deciding between shipping a single large pull request or breaking it down into smaller, more manageable pieces. The former often leads to an unreviewable mess while the latter requires constant babysitting and conflict resolution. However, the introduction of coding agents has amplified the need for structuring pull requests effectively, as they boost productivity across every stage of the software development life cycle (SDLC).

This post delves into an example of how stacked pull requests can simplify reviews, using the addition of product search to a shopping assistant as a case study.

When tasked with incorporating product search into an existing web application, a typical approach would involve creating a feature branch, assigning it to an agent or multiple custom agents, writing the code, updating tests, reviewing the code, and finally opening a pull request. This process often involves a single, ginormous 1,000+ line diff that includes everything from a new data model and its seed data to the client wiring, UI, and empty/fallback/error states.

Reviewers are left with little context and struggle to provide meaningful feedback, resulting in a slow and painful merging process.

GitHub's stacked pull requests offer a more efficient alternative to this monolithic approach. The core principle behind stacked pull requests is decomposition. Instead of submitting a single pull request that encompasses the entire feature, the feature is broken down into logical layers, each representing a dependency chain that leads to the desired outcome. This approach allows for the creation of small, focused, and independently reviewable layers, which are much easier to review and understand.

The stack structure consists of several layers, each corresponding to a specific branch in the repository. In the example provided, the stack base is set at L1 (feat/catalog-data), which includes the creation of a typed catalog with seed data, validation, and a data access module. The subsequent layers (L2-L4) build upon this foundation, addressing the search API, chat grounding, and grounded UI, respectively.

By assigning specific reviewer audiences for each layer, teams can ensure that the right people are reviewing the right aspects of the feature, leading to more efficient and effective reviews.

GitHub's native support for stacked pull requests can be activated from the pull request UI and extends seamlessly to the terminal via the gh stack CLI. Installation of the stacked pull requests CLI extension and running the command `gh extension install github/gh-stack` enables teams to leverage this powerful feature and streamline their pull request workflows.