Chunked PR workflow

The goal of this workflow is to make PR review more manageable.

History

Previously, we had issues with PRs becoming too large and almost un-reviewable. So we decided to split a given Linear ticket into as many chunks as possible, then produce smaller PRs and hopefully make the review experience better. But our first attempt at this was not perfect and we still have things to adjust:

• review expectations were not clear, e.g.:
  • reporting issues that were already fixed in later chunks existing PRs
  • reviewing code that would no longer exist in the final version
  • reporting issues that were intentionally put aside at the current stage
• testing was not fully completed, ending up in several regressions when merging everything into the develop branch
• observability for the product manager was not optimal (constant back and forth between “on review” and “in progress” statuses)

Latest guidelines

Common case

1. We create a new branch from develop and name it after the ticket (e.g. feature/ENG-123)

2. We break down the feature/ENG-123 into smaller, manageable chunks:

   • feature/ENG-123.1 (first chunk of work)
   • feature/ENG-123.2 (second chunk of work)
   • feature/ENG-123.3 (third chunk of work)

3. For each chunk:

   • create a new branch from the main feature branch (feature/ENG-123)
   • implement the changes with one or more commits
   • open a pull request back to the main feature branch (feature/ENG-123)

4. Once a chunk’s PR is reviewed and approved:

   • squash and merge the chunk branch into feature/ENG-123
   • delete the chunk branch

5. Repeat steps 3-4 for each remaining chunk until all work is completed

6. Once all chunks are merged into feature/ENG-123:

   • open a final pull request from feature/ENG-123 to develop
   • the purpose of this final pull request is only to test the feature and ensure that there are no uncovered edge cases or regressions

Complex Example

Here’s an example of a relatively complex workflow while working on a hypothetical ENG-123 ticket:

Notice that while the feature/ENG-123.1 branch is in review, the developer starts working on the next chunk (feature/ENG-123.2) and finishes it before feature/ENG-123.1 is reviewed. In this case, rather than opening the pull request pointing at feature/ENG-123, the developer must open it pointing at feature/ENG-123.1 instead.

Then, they must wait for feature/ENG-123.1 to be merged into feature/ENG-123 before merging feature/ENG-123.2 into feature/ENG-123 as well.

For feature/ENG-123.3, the flow is more straightforward as there are no other overlapping chunks.

Finally, before merging into develop, a final PR provides room for in-depth testing and last-minute corrections.