Review Workflow

Review pull requests in NixOS/nixpkgs using nixpkgs-review.

When to Use

“review nixpkgs pr”
“nixpkgs-review pr”
“review pull request”
“test nixpkgs pr”

Quick Commands

Basic PR Review

# Review PR by number
nixpkgs-review pr 12345

# Review and post results to PR
nixpkgs-review pr 12345 --post-result

# Review specific packages only
nixpkgs-review pr 12345 -p package-name

Review Local Changes

# Review uncommitted changes
nixpkgs-review wip

# Review staged changes
nixpkgs-review wip --staged

# Review specific commit
nixpkgs-review rev HEAD

Ofborg Commands

# Trigger builds on PR (comment on GitHub)
@ofborg build package-name

# Run NixOS tests
@ofborg test test-name

# Re-evaluate (only if eval failed)
@ofborg eval

Setup

Install nixpkgs-review

# Run without installing
nix run nixpkgs#nixpkgs-review

# Install to profile
nix profile install nixpkgs#nixpkgs-review

# In development shell
nix-shell -p nixpkgs-review

GitHub Authentication

Required for posting results with --post-result:

# Method 1: GitHub CLI (recommended)
gh auth login

# Method 2: Environment variable
export GITHUB_TOKEN=ghp_...

# Method 3: hub configuration (~/.config/hub)
github.com:
- user: username
  oauth_token: token
  protocol: https

Review Workflow

Step 1: Fetch and Review PR

Multi-Architecture Testing (Recommended):

# Review PR on multiple architectures (preferred)
nixpkgs-review pr 12345 --system x86_64-linux,aarch64-linux --no-shell

# This provides better coverage and catches arch-specific issues
# Use --no-shell for non-interactive batch building

Single Architecture (Quick Test):

# Review PR on current system only
nixpkgs-review pr 12345

# This will:
# 1. Fetch the PR
# 2. Determine changed packages
# 3. Build all changed packages
# 4. Drop you into nix-shell with built packages

When to use multi-arch:

For packages that claim multi-platform support
When you have time for thorough review
For cross-platform packages (most packages)
On Linux systems (can build both x86_64 and aarch64)

When single-arch is OK:

Platform-specific packages (e.g., Linux kernel modules)
Darwin-only packages (when reviewing on macOS)
Quick sanity checks before detailed review

Step 2: Test Built Packages

In the nix-shell environment:

# Test the package works
package-name --version
package-name --help

# Check binary
which package-name
ls -la $(which package-name)

# For GUI applications
package-name &

# Check package structure
nix build .#package-name
tree result/

Step 3: Review Changes

While in nix-shell, examine the PR:

# View PR comments
nixpkgs-review comments

# Check file changes
git diff master...pr-branch

# Review package definition
cat pkgs/path/to/package/default.nix

Step 4: Approve or Request Changes

# In nix-shell: Approve if good
nixpkgs-review approve

# Exit shell
exit

# Or post results without approval
nixpkgs-review pr 12345 --post-result

Step 5: Merge (Maintainers Only)

For PRs labeled 2.status: merge-bot eligible, maintainers can request automated merge:

# Post comment on PR to trigger auto-merge
gh pr comment 12345 --body "@NixOS/nixpkgs-merge-bot merge"

# Or via web interface: comment "@NixOS/nixpkgs-merge-bot merge"

Requirements:

✅ You are listed as maintainer of ALL touched packages
✅ PR targets a development branch (master, staging, etc.)
✅ PR touches only files in pkgs/by-name/
✅ PR is approved OR opened by r-ryantm/committer
✅ You are a member of @NixOS/nixpkgs-maintainers

Use cases:

Simple version bumps for packages you maintain
Dependency updates for your packages
Low-risk changes to packages you maintain

Note: Sometimes GitHub gets stuck after enabling Auto Merge. Leave another approval to trigger the merge.

Example workflow:

# 1. Review PR
nixpkgs-review pr 12345

# 2. Test package
package-name --version

# 3. Approve (in nix-shell)
nixpkgs-review approve
exit

