💫How to plz

You can use plz as much or as little as is useful for you and your team. It’s an additive layer that shouldn’t disturb existing GitHub workflows or PRs.

View our intro video for a walk-through of the web UI and CLI.

Key terms

• Review: Our main object of concern.

  • This connects directly to a GitHub Pull Request (PR). A review has an author, a reviewer, a merge status, source + target branches, etc.

• Stack: A set of connected reviews (GitHub PRs)

• Revision: An iteration on a review.

  • In the world of GitHub PRs, these might correspond with "commits."

  • We think of these as a snapshot of your code updates at a point in time. A revision can have comments tied to it, and top-level feedback.

  • A revision is a candidate for review. A revision can be automatically created if underlying code changes or needs conflict resolution.

  • Revisions can be compared to other revisions ("relativeTo"). This enables a diff.

  • There’s lots of good stuff about commits and git in this engineering blog post from GitHub about the terminology and ways to understand git's primitives.

• Diff: A set of changes between revisions / commits.

  • We bundle diffs by file.

Using plz.review for reviewing code only

This is the simplest use case, and the one closest to the usual GitHub pull request workflow where plz.review serves as a replacement for the GitHub code review UI.

Once plz.review has been installed on a given repository, you can use it to perform code reviews. There is no change to the usual GitHub PR workflow, the main advantage is an improved user experience for reviewing code. Here’s how it works:

• Open PRs in GitHub will get a message added with a link to plz for reviewing those PRs.

  
• PRs you create appear in plz.review as reviews in the “My Changes” page.

• When your teammates request a review, their PRs will appear in the “My Feedback” page.

• A PR consisting of multiple commits will show in plz.review as a single review with multiple revisions.

  • Think of revisions as snapshots; plz.review lets you display diffs between any two revisions (including the baseline) of a review.

• Comments left in plz.review are reflected back on the corresponding GitHub PR page.

The review summary page distills the PR into its most important information for review. You can navigate the file diffs that compose the review and leave comments on line numbers and files themselves.

Once these comments are drafted, you publish the collection of comments for resolution or further discussion. Resolving comments is front and center so authors and reviewers can easily see the state of their PR in its review lifecycle.

Next steps

• Install plz.review in your repositories.

• Learn how to accomplish specific UI tasks in the Web UI Basics page.

• Optimize your review experience using a growing list of Keyboard Shortcuts for navigating diffs and files.

Using the plz CLI to manage reviews

According to the plz philosophy, multiple small PRs are better than one large PR. But managing sequences of changes like these can be a headache, so we built the CLI to make that as easy as possible. With the CLI you can:

• Create a review from a Git commit.

• Push and pull Git state between your local repository and GitHub.

• Push, pull or visualize multiple related (”stacked”) PRs at once.

Keep in mind: Rebasing is a key concept when using the plz CLI.

The sequence of commits in your current branch is what creates a stack of PRs to review with plz. Understanding and using Git's native rebase workflow is important for managing this stack.

Next steps

• Install and auth the plz CLI locally to start playing around with it.

• Discover some basic CLI workflows in the CLI Basics page, including more on rebasing.

• Build a deeper understanding of the plz CLI, Git, and stacks in the CLI User Guide.