The Theatre of Pull Requests and Code Review
Meks McClure · September 23, 2025
I recently attended the Goatmire Elixir Conf and one of the standout talks for me was Saša Jurić's "Tell Me a Story". It was an incredible presentation that combined theatrical storytelling with practical technical advice. Saša performed parts of his talk in character, turning technical topics into a compelling narrative that was part comedy, part tragedy, and fully packed with useful insights I've started implementing myself. The recording will eventually be released online for viewing. I highly recommend that people watch it, and I'll endeavor to add a link to it here when it becomes available.
The Code Review Challenge
The talk focused on Code Review and Pull Requests (PRs). Saša laid out common problems most software engineers face. Too often, engineers dread code reviews even though they're a significant part of team collaboration. We avoid them because PRs tend to be too large, too complex, too difficult to comprehend, and too painful to test. So we end up commenting "Looks Good To Me" and suggesting a few minor styling improvements to give the appearance of a thorough review.
This is how security leaks happen and codebases become progressively unmaintainable. Since git blame only points to the original author, it's easy to think "if something goes wrong, it's not on me". But we're all responsible for the whole system, regardless of who wrote the individual lines of code.
What Makes a PR Reviewable?
So how do we review something that feels unreviewable? Saša advocates for normalizing the practice of returning difficult-to-understand PRs to the author. This makes logical sense, but it's challenging to implement because it can feel like admitting we're not smart enough to understand the code. However, saying "I don't understand this enough to approve it" is far more valuable than pretending with an empty "LGTM".
If we commit to only reviewing truly reviewable PRs, what does that look like? According to Saša, it should take the average reviewer 5-10 minutes. By 'average reviewer,' he means mid-to-senior developers who understand the domain, business, and tech stack well—not newcomers still learning the system or mythical 10x engineers.
How do you create a PR that can be reviewed in 5-10 minutes? By reducing the scope. A full feature should often be multiple PRs. A good rule of thumb is 300 lines of code changes - once you get above 500 lines, you're entering unreviewable territory.
Telling a Story with Commits
A key part of having a reviewable PR is writing commits that tell a story. Present your changes incrementally and logically so reviewers can follow your thought process. Generic commit messages such as "add dependency," "implement file upload feature," and "address PR feedback" don’t tell much of a story and leave reviewers guessing. Why was the dependency added? What were the specific steps in creating the file uploader feature? What feedback is being addressed?
Story-Telling Commit Messages
After a toast to the demo gods, Saša demonstrated writing story-telling commits with a live coding example, creating a PR that was part of a larger feature. His example PR adds just 152 lines of code, removes 2 lines, but uses 13 thoughtful commits.
While some developers might understand those 152 lines from the final diff alone, I couldn't confidently approve it without the commit story.
Breaking Down the Example
For instance, looking at the overall diff, I didn't understand why he added :runtime_tools to applications in mix.exs . Following the commit narrative, it's clear this was needed for access to :scheduler.get_sample() to collect the samples. Now I can research that context or ask more pointed questions.
The Iterative Process
A huge benefit of seeing this live was witnessing the iterative process. In the compute average utilization commit, we initially saw an incorrect implementation that computed averages of all schedulers, including offline ones. When testing revealed unexpected results, Saša went back and updated both the code and the commit that originally implemented that function so the story remained coherent.
A flow that I find to work well for keeping commit history clean is with fixup commits. A fixup is a small commit that’s explicitly marked to be folded into an earlier commit during an interactive rebase. When you run rebase with autosquash, Git automatically pairs each fixup with its target and tucks the changes into the right place, keeping the story coherent without manual reordering.
I sometimes experience creating merge conflicts for myself during this process. Both Saša and I agree that if it becomes too much effort to resolve the conflict, then creating a new commit is ok. Taking the time to put in extra effort to keep the commit history clean and the story coherent makes the PR easier for reviewers to understand.
The Value of Clean History
Keeping the commit history clean connects to advice I've heard about ensuring every commit compiles and keeps the application runnable. I used to follow this loosely, but recent experiences with git bisect emphasized to me its importance. (If you are unfamiliar with git bisect , it's worth checking out; it uses a binary search algorithm to find which commit in your project's history introduced a bug.)
There are a few factors that make narrowing down when and how a regression was introduced more challenging. If a commit doesn't compile, I can't isolate whether the bug first appeared there. If the bug appeared in a commit that had hundreds of lines of code changed, determining which part of the commit is the issue requires significantly more reasoning. A clean commit history with messages that tell a story makes these kinds of investigations easier.
Making Review a Collaborative Success
When we present focused PRs with commits that tell clear stories, we get feedback sooner and our development cycles speed up. When reviewers understand our changes, we're more likely to receive valuable feedback instead of blanket approvals, and we're more likely to ship quality code. When our commits make sense, we can travel back in time as needed to understand how our codebase evolved.
Thanks to Saša's theatrical lesson, I will be more intentional about crafting commit stories. The next time you're preparing a PR, consider: Are you telling a story your reviewers can follow? Start small - maybe focus on just one aspect, like keeping PRs under that 300-line guideline or writing more descriptive commit messages. Your future reviewers (and your future debugging self) will thank you.
Resources