# 4. Trigger merge (if you're maintainer and PR is eligible)
gh pr comment 12345 --body "@NixOS/nixpkgs-merge-bot merge"

What to Check

1. Package Builds Successfully

No build errors
All outputs created
Dependencies resolved

2. Tests Pass

# Check if tests are enabled
nix show-derivation .#package-name | grep doCheck

# Tests run during build
# Watch for test failures in build output

3. Binary Works

# Can execute
package-name --version

# Shows help
package-name --help

# Runs without errors
package-name (basic functionality test)

4. Dependencies Correct

# Check runtime dependencies
ldd result/bin/package-name

# Should not have missing libraries
# Should use Nix store paths

5. Meta Attributes

Check package metadata:

# In package definition
meta = with lib; {
  description = "Clear, accurate description";
  homepage = "https://correct-url.com";
  license = licenses.mit;  # Correct license
  maintainers = with maintainers; [ username ];
  platforms = platforms.linux;  # Appropriate platforms
};

6. No Regressions

# Check dependent packages still build
nixpkgs-review pr 12345  # Builds dependents automatically

# Look for failed dependents in output

7. Code Quality

Follows Nix coding conventions
Uses appropriate builders (buildGoModule, rustPlatform, etc.)
No hardcoded paths
Proper use of fetchFromGitHub/fetchurl
Hash is correct (sha256/sha512)

Review Scenarios

Version Update PR

# Review version bump
nixpkgs-review pr 12345

# Check:
# - Version number updated correctly
# - Hash updated correctly
# - Tests still pass
# - No breaking changes
# - Changelog reviewed (if major update)

What to verify:

Version matches upstream release
Hash is correct (not placeholder)
Dependencies still compatible
No new runtime dependencies added without documentation

New Package PR

# Review new package
nixpkgs-review pr 12345 -p new-package

# Check:
# - Package name follows conventions
# - In correct location (pkgs/by-name/ preferred)
# - Meta attributes complete
# - License specified correctly
# - Maintainers added
# - Tests included (if applicable)
# - Description accurate

Package location rules:

Prefer pkgs/by-name/xx/package-name/package.nix
Two-letter prefix from package name
Must be top-level package
Cannot use specialized callPackage (python3Packages, etc.)

Security Update PR

# Review security update
nixpkgs-review pr 12345

# Check:
# - CVE mentioned in PR description
# - Version fixes vulnerability
# - All variants updated (if multiple)
# - Security advisory linked
# - Consider backport to stable

Breaking Change PR

# Review breaking change
nixpkgs-review pr 12345

# Check:
# - Breaking changes documented
# - Migration guide provided
# - Dependents tested
# - Release notes updated
# - Staged appropriately (staging branch)

Advanced Options

Review Specific Packages

# Build only specific packages
nixpkgs-review pr 12345 -p firefox chromium

# Build packages matching regex
nixpkgs-review pr 12345 --package-regex "python.*"

Cross-System Review

# Review for multiple systems
nixpkgs-review pr 12345 --system x86_64-linux,aarch64-linux

Non-Interactive Review

# Don't enter shell
nixpkgs-review pr 12345 --no-shell

# Run custom command
nixpkgs-review pr 12345 --run "nix-shell -p hello --run hello"

# Print results to stdout
nixpkgs-review pr 12345 --print-result

Sandbox Mode

# Protect HOME directory
nixpkgs-review pr 12345 --sandbox

Posting Results

Automatic Posting

# Post build report as PR comment
nixpkgs-review pr 12345 --post-result

# Requires GitHub authentication (see Setup)

The posted comment includes:

Build status (success/failure)
List of built packages
Build logs (if failed)
System information

Manual Comments

If --post-result doesn’t work:

Note which packages built successfully
Note any failures with error messages
Post manual comment on PR with findings
Include system (x86_64-linux, aarch64-linux, etc.)

Review Best Practices

Be constructive - Focus on helping improve the PR
Test thoroughly - Don’t just check if it builds
Check license - Ensure license matches upstream
Verify platforms - Check claimed platforms are correct
Run the binary - Actually execute the program
Check description - Should be clear and accurate
Review commit message - Should follow conventions
Check for TODOs - Ensure no placeholder comments
Approve quickly - Don’t block good PRs unnecessarily
Be respectful - Remember there’s a human behind the PR

Common Issues

Build Failures

# Keep build directory on failure
nixpkgs-review pr 12345 --keep-going

# View build logs
nix log .#package-name

# Show full trace
nixpkgs-review pr 12345 --show-trace

Hash Mismatches

Common in updates:

# Correct hash shown in error
# Copy the "got:" hash to package definition
hash = "sha256-AAAA...";  # Wrong
hash = "sha256-BBBB...";  # Correct (from error)

Missing Dependencies

# Check what's missing
ldd result/bin/program

# Add to buildInputs or nativeBuildInputs
nativeBuildInputs = [ pkg-config ];
buildInputs = [ libfoo ];

Test Failures

# If tests fail but package works
# Suggest disabling tests with comment:
doCheck = false;

# Or skip specific tests
checkPhase = ''
  runHook preCheck
  pytest -k "not failing_test"
  runHook postCheck
'';

Batch Review

For reviewing multiple PRs:

# Review multiple PRs
for pr in 12345 12346 12347; do
  nixpkgs-review pr $pr --no-shell --post-result
done

# Or in parallel (careful with resources!)
parallel nixpkgs-review pr {} --no-shell --post-result ::: 12345 12346 12347

Using Ofborg

Ofborg is the nixpkgs CI bot that automatically builds and tests packages.

Automatic Checks

Ofborg runs automatically on every PR:

ofborg-eval: Validates Nix expressions
ofborg-eval-check-maintainers: Verifies maintainers exist
ofborg-eval-check-meta: Ensures meta attributes present
ofborg-eval-darwin: Checks macOS builds
ofborg-eval-nixos: Checks NixOS builds

Check ofborg results in the PR “Checks” tab.

Triggering Manual Builds

Comment on the PR to trigger ofborg:

# Build specific package
@ofborg build package-name

# Build multiple packages
@ofborg build package1 package2

# Run NixOS tests
@ofborg test nginx

# Re-evaluate (only if eval failed)
@ofborg eval

# Multiple commands
@ofborg build firefox @ofborg test firefox

Interpreting Results

Green checkmark (✓): Build succeeded Red X (✗): Build failed - click “Details” for logs Orange dot: Skipped (broken/unsupported platform)

When to Use Ofborg

Use @ofborg build:

Test on platforms you don’t have (aarch64, darwin)
Verify complex dependency changes
After fixing build failures

Use @ofborg test:

After changing NixOS modules
Verify service configurations
After updating packages that tests depend on

Integration with nixpkgs-review

nixpkgs-review automatically uses ofborg evaluation results:

# Uses ofborg's evaluation if available
nixpkgs-review pr 12345

# Force local evaluation
nixpkgs-review pr 12345 --eval local

This saves time by reusing ofborg’s work on determining changed packages.

Review Workflow

When to Use

Quick Commands

Basic PR Review

Review Local Changes

Ofborg Commands

Setup

Install nixpkgs-review

GitHub Authentication

Review Workflow

Step 1: Fetch and Review PR

Step 2: Test Built Packages

Step 3: Review Changes

Step 4: Approve or Request Changes

Step 5: Merge (Maintainers Only)

What to Check

1. Package Builds Successfully

2. Tests Pass

3. Binary Works

4. Dependencies Correct

5. Meta Attributes

6. No Regressions

7. Code Quality

Review Scenarios

Version Update PR

New Package PR

Security Update PR

Breaking Change PR

Advanced Options

Review Specific Packages

Cross-System Review

Non-Interactive Review

Sandbox Mode

Posting Results

Automatic Posting

Manual Comments

Review Best Practices

Common Issues

Build Failures

Hash Mismatches

Missing Dependencies

Test Failures

Batch Review

Using Ofborg

Automatic Checks

Triggering Manual Builds

Interpreting Results

When to Use Ofborg

Integration with nixpkgs-review

Resources