reviewpatch

Feel free to drop us an email for anything: hello AT reviewpatch.org

Please use GitHub Issues and Discussions to communicate publicly.

reviewpatch - a code review tool based on the patch workflow | Product Hunt

Introduction

reviewpatch is a code review tool based on the patch workflow. Instead of relying on plain-text emails, reviewpatch provides a Web-based user interface for developers to collaborate with each other. Under the hood it still uses such commands as git-format-patch and git-am to be compatible with virtually any existing git setups.

The patch workflow is significantly different in many aspects from the pull request workflow which is arguably more popular. See comparisons below.

Patch Workflow Pull Request Workflow
A series of patches forms a patchset. Patches are amended with improvements in a new version of the patchset. Improvements are added in follow-up commits. Existing commits remain unchanged.
Does not rely on a central git server. Read-only access is sufficient for contributors. Requires a central git server with write permissions given to contributors.
Supports a pipeline-like development model and reduces self merge conflicts. Inflexible 1:1 correspondence between a topic branch and a pull request.
Possible compatibility with non-git tools to manipulate patches locally. Tied to a particular version control tool such as git.

The diagram below illustrates the dataflow related to reviewpatch users. rp is a command-line tool provided as part of reviewpatch. It helps you manage patches and sync them with the server side.

  1. Contributors pull latest changes from the main repository and rebase local changes on the top.
  2. rp create automatically finds the commits between HEAD and the current branch's upstream branch (set via git branch -u) and uploads git-format-patch outputs to the reviewpatch server.
  3. Peer developers could review the uploaded patchsets in the browser. Explicit approvals are to be given by the reviewers via the Web interface.
  4. Once a patchset is approved, a maintainer could apply it locally and push it to the upstream.
  5. When the contributor pulls again, the ahead commits would be rebased by git automatically and the current branch becomes clean.
To get started, read Client Installation, Server Installation, and/or Quickstart.

System Requirements

Both the client and the server require a recent version of Fedora or Ubuntu. macOS binaries are available upon request but are unsupported for now. At run-time the binaries require some dynamic libraries. It also requires git to be in the $PATH.

To install the run-time dependencies on Fedora:

# dnf update
# dnf install git openssl-libs zlib

To install the run-time dependencies on Ubuntu:

# apt-get update && apt-get install git libssl1.1 zlib1g

reviewpatch does not need an external database for state persistence.

Client Installation

Download rpcli_${os_label}.tar.gz from the releases directory. Inside the tarball there is an executable named rpcli.

If you are a system administrator and would like to install it for all users, just copy it to /usr/local/bin:

% sudo cp rpcli /usr/local/bin/rp

If you are installing it for yourself, rename and copy it to ~/.local/bin/rp and make sure it is in your $PATH.

Server Installation

Download rpsrv_${os_label}.tar.gz from the releases directory. Extract the tarball to a directory dedicated to running the reviewpatch server. As an example, we use /opt/reviewpatch as the working directory. In addition, please also create a dedicated user (e.g. rpsrv) for running the server. The server does not need root permissions.

% tar xvf rpsrv_${os_label}.tar.gz -C /opt/reviewpatch

Test Mode

To try it out without much setup, just run it from the chosen working directory:

% cd /opt/reviewpatch
% ./rpsrv --test-mode
By default it binds to localhost and listens on port 9999. Open http://localhost:9999 to see what it looks like. Also use this as the endpoint in .rpconfig.json.

Production Mode

For security reasons, the reviewpatch server must be placed behind a reverse proxy in production mode. User authentication is delegated to the reverse proxy, and the reviewpatch server takes the value of an HTTP header as the current username. For example:

% ./rpsrv --username-header "X-Remote-User"
Similarly, TLS encryption (e.g. HTTPS) and many other things should also be handled by the reverse proxy. We recommend using the Apache HTTP Server (i.e. httpd) as the reverse proxy but you may also use NGINX. Here is a sample configuration file for httpd.

We also recommend using systemd to manage the reviewpatch server as a systemd service. Create a file at /etc/systemd/system/rpsrv.service with the following contents:

[Unit]
Description=reviewpatch server
Requires=network.target

[Service]
Type=simple
ExecStart=/opt/reviewpatch/rpsrv --username-header "X-Remote-User"
User=rpsrv
WorkingDirectory=/opt/reviewpatch

[Install]
WantedBy=multi-user.target
A data file would be created at /opt/reviewpatch/reqlog.json. Change the above WorkingDirectory config to save it elsewhere.

Quickstart

Let's assume that your project's git repository is located at https://yoursite/repo.git and you cloned it into $HOME:

% cd ~
% git clone https://yoursite/repo.git my-project && cd my-project
% git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean
Please note the highlighted line: git clone has already set the tracking upstream for you. To start working on something, create a topic branch with:
% git checkout -tb my-topic origin/master
In the topic branch, git commits can be created, edited, and cherry-picked as usual. For example:
% echo Hi > hello
% git add hello
% git commit -m "add the hello file"
% git status
On branch my-topic
Your branch is ahead of 'origin/master' by 1 commit.

Client Configuration

Before we could do anything with reviewpatch, the project needs to be configured locally so that the rp command knows where the reviewpatch server is. Simply create a JSON file under the project root directory:

% echo '{"endpoint":"http://address:port"}' > .rpconfig.json
Please reach out to your system administrator to get the appropriate endpoint information. If you followed Server Installation to run the server in test mode, use http://localhost:9999 as the endpoint.

Authentication

In production mode, reviewpatch server's Web interface is protected by the reverse proxy. In test mode, the Web interface is unprotected and the current authenticated user is hard-coded to be testuser.

In both modes, the rp command-line interface uses API keys for authentication. Run the following command to generate a key pair:

% rp keygen username
The command should prompt you to save the public key via the reviewpatch server's Web interface. Ask your system administrator if you are unsure about what username to use. If you followed Server Installation to run the server in test mode, use testuser as the username.

Run the following command to validate your setup:

% rp whoami
username

Creating A Code Review

When the patches in the topic branch are ready, create a code review with:

% rp create
Created code review https://....../cr/42/1/1
The command looks for git commits that are not in this topic branch's tracking upstream, and sends them as a series of patches (i.e. a patchset) to the server. The server returns a numeric ID (e.g. 42) for the code review. Code review URLs contain strings in the form of cr/x/y/z where x is the numeric ID, y is the patchset version, and z is the patch index.

To learn more about the rp command, run:

% rp --help

Release Notes

The version numbers do not have significant meanings. They are merely used to differentiate various development iterations. For example, think of 1.0 as in Linux kernel 1.0, which does not necessarily imply any stableness or quality guarantees. We try our best to make sure that existing data files always work under new versions so that system administrators do not have to worry too much about upgrades and migrations.

1.0

October 5, 2021

This is the first released version of reviewpatch. We have been dogfooding it for several months and it seems to work good enough to meet our needs. Improvements related to CI and static analysis will be released when they are ready.