Share
Explore

plz.review one pager

Powerful workflows for code reviews
Plz Review is a tool that streamlines the code review process for teams.
We view code reviews as one of the most important areas in the development process. When done well, code review can be less a chore and more a way to encourage code quality and health, create a sense of shared responsibility and ownership, and help mentor other developers. We feel ill-served by the current products on the market, specifically by GitHub’s PR model and workflow. And using an alternative today requires a prohibitive investment for setup and maintenance of our own source code infrastructure.
plz.review connects to your GitHub account [or org] and then provides a command line utility and web interface for managing your PRs, and the PRs you’ve been asked to review. It aims to be a vastly more pleasant experience over using GitHub directly for PR and review management.
A better code workflow experience leads to happier developers, better reviews, and a better codebase.
Current state of the world / problems solved
Teams that don’t run their own code/git hosting infrastructure use GitHub (or competitors) for storing and versioning their code
If they use GitHub, the use Pull Requests (PRs) to manage their changes and get them reviewed (ideally).
Managing PRs and code reviews solely in GH is a drag
The interface is “fine” but requires browser extensions to power up (namely, keyboard shortcuts)
Doesn’t show you the “right” diffs: e.g. as a reviewer it’s difficult to see diffs since your last comment
Notifications are not at the right level of granularity and difficult to manage
The GitHub PR model of development encourages large changes since it’s difficult to manage “chains” of related changes
This is one of core concerns and areas to try to improve
I can’t easily track PRs and reviews across multiple repos.
What do I have in progress? What is waiting for my feedback/LGTM? There is no centralized dashboard for PRs.
Gerrit and Phabricator (see below) appear to solve many of these problems with an improved workflow and UX, but they require in-house git instances and are a pain to set up and maintain, requiring a large investment from an IT or devops team. We’d aim to isolate the “review” pieces from these systems and map them to GH via their api’s.
we want to bring this feature set to git-as-a-service users.
seems like the closest thing to what we’re trying to do (Gerrit tooling on top of GH repos) but with a nicer and more modern UX

Key Terms to Define
Pull Request (PR): A set of changes to a git repository hosted on GitHub, to be merged into a target branch.
Review: Feedback from peers on a PR. Commonly includes comments tied to files and/or line numbers. Should lead to either an approval to merge, or the closing of that PR.
Root review
Parent review
Revision: A snapshot of the code at time of review. Can be made up of one or many commits.
TODO
Commit:
Merge:
Rebase:
Other products’ terms:
Patch Set
Changelist

Prior Art
GitHub PR Reviews
And similarly GitLab, Bitbucket
Google powered code review
Mondrian (internal), which evolved into
Critique (internal), which was open sourced as
we are trying to use the Gerrit workflow, mapped on to GH
FB powered code review
Reviewable
Jetbrains thing
GitHub “apps” that allow for more grunular review: (TODO: add names)

Distinguishing features (planned)
“Stacked Reviews” or “Review Chains”
This is already done in Gerrit. We will apply this model to GH repos.
A very nice UI: simple, fun, utilitarian
A consolidated view of
my authored PRs across repos
my PRs to review across repos

Example flow for a review
User creates a new review with some changes
We notify the reviewer(s) via preferred mode with a link to the web UI
Reviewer goes to site and is presented a pleasing interface for reviewing codes, which they do with efficiency
They ask for a few changes and present a couple questions, some tied to a line of code, some tied to a file, some tied to the entire review.
Author is notified by preferred mode, sees a quick summary of the comments/questions.
They open their branch, make the requested changes, and run > plz sync.
They reply to the reviewer’s questions in the web UI. Replying resolves the comment by default.
They click a checkbox that marks all remaining comments as resolved.
Git Workflows
PRs
The simplest workflow is to use to improve your GitHub review workflow. Once is configured for your GitHub repositories, each PR will have a corresponding review. You can get to the new review by navigating to it on or clicking through the link from the PR:
image.png
CLI
also provides a CLI for managing reviews from your local Git repo.
We prompt for some info: reviewer handles, title/description, what else?
We sync the branch to the remote origin and create a PR in GH, and present the author with their link
Note that the CLI is completely optional and is mainly provides shorthands for juggling multiple branches/PRs.
Review Chains
Suppose you have a couple of changes locally that you want to be reviewed independently:
commit 1b6f01fd0a87f78b3d1cd55f3e796dbd77ebf4c5 (HEAD -> fix-abhorrent-bug)
Author: Dylan Trotter <dylan@bitcomplete.io>
Date: Sun Dec 6 13:49:19 2020 -0500

Fix the managed merge bug

commit ee4a5d2ec6f20b8ed1e1111d7e2da09bf684b546
Author: Dylan Trotter <dylan@bitcomplete.io>
Date: Sun Dec 6 12:17:55 2020 -0500

Refactor the merge button

commit 8cd4ef4c6c1ca71e5d65fd310122fa4b075a7a14 (master, origin/master)
Author: lyndonoc <lyndonoc@gmail.com>
Date: Wed Dec 2 02:46:13 2020 -0500

Frontend integration for review description update
Normally this feature branch would be a single PR with two commits, or you could create two PRs but then you need to juggle two branches.
Assuming CLI plz installed on system and you have a clean git index, run: plz review now looking at git log you’ll see:
commit 58916a1220289add8ef952e45184f48707f0b210 (HEAD -> fix-abhorrent-bug, origin/plz.review/r/353236)
Author: Dylan Trotter <dylan@bitcomplete.io>
Date: Sun Dec 6 13:49:19 2020 -0500

Fix the managed merge bug

plz.review: https://plz.review/r/353236

commit 7db0c2ff07f70d9fc8257e9d8dbd18f6d2226744 (origin/plz.review/r/353235)
Author: Dylan Trotter <dylan@bitcomplete.io>
Date: Sun Dec 6 12:17:55 2020 -0500

Refactor the merge button

plz.review: https://plz.review/r/353235
Several things have happened:
Each commit has been tagged with a plz.review containing the short review URL
Each commit is mapped to a remote branch like origin/plz.review/r/123 which is the corresponding PR’s head branch
You can now amend these commits locally and upload new revisions by running plz review.
Handling Conflicts
When conflicts arise, the UI will not help you resolve them. Instead, you should either:
Use the GH UI to resolve the conflicts. This is accomplished by adding commits to the PR, entirely through the GH web UI. The PR changes will be reflected in plz.review.
Resolve conflicts locally using the Git CLI in the usual fashion, and then re-upload the changes.
How exactly does a review relate to a GH PR?
A review corresponds to a GitHub PR one-to-one. Changes to the PR are reflected in the review. For example, if a user uploads new commits to a PR, those changes are seen as a new revision in plz.review.
What do we sync back to GH?
TODO, but we will attempt to mirror back to GH whenever possible to try to keep PR state updated.
Web UI
The web UI will provide a few key views:
Review List
This is a list of PRs ー either my own, my list of PRs to review, a list of open PRs on a project, or someone else’s list of PRs. Lots of ways to filter/organize and present these review lists.
A given list will have rows of reviews, which would include:
PR Title, Date created, Author, Reviewers, Review State, Number of comments (or latest comment metadata), etc
Example that we can improve upon:
Review
A list of files with code changes, to be reviewed by a peer. The review contains or consists of the following primitives:
Title and Description
Other metadata: author, reviewers, review state, references to source GitHub PR
Actions: publish or merge if author, publish or approve if reviewer
Commits
File list, with diff metadata and links to diff views
Round of Feedback
Comments
Views of previous comments
Text input / form for adding new comments.
Note: Comments can be added at the line level within a file (about the diff), at the file level (about the file as a whole), or at the review level (about the whole PR)

Examples that we can improve upon:

File Diffs
All the code changes for a given file, presented as a list of diffs.
A diff is... one set of lines of code in any given file, with some amount of surrounding code context. We refer to these as “hunks” sometimes. For later: we could also show individual diffs in an alternate presentation (ie, divorced from their parent file context).

TODO: add examples from GitHub for each of these views

There will also be a Settings view both for the project (adding/removing repos) and for the user (setting notifications and other prefs).

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.