Contributor documentation

May 18, 2026 ยท View on GitHub

@philiptaron and @wolfgangwalther are admins of this repository, while everybody in @NixOS/nixpkgs-ci has write access, as well as @willbush.

Development

Enter the development environment in this directory either automatically with direnv or manually with

nix-shell

The most important tools and commands in this environment are:

  • rust-analyzer to have an IDE-like experience for your own editor.

  • Running tests:

    cargo test

  • Formatting:

    treefmt

  • Linting:

    cargo clippy --all-targets

    Optionally, check out extra lints or uncomment them at the top of main.rs.

    cargo clippy --all-targets -- -W clippy::nursery -W clippy::pedantic

  • Running the main CI checks locally:

    nix-build -A ci

Integration tests

Integration tests are declared in ./tests as subdirectories imitating Nixpkgs with these files:

  • main: A Nixpkgs root directory with:

    • default.nix: Always contains

      import <test-nixpkgs> { root = ./.; }

      which makes

      nix-instantiate <subdir> --eval -A <attr> --arg overlays <overlays>

      work very similarly to the real Nixpkgs, just enough for the program to be able to test it.

    • pkgs/by-name: The pkgs/by-name directory to check.

    • pkgs/top-level/all-packages.nix (optional): Contains an overlay of the form

      self: super: {
  # ...
}

      allowing the simulation of package overrides to the real pkgs/top-level/all-packages.nix. The default is an empty overlay.

  • base (optional): Contains another Nixpkgs root directory with potentially any of the above structures. This is used to test ratchet checks.

  • expected (optional): A file containing the expected standard output. The default is expecting an empty standard output.

    This file is matched against the error almost literally, with the only exception being that the @REDACTED@ string can match anything, which is useful for non-deterministic errors.

Automation

Pinned dependencies are regularly updated automatically.

Releases are automatically created when the release PR (created by Knope) is merged.

User-facing changes should be documented for inclusion in the changelog and release notes, either via changesets or conventional commits.