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.

⁠

http://gerrithub.io⁠

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

⁠

Gerrit⁠

→ we are trying to use the Gerrit workflow, mapped on to GH

⁠

https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html⁠

⁠

https://gerrit-review.googlesource.com/Documentation/⁠

⁠

FB powered code review

⁠

Phabricator⁠

Reviewable

Jetbrains thing

⁠

http://gerrithub.io/⁠

⁠

more...⁠

⁠

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.

“relation chains”

https://gerrit-review.googlesource.com/Documentation/concept-changes.html#related-changes⁠

⁠

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

plz.review⁠

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

plz.review⁠

to improve your GitHub review workflow. Once

plz.review⁠

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

plz.review,⁠

or clicking through the link from the PR:

⁠

CLI

⁠

plz.review⁠

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

plz.review⁠

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

trailer⁠

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

plz.review⁠

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:

https://gerrit-review.googlesource.com/q/status:open+-is:wip⁠

⁠

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:

⁠

https://gerrit-review.googlesource.com/c/gerrit/+/300704⁠

⁠

https://gerrit-review.googlesource.com/c/gerrit/+/299469⁠

⁠

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).

Example of this view:

https://gerrit-review.googlesource.com/c/gerrit/+/300704/2/polygerrit-ui/app/elements/core/gr-main-header/gr-main-header.js⁠

⁠

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.