Skip to content

Stacked PRs

What

Stacked PRs are basically small PRs build on top of each other. In the Git branching model, this means that the first PR targets the default branch, whereas the next PR targets the branch of the first PR, and so on.

  gitGraph
      commit id: "Initial commit"
      commit id: "Add user model"

      branch feature-1
      checkout feature-1
      commit id: "Add database schema"

      branch feature-2
      checkout feature-2
      commit id: "Add user controller"

      branch feature-3
      checkout feature-3
      commit id: "Add validation logic"

      checkout main
      commit id: "Other team changes" type: HIGHLIGHT

Once the first PR of such a stack is landed, the second PR has to target the default branch.

  gitGraph
      commit id: "Initial commit"
      commit id: "Add user model"
      commit id: "Other team changes" type: HIGHLIGHT

      commit id: "Add database schema"

      branch feature-2
      checkout feature-2
      commit id: "Add user controller"

      branch feature-3
      checkout feature-3
      commit id: "Add validation logic"

To simplify the work of administering such a stack, we opt for the tool stack-pr.

Why

Based on a few common understandings, we decided to implement a workflow based on stacked PRs.

Common understandings

  • The author of a PR owns it and strives to land it quickly.
  • The reviewers do the PR author a favour. The author therefore tries to make reviewing as easy as possible.
  • Shorter PRs are easier to review, and the reviews of shorter PRs are more helpful and trustworthy.

Advantages of this seemingly convoluted workflow are:

  • Faster reviews: Smaller, focused PRs are quicker to review and approve, reducing feedback cycles
  • Higher quality: Reviewers provide better feedback on smaller changesets; easier to spot issues
  • Unblocked development: Continue building on top of pending PRs instead of waiting for approval

Support only implemented in mono repo lyceum-tech/lyceum

Help like Hymenaeus is only implemented in our main repo lyceum-tech/lyceum. Other repos have smaller code bases and the effort of stacked PRs might not be worth it.