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.
- 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.
- Diff: A set of changes between revisions / commits.
- We bundle diffs by file.
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.
- 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.
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.