The Theatre of Pull Requests and Code Review By Meks McClure · September 23, 2025 --- Overview Meks McClure attended the Goatmire Elixir Conf, where a highlight was Saša Jurić’s talk, "Tell Me a Story". The presentation mixed theatrical storytelling with practical advice on code reviews and pull requests (PRs), showing how to make these processes more effective and engaging. --- The Code Review Challenge Code reviews and PRs are often dreaded due to their size, complexity, and difficulty in understanding. Reviews deteriorate into superficial "Looks Good To Me" comments or minor style suggestions. This leads to security issues and unmaintainable codebases. There's a shared responsibility among developers, beyond just the original authors of code. --- What Makes a PR Reviewable? Difficult PRs should be sent back to the author rather than approved without understanding. A reviewable PR is one that can be thoroughly reviewed in 5-10 minutes by an average, mid-to-senior level developer familiar with the domain. Large scope PRs should be split into smaller, more focused pieces. A good size guideline: around 300 lines of code; over 500 lines is generally too large. --- Telling a Story with Commits Commits should form a logical, incremental story for reviewers to follow. Avoid generic commit messages like "add dependency" or "address PR feedback" which lack clear context. Good commit messages explain the rationale and steps of changes. Story-telling Commit Messages Example Saša’s example PR (link) shows 152 lines changed over 13 structured commits. This breakdown helps reviewers understand why changes were made, e.g., adding :runtimetools to access a specific function. The Iterative Process Saša demonstrated fixing and refining commits after testing revealed issues. Use fixup commits to cleanly amend earlier commits during interactive rebases (git rebase --autosquash). It’s sometimes acceptable to create new commits when resolving conflicts becomes too complex. Clean commit histories and coherent stories ease reviewers’ understanding. The Value of Clean History Every commit should compile and keep the application runnable. This practice facilitates tools like git bisect, which helps track when a bug was introduced. Large, inconsistent commits complicate debugging. --- Making Review a Collaborative Success Focused PRs with clear commit stories speed up development cycles. Reviewers give better feedback, increasing code quality. Well-crafted commits enable easier codebase history navigation. Developers are encouraged to be intentional about crafting commit stories. Key question when preparing PRs: Are you telling a story your reviewers can follow? Start with small improvements: Keep PRs under 300 lines. Write descriptive, narrative commit messages. Your future self and colleagues will benefit. --- Resources Git blame — shows last modification per line Git rebase — cleans up commit history Git fixup — amends earlier commits Git bisect — finds when bugs were introduced --- Photo credits to Petter Boström*