zimbatm / nix-review

Review pull-requests on https://github.com/NixOS/nixpkgs

nix-review

Review pull-requests on https://github.com/NixOS/nixpkgs. nix-review automatically builds packages changed in the pull requests

Features

• ofborg support: reuses evaluation output of CI to skip local evaluation, but also fallbacks if ofborg is not finished
• automatically detects target branch of pull request
• provides a nix-shell with all packages, that did not fail to build
• remote builder support
• allows to build a subset of packages (great for mass-rebuilds)
• allow to build nixos tests
• colorful output
• markdown reports
• logs per built or failed package
• symlinks build packages to result directory for inspection

Installation

nix-review is included in nixpkgs.

To use it run without installing it, use:

$ nix run nixpkgs.nix-review

To install it:

$ nix-env -f '<nixpkgs>' -iA nix-review

To run it from the git repository:

$ nix-build
$ ./result/bin/nix-review

Development Environment

For IDEs:

$ nix-build -A env -o .venv

or just use:

./bin/nix-review

Usage

Change to your local nixpkgs repository checkout, i.e.:

cd ~/git/nixpkgs

Note that your local checkout git will be not affected by nix-review, since it will use git-worktree to perform fast checkouts.

Then run nix-review by providing the pull request number...

$ nix-review pr 37242

... or the full pull request url:

$ nix-review pr https://github.com/NixOS/nixpkgs/pull/37242

The output then looks as follow:

$ git fetch --force https://github.com/NixOS/nixpkgs pull/37242/head:refs/nix-review/0
$ git worktree add /home/joerg/git/nixpkgs/.review/pr-37242 1cb9f643480612696de93fb2f2a2f3340d0e3156
Preparing /home/joerg/git/nixpkgs/.review/pr-37242 (identifier pr-37242)
Checking out files: 100% (14825/14825), done.
HEAD is now at 1cb9f643480 redis: 4.0.7 -> 4.0.8
Building in /tmp/nox-review-4ml2epyy: redis
$ nix-build --no-out-link --keep-going --max-jobs 4 --option build-use-sandbox true <nixpkgs> -A redis
/nix/store/jbp7m1gshmk8an8sb14glwijgw1chvvq-redis-4.0.8
$ nix-shell -p redis
[nix-shell:~/git/nixpkgs]$ /nix/store/jbp7m1gshmk8an8sb14glwijgw1chvvq-redis-4.0.8/bin/redis-cli --version
redis-cli 4.0.8

To review a local commit without pull request, use the following command:

$ nix-review rev HEAD

Instead of HEAD also a commit or branch can be given.

To review uncommited changes, use the following command:

$ nix-review wip

Staged changes can be reviewed like this:

$ nix-review wip --staged

Remote builder:

Nix-review will pass all arguments given in --build-arg to nix-build:

$ nix-review pr --build-args="--builders 'ssh://[email protected]'" 37244

As an alternative one can also specify remote builder as usual in /etc/nix/machines or via the nix.buildMachines nixos options in configuration.nix. This allows to parallelize builds across multiple machines.

Github api token

In case your IP exceeds the rate limit, github will return an 403 error message. To increase your limit first create a personal access token. Then use either the --token parameter of the pr subcommand or set the GITHUB_OAUTH_TOKEN environment variable.

$ nix-review pr --token "5ae04810f1e9f17c3297ee4c9e25f3ac1f437c26" 37244

Checkout strategy (recommend for r-ryantm + cachix)

By default nix-review pr will merge the pull request into the pull request's target branch (most commonly master). However at times mass-rebuilding commits have been applied in the target branch, but not yet build by hydra. Often those are not relevant for the current review, but will significantly increase the local build time. For this case the --checkout option can specified to override the default behavior (merge). By setting its value to commit, nix-review will checkout the user's pull request branch without merging it:

$ nix-review pr --checkout commit 44534

Only building a subset of packages

To build only certain packages use the --package (or -p) flag.

$ nix-review pr -p openjpeg -p ImageMagick 49262

There is also --package-regex option that takes a regular expression to match against the attribute name:

# build only linux kernels but not the packages
$ nix-review pr --packages-regex 'linux_' 51292

-p and --package-regex can be used together in which case the matching packages will merged.

Running tests

NixOS tests can be run by using the --package feature and our nixosTests attribute set:

$ nix-review pr -p nixosTests.ferm 47077

Ignoring ofborg evaluations

By default, nix-review will use ofborg's evaluation result if available to figure out what packages need to be rebuild. This can be turned off using --eval local, which is useful if ofborg's evaluation result is outdated. Even if using --eval ofborg, nix-review will fallback to local evaluation if ofborg's result is not (yet) available.

Review changes in personal forks

Both the rev and the wip subcommand support a --remote argument to overwrite the upstream repository URL (defaults to https://github.com/NixOS/nixpkgs). The following example will use the mayflower nixpkg's fork to fetch the branch where the changes will be merged into:

nix-review --remote https://github.com/mayflower/nixpkgs wip

Note that this has been not yet implemented for pull requests i.e. pr subcommand.

Roadmap

• trigger ofBorg builds (write @GrahamcOfBorg build foo into pull request discussion)
• build on multiple platforms
• test backports
• show pull request description + diff during review

Run tests

Just like nix-review also the tests are lightning fast:

$ python3 -m unittest discover .

We also use python3's type hints. To check them use mypy:

$ mypy nix_review

Related projects:

• nox-review:
  • works but is slow as a snail: the checkout process of nox-review is slow since it requires multiple git fetches. Also it cannot make use of ofborg's evaluation
  • it only builds all packages without providing a nix-shell for review
• niff:
  • only provides a list of packages that have changed, but does not build packages
  • also needs to evaluate changed attributes locally instead of using ofborg