ofborg/README.md

# ofborg

## Guidelines

1. Review the code of all PRs before triggering the bot on them.
2. Be gentle; try not to run mass rebuilds or massive builds (like Chromium) on
   it.

## Automatic Building

All users will have their PRs automatically trigger builds if their commits
follow the well-defined format of Nixpkgs. Specifically: prefixing the commit
title with the package attribute. This includes package bumps as well as other
changes.

Example commit titles and the builds they will start:

| Message                                                               | Automatic Build                                          |
|-----------------------------------------------------------------------|----------------------------------------------------------|
| `vim: 1.0.0 -> 2.0.0`                                                 | `vim`                                                    |
| `vagrant: Fix dependencies for version 2.0.2 `                        | `vagrant`                                                |
| `python36Packages.requests,python27Packages.requests: 1.0.0 -> 2.0.0` | `python36Packages.requests`, `python27Packages.requests` |
| `python{2,3}Packages.requests: 1.0.0 -> 2.0.0`                        | _nothing_                                                |

When opening a PR with multiple commits, ofborg creates a single build job for
all detected packages. If multiple commits get pushed to a PR one-by-one, each
detected package will get a separate build job.

If the title of a PR begins with `WIP:`, contains `[WIP]` anywhere, or has the
`2.status: work-in-progress` label, its packages are not built automatically.
**Note**: Marking a PR as a draft does not prevent automatic builds.

## Commands

The comment parser is line-based, so commentary can be interwoven with
instructions for ofborg.

1. To trigger the bot, the line _must_ start with `@ofborg` (case insensitive).
   * **Note**: GitHub will not suggest `@ofborg` to you, but it will work all
     the same. When in doubt, preview your comment and verify that `@ofborg`
     links to https://github.com/ofborg/.
2. To use multiple commands, separate them with whitespace. For examples, see
   the "[Multiple Commands](#multiple-commands)" section.

### test

```
@ofborg test list of tests
```

This will run `nix-build ./nixos/release.nix -A tests.list -A tests.of -A
tests.tests` from the root of the Nixpkgs checkout.

Tests will run on all allowed machines. For more information, see the "[Trusted
Users](#trusted-users)" section.

### eval

```
@ofborg eval
```

See "[How does ofborg call
`nix-instantiate`?](#how-does-ofborg-call-nix-instantiate)" for what command(s)
this will run.

**Note**: Every PR automatically evaluates both upon creation and when the
commits change. There is no reason to run eval on a PR unless the evaluation
failed for weird reasons or master was previously broken.

### build

```
@ofborg build list of attrs
```

This will run `nix-build ./default.nix -A list -A of -A attrs` from the root of
the Nixpkgs checkout (see also "[How does ofborg call
`nix-build`?](#how-does-ofborg-call-nix-build)").

Builds will run on all allowed machines. For more information, see the "[Trusted
Users](#trusted-users)" section.

## Multiple Commands

You can use multiple commands in a variety ways. Here are some valid
combinations:

*
    ```
    @ofborg build list of attrs
    @ofborg eval
    ```

*
    ```
    @ofborg build list of attrs @ofborg eval
    ```

*
    ```
    looks good to me!
    @ofborg eval
    @ofborg build list of attrs
    ```

*
    ```
    @ofborg eval
    @ofborg build list of attrs
    looks good to me!
    ```

*
    ```
    @ofborg build list of attrs
    @ofborg test list of attrs
    ```

* This will build `list`, `of`, `attrs`, `looks`, `good`, `to`, and `me!` (which is probably not what you want):
    ```
    @ofborg build list of attrs looks good to me!
    ```

## Trusted Users

Trusted users have their builds and tests executed on _all_ available platforms,
including those without good sandboxing. Because this exposes the host to a
higher risk of security issues, the trusted users list consists of only
well-known, trusted members of the community.

At the time of writing, trusted users have their builds and tests run on these
platforms:

 - `x86_64-linux`
 - `aarch64-linux`
 - `x86_64-darwin`

See [`config.public.json`](./config.public.json) for a list of all trusted users.

# How does ofborg call `nix-build`?

ofborg runs builds with a command similar to the following:

```shell
$ HOME=/homeless-shelter NIX_PATH=ofborg-nixpkgs-pr=$(pwd) nix-build ./default.nix \
    -A hello \
    --no-out-link \
    --keep-going \
    --option restrict-eval true \ 
    --option build-timeout 1800 \ 
    --argstr system thesystem \
    --show-trace
```

# How does ofborg call `nix-instantiate`?

ofborg runs NixOS evals with a command similar to the following:

```shell
$ HOME=/homeless-shelter NIX_PATH=ofborg-nixpkgs-pr=$(pwd) nix-instantiate ./nixos/release.nix \
    -A manual \
    --option restrict-eval true \
    --option build-timeout 1800 \
    --argstr system thesystem \
    --show-trace
```

ofborg runs Nixpkgs evals with a command similar to the following:

```shell
$ HOME=/homeless-shelter NIX_PATH=ofborg-nixpkgs-pr=$(pwd) nix-instantiate ./pkgs/top-level/release.nix \
    -A manual \
    --option restrict-eval true \
    --option build-timeout 1800 \
    --argstr system thesystem \
    --show-trace
```

# Running meta checks locally

To run the meta checks, you will need the
[`outpaths.nix`](./ofborg/src/outpaths.nix) file. You can acquire this file and
run the checks themselves like so:

```shell
$ curl -o outpaths.nix https://raw.githubusercontent.com/NixOS/ofborg/released/ofborg/src/outpaths.nix
$ GC_INITIAL_HEAP_SIZE=4g nix-env -f ./outpaths.nix -qaP --no-name --out-path --arg checkMeta true > out-paths
```

# Hacking

```shell
$ git clone https://github.com/NixOS/ofborg/
$ cd ofborg
$ nix-shell ./shell.nix
$ cd ofborg # enter the subdirectory with Rust code
# make your changes
$ cargo build
$ cargo check
$ cargo test
```

To test whether or not Continuous Integration will pass with your changes, you
can run the following commands from the root of your checkout:

```shell
$ nix-shell --run checkPhase -A mozilla-rust-overlay # checks rustfmt and clippy
$ nix-shell --run checkPhase # runs the test suite
$ nix-build -A ofborg.rs # build ofborg
```

Currently there is no easy way to set up a test instance of ofborg. If `cargo
check` and `cargo test` both succeed, feel free to Pull Request your changes.
Make sure to format your code with `cargo fmt` and check for additional warnings
with `cargo clippy`. If you added, removed, or updated the dependencies, also be
sure to update Cargo.nix by running
[`./nix/update-crates.sh`](./nix/update-crates.sh).

To disable warnings as errors, run your command with an empty `RUSTFLAGS`. For
example:

```shell
$ RUSTFLAGS= cargo clippy
```

This will override the default of `-D warnings` set in
[`shell.nix`](./shell.nix), which tells Rust to error if it detects any
warnings.

# Running a builder

If you want to run a builder of your own, check out the [wiki page on operating
a builder](https://github.com/NixOS/ofborg/wiki/Operating-a-Builder/).