prr is a tool that brings mailing list style code reviews to Github PRs.
This means offline reviews and inline comments, more or less.
To that end, prr introduces a new workflow for reviewing PRs:
The tool was born of frustration from using the point-and-click editor text boxes on PRs. I happen to do a lot of code review and tabbing to and from the browser to cross reference code from the changes was driving me nuts.
Install prr:
Option 1: Install rust toolchain (if you haven't already): https://rustup.rs/
sh
$ cargo install prr
Option 2: Homebrew
sh
$ brew install prr
Create a Github Personal Access Token (PAT) for prr:
prr will need this token so it can make GH API calls on your behalf.
Create the token by going to Settings -> Developer settings -> Personal
access tokens -> Generate new token and give the token repo permissions.
Keep the newly generated token handy for the next step.
Create a prr config file:
```sh $ mkdir -p ~/.config/prr
$ cat << EOF > ~/.config/prr/config.toml [prr] token = "$YOURPATFROMLASTSTEP" workdir = "/home/dxu/dev/review" EOF ```
where $YOUR_PAT_FROM_LAST_STEP is the PAT token from step 3 and workdir
is the directory you want prr to place all your review files.
Review your first PR:
Feel free to test prr out against my test repository, by the way.
```sh $ prr get danobi/prr-test-repo/6 /home/dxu/dev/review/danobi/prr-test-repo/6.prr
$ vim /home/dxu/dev/review/danobi/prr-test-repo/6.prr
$ prr submit danobi/prr-test-repo/6 ```
For details on how to actually mark up the review file, see the next section titled "Features"
Description: PR-level review comment. You only get one of these per review.
Syntax: Non-whitespace, non-quoted text at the beginning of the review file.
Description: Inline comment attached to a specific line of the diff.
Syntax: None-whitespace, non-quoted text on a newline immediately following a quoted non-header part of the diff.
Description: Like an inline comment, except it covers a span of lines.
Syntax: To start a span, insert one or more newlines immediately before a quoted, non-header part of the diff. To terminate a span, insert a inline comment.
Description: Meta-directives to give to prr in review comment. Currently
only supports approving, requesting changes to, and commenting on a PR.
Syntax: @prr approve, @prr reject, or @prr comment.
"Vim integration" is a bit overselling it, but I've created some ftdetect
and syntax configs to enable syntax highlighting for prr review files.
It can be pretty hard to look at a diff without having deletes and additions highlighted in different colors.
prr supports various configuration options spread over one or more config
files. The global config file must be located at $XDG_CONFIG_HOME/prr/config.toml.
This typically expands to $HOME/.config/prr/config.toml.
prr also supports local config files. Local config files must be named
.prr.toml and will be searched for starting from the current working
directory up every parent directory until either the first match or the root
directory is hit. Local config files override values in the global config.
Table specific semantics are documented below.
The [prr] table controls installation wide settings.
prr.token: Personal authentication token (required)prr.workdir: Directory to place review files (optional)prr.url: URL to github API (optional)If this table is specified in a local config file, it must be fully specified and will override the global config file.
The [local] table contains configuration local to a directory and its
sub-directories.
local.repository: A string in format of ${ORG}/${REPO} (optional)
${ORG}/${REPO} from PR string arguments.
For example, you may run prr get 6 instead of prr get danobi/prr/6.This table may not be specified in both a local config file and the global config file.