Skip to content

Commit

Permalink
Improve contributor documentation
Browse files Browse the repository at this point in the history
- Move all that was in README.md to CONTRIBUTING.md
  README.md is only for user documentation
- Expand it to mention recent additions
  • Loading branch information
infinisil committed Apr 18, 2024
1 parent ff3553e commit a227284
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 51 deletions.
69 changes: 69 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Contributor documentation

[@infinisil](https://github.com/infinisil) is the admin and main developer of this repository,
while everybody in [@NixOS/nixpkgs-check-by-name](https://github.com/orgs/NixOS/teams/nixpkgs-check-by-name) has write access.

## Development

Enter the development environment in this directory either automatically with
[`direnv`](https://github.com/direnv/direnv) or manually with
```bash
nix-shell
```

The most important tools and commands in this environment are:
- [rust-analyzer](https://rust-analyzer.github.io/) to have an IDE-like experience for your own editor.
- Running tests:
```bash
cargo test
```
- Linting and formatting:
```bash
cargo clippy --all-targets
treefmt
```
- Running the [main CI checks](./.github/workflows/main.yml) locally:
```bash
nix-build -A ci
```

### Integration tests

Integration tests are declared in [`./tests`](./tests) as subdirectories imitating Nixpkgs with these files:
- `default.nix`:
Always contains
```nix
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
```nix
self: super: {
# ...
}
```
allowing the simulation of package overrides to the real [`pkgs/top-level/all-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix).
The default is an empty overlay.

- `base` (optional):
Contains another subdirectory imitating Nixpkgs with potentially any of the above structures.
This is used to test [ratchet checks](./README.md#ratchet-checks).

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

## Automation

Pinned dependencies are [regularly updated automatically](./.github/workflows/update.yml).

Releases are [automatically created](./.github/workflows/release.yml) when the `version` field in [`Cargo.toml`](./Cargo.toml)
is updated from a push to the main branch.
53 changes: 2 additions & 51 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
This directory implements a program to check the [validity](#validity-checks) of the [`pkgs/by-name` Nixpkgs directory](https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name).
This is part of the implementation of [RFC 140](https://github.com/NixOS/rfcs/pull/140).

This code in this repository was originally [part of Nixpkgs](https://github.com/NixOS/nixpkgs/commits/55bf02190ee57fcf83490fd7b6bf7834e28c9c86/pkgs/test/nixpkgs-check-by-name), but has since been [moved into this separate repository](https://github.com/NixOS/nixpkgs/issues/286559).
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for contributor documentation.
Below is the user documentation.

To see how it is used in Nixpkgs, see the [`check-by-name.yml` workflow](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/check-by-name.yml).

[@infinisil](https://github.com/infinisil) is the admin and main developer of this repository, while everybody in [@NixOS/nixpkgs-check-by-name](https://github.com/orgs/NixOS/teams/nixpkgs-check-by-name) has write access.

## Interface

Expand Down Expand Up @@ -52,52 +52,3 @@ The current ratchets are:
(see [nix evaluation checks](#nix-evaluation-checks)) must not be introduced.
- New top-level packages defined using `pkgs.callPackage` must be defined with a package directory.
- Once a top-level package uses `pkgs/by-name`, it also can't be moved back out of it.

## Development

Enter the development environment in this directory either automatically with `direnv` or with
```
nix-shell
```

Then use `cargo`:
```
cargo build
cargo test
cargo fmt
cargo clippy
```

## Tests

Tests are declared in [`./tests`](./tests) as subdirectories imitating Nixpkgs with these files:
- `default.nix`:
Always contains
```nix
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.

- `all-packages.nix` (optional):
Contains an overlay of the form
```nix
self: super: {
# ...
}
```
allowing the simulation of package overrides to the real [`pkgs/top-level/all-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix).
The default is an empty overlay.

- `base` (optional):
Contains another subdirectory imitating Nixpkgs with potentially any of the above structures.
This is used for [ratchet checks](#ratchet-checks).

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

0 comments on commit a227284

Please sign in to comment.