A quick tl;dr guide for people who are already familiar with Pull Requests
|
Pull Request Workflow |
Stacked Diff Workflow |
|
 |
 |
| Concept |
- Code evolves in one dimension:
|
- Code evolves in two dimensions:
- "No functionality" → "Functionality A, B, and C"
- "First attempt" → "Released version"
|
| Commands |
commit to move down the list
|
commit to move downamend to move right
|
| Unit of code review |
- Often the whole PR, viewing just the end result, to avoid reviewing code from "Add new API" which was then deleted in "fix bug in server"
- Individual commits available if you want to see a specific bug get fixed.
- Client and server code reviews are all-or-nothing - No nice way to review "just the server" or "just the client"
- Unless the developer splits it into two separate pull requests, but then there's no record that the client depends on the server
- Or the developer does
commit --amend and push --force to create one server commit and one client commit, with each of those two commits evolving separately over time... at which point congratulations, you've invented a more-complicated and less-useful stacked diff workflow :D
|
- Client and server reviewed separately
- But linked to show that client depends on server
- By default viewing "current version of client" and "current version of server"
- With the ability to see what changed between eg "Add API (Version 1)" and "Add API (Version 2)" if you want to see a specific bug get fixed.
- The client can be reviewed and approved first, but it can't land until after the server diff lands.
- If for some reason you really want client and server to be reviewed as a single unit, you still have the possibility to submit them as a single diff
|
| Unit of merge |
- Client and server are merged into the main branch in one go
- Unless you cherry-pick individual commits, but this is error-prone
|
- Server and client can be landed together with the "merge stack" button, or the server can be landed first with the "merge diff" button
- The client can't be merged until after the server is there.
|
| Unit of history |
- 5 commits in the history
- Unless you do an interactive rebase to squash after code review is finished, but then what gets released doesn't match what was reviewed
|
- 1 commit for "Add new API to server (v3)" and 1 commit for "Make use of new API in client (v2)"
- Old discarded attemps (eg the buggy "Add new API to server (v1)") aren't in the main branch, but are still visible in the code review tool
|
|
|
|
