At Bit Complete we write a lot of code, and we love GitHub's tooling for browsing and managing our source code. But we find that the workflow and UI around pull requests and code review doesn't quite cut the mustard.
The GitHub PR user experience is designed for code authors, rather than code reviewers. As a code author, your main concern is getting your code from your local development environment into a deployed product as quickly as possible. GitHub's UI is designed primarily for this use case.
Unfortunately that goal doesn't align very well with code quality. High-quality code is best written in an environment that fosters high-quality code reviews, and reviewing code effectively sometimes requires structuring code changes in a way that reviewers can understand. In short, code authors need to be encouraged to think like reviewers, and our tools should make that as easy as possible.
The best code review tools are well known to Google and Facebook engineers who use them everyday via internal applications with dedicated teams running their source control servers, but that doesn't help those of us who use cloud solutions out in the harsh cold world. There are also some open source tools that solve aspects of this problem, such as Gerrit and Phabricator, but in our experience they are painful to deploy and manage, and they lack support.
Code reviews are very important to us. So we created a tool for those of us who live outside the FAANG bubble. We all should have access to easier and faster code review workflows and UX.
plz.review integrates with your GitHub repos. It provides a familiar but more optimized UI for viewing code changes and providing feedback. It enables a different workflow for creating “reviewable units” of the code you intend to merge. Our primary user is the reviewer. Making their experience better leads to happier senior developers, more meaningful code reviews, and a healthier codebase. It’s also for authors, making it easier to see, respond to, and resolve pieces of feedback from a review. And we find that usage leads to changes in author behaviour that encourage thoughtful PR construction and improve a repo’s commit history.
Here are three big ways our tool makes my job as a code reviewer easier and addresses areas where GitHub falls short:
1. Tell me what PRs need my attention
Working at a software development agency, I tend to work in a bunch of different repositories, but most of the GitHub UI centers around a specific repository, so it’s hard to quickly get a handle on those PRs that require my attention right now. Even within a specific repository it’s hard to form a quick picture of what PRs need my input:
The GitHub homepage seems like a great place to surface pull requests that need my attention across all my repos, but most of what I see there is stuff that recently got merged:
With plz.review we put your tasks as a reviewer front and center by showing you all of the PRs that require your feedback in a dedicated view that’s easily accessible from the site navigation.
By default you can see everything across all of your repos, but you can also drill down by org, repo, PR status, author, and reviewer. Throughout the day as I have some free time I open the My Feedback page and can quickly figure out what PRs need my input.
2. Show me what happened to a PR since my last review
When I come back to a review on which I’ve already given feedback, what I really need to know is “what changed since I was last here”. While GitHub does give a comprehensive timeline, it tends to get cluttered with a lot of pushes and PR events that I don’t really care about:
What I really want to see is how/whether the author addressed the comments that I made and the relevant diffs. Pulling this information out of GitHub usually involves a lot of figuring out what commits are relevant and zeroing in on those, and it’s a hassle.
plz.review introduces the idea of “revisions” which are simply snapshots of a review at a point in time. Behind the scenes a revision corresponds to a set of commits, but as a reviewer I don’t usually care to look at the individual commits because they generally represent bookkeeping from the author’s local Git repo.
When I’m coming back to a PR in plz.review I can quickly figure out what’s changed, and look at the diffs relative to my last feedback to understand how the author addressed my comments.
3. Encourage small PRs
Large PRs that compose multiple logical code changes are difficult to review, so for the reviewers’ sake it’s important to try to keep PRs small and focused. I find it much easier to review three small changes that each do one thing vs. one large change that does three things. Ideally a code review tool makes it easy to manage multiple small PRs.
In GitHub, the unit of code review is the pull request, and a PR encapsulates a full Git branch from the author. When my branch is the only means to package up code changes, the temptation is to push more and more changes to that branch throughout the review cycle.
A great code review tool should help the code author organize their work into reviewable chunks that aren’t going to become obsolete as the author continues to code and respond to feedback.
At Bit Complete we love the concept of stacked diffs which allow a code author to prepare reviewable diffs while continuing to work on top of those changes. In our development team, stacks are crucial to working effectively, so in plz.review, stacked PRs are at the core of the product.
To create and manage stacks, we've created an open source command line tool called plz. By combining the CLI with your usual Git workflow, you can manage multiple PRs that depend on one another in the form of a stack of commits:
In the UI you can quickly navigate this stack using the stack dropdown in the footer navbar.
Expect to see more iteration on stacks as a tool for organizing code changes. We think there’s a ton more to do to make these workflows better for all involved.
plz try it!
Currently plz.review is available for use on personal repos, so go ahead and give it a try. Here’s the complete documentation. And if you run into an issue, report it!
If you’d like to try plz.review for your GitHub organization, plz let us know. We are currently onboarding teams and we’d love your feedback.
