Feel free to drop us an email for anything: hello AT reviewpatch.org
Please use GitHub Issues and Discussions to communicate publicly.
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.
HEAD
and the current branch's upstream branch (set via git branch -u) and uploads git-format-patch outputs to the reviewpatch server.
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.
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
.
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
To try it out without much setup, just run it from the chosen working directory:
% cd /opt/reviewpatch % ./rpsrv --test-modeBy 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.
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.targetA data file would be created at
/opt/reviewpatch/reqlog.json
. Change the above WorkingDirectory config to save it elsewhere.
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/masterIn 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.
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.jsonPlease 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.
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 usernameThe 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
When the patches in the topic branch are ready, create a code review with:
% rp create Created code review https://....../cr/42/1/1The 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
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.
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.