Improving on the GitHub code review comment experience

July 05, 2022· by Dylan Trotter

Code reviews are really just conversations about code changes. That’s why when we set about building plz.review we knew that great review comment functionality was going to be at the core of the product. There are a bunch of limitations with the conversation experience in GitHub that had always bothered us and we felt we could do better. Here are a few of the ways that the plz.review comment and conversation UX is a big improvement over GitHub.

Comments without boundaries

One bothersome thing about GitHub comments is that you can only leave them near the diffs introduced by the author. But sometimes you want to call attention to something outside of those diffs, elsewhere in the file you’re looking at. In plz.review it’s possible to comment anywhere in any of the files in the PR. Here’s an example:

Comment in plz

To make this comment available in GitHub, we provide a rollup in the top-level review comment that includes a brief snippet, along with a link that will take you straight to the comment in plz.review:

Comment rollup in GitHub

GitHub also imposes restrictions on what commits within a PR you can comment on. For example after a force push, you can no longer make review comments on code pushed in prior commits. In plz.review we impose no such restrictions. You can comment on any revision of the PR you wish at any time, and those comments are always present in the plz timeline, or by navigating to the relevant revision:

Comment on older revision in plz

No comment left behind

When code reviews become long, with many discussions, it’s often a sign that there are important conversations happening. The GitHub pull request timeline view provides an important way to track and contribute to these conversations, but when there are “too many” comments in a particular review, GitHub collapses them by hiding most of the comments behind a “load more” button:

GitHub hidden comments

It’s a hassle to have to click to reveal these conversations, but more importantly, in an already busy timeline it’s easy to miss these collapsed conversations. At best this increases review turnaround time, and at worst it could leave important comments unaddressed.

In plz.review the timeline centers around reviews happening on the PR, showing each round of feedback and including all its comments in chronological order. This way you can quickly tell which conversations are still unresolved and which ones need more input:

plz timeline comment

GitHub comment interoperability

Since we released plz.review a little over a month ago we’ve received a bunch of really useful feedback from teams we’ve onboarded. One thing we heard consistently was that full adoption within the team would take some time and that some members would likely continue using GitHub for a while. It’s important to be able to review on GitHub and respond on plz.review, and vice versa.

We took this feedback to heart and implemented full comment interoperability. For example, here’s a comment made from plz.review:

plz mirrored comment

And here’s the same comment in GitHub:

GitHub mirrored comment

Things like comment edits, deletion and resolve state are all mirrored in both places, regardless of whether they happen in GitHub or in plz. The feedback so far has been really positive, and we’re excited that teams will be able to onboard more incrementally.

Try plz.review for yourself!

We think the comment experience in plz.review is a big improvement over GitHub, but give it a try and let us know what you think.

If you’d like to try plz.review for your GitHub organization, plz join the waitlist. We are currently onboarding teams and we’d love your feedback.


Latest posts