A tool for enforcing code review requirements
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


orpa - a tool for enforcing code review requirements

Status: WIP; see TODO file.


Begin by making a file called MAINTAINERS. This file outlines the review requirements for various parts of your source tree. The format is: path glob, scrutiny level, number of required reviews, potential reviewers. For instance:

# All changes to Cargo.toml go through alice
Cargo.toml      !   1   alice

# Source files should be looked at by _someone_
src/*           !   1   alice,bob,charlie,daisuke

# Changes to the backend should be reviewed by two people
src/backend/*   !   2   alice,bob,charlie,daisuke

# Changes to protobuf schemas should be reviewed carefully
*.proto         !!  1   alice,charlie

Workflow example

Suppose Bob has been working on a branch ("bobs-feature") and wants to get it merged. orpa can tell us us whether a commit passes or not, given the rules defined in MAINTAINERS. Assuming "bobs-feature" is checked out, we get:

$ orpa status
The following requirements are unmet.
    src/*       !   1   alice,bob,charlie,daisuke
    src/*       !   1   alice,bob,charlie,daisuke
    *.proto     !!  1   alice,charlie,eddy

Looks like some of Bob's changes haven't been accepted, and he needs to get in touch with some maintainers to get their approval.

orpa can also tell us which branches require our approval. For instance, Alice would see this:

$ orpa todo
The following branches require review:

Suppose Alice has looked at the changes in the "my-feature" branch and is happy with them. She can approve them like so:

$ orpa approve bobs-feature:src/main.rs bobs-feature:src/schema.proto

Or, if "my-feature" is checked out, she can simply do:

$ orpa approve src/*

Alice pushes her approvals to "origin" like so:

$ orpa sync

And now "bobs-feature" is good-to-go!

$ orpa status bobs-feature
All changes approved


orpa status <branch> exits with status 0 if "branch" is accepted and 1 if not, so you can use it in a pre-recieve hook to enforce review policy.

A review at a high level of scrutiny (eg. "!!") satifies a requirement for a review at a lower level of scrutiny (eg. "!").

It's expected that reviewers will be referred to by short names (eg. "asayers") in the rules. In this case, it's probably a good idea to add a section to your MAINTAINERS files to let contributors know who do pester:

# alice     Alice Doe <alice@example.com>
# bob       Bob Smith <bob@example.com>

Approvals are stored in git-notes and committed to "refs/notes/orpa". If you're so inclined, you can look at the raw approvals data with git notes --ref=refs/notes/orpa show <blob>. "refs/notes/orpa" is synchronised with "origin" by orpa sync.