Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
325 lines (236 loc) · 13.3 KB

CONTRIBUTING.md

File metadata and controls

325 lines (236 loc) · 13.3 KB

Contributing to nix-installer

Most contributions should be made upstream; see the upstream contributing guide for guidelines.

In general, bugs should also be opened in the upstream issue tracker.

In some cases the Determinate Systems installer has made decisions that do not align with decisions of the official Nix installer, and in those cases, a contribution to this repo is appropriate.

Development

Some snippets or workflows for development.

Direnv support

While nix develop should work perfectly fine for development, contributors may prefer to enable direnv or nix-direnv support.

From the project folder:

direnv allow

If using an editor, it may be preferable to adopt an addon to enter the environment:

Code Formatting and Linting

This project uses treefmt for formatting.

nix fmt                                        # format all files
nix build .#checks.x86_64-linux.formatting     # check formatting
nix build .#checks.x86_64-linux.clippy         # run clippy

Testing Installs

If you're hacking on nix-installer, you likely already have Nix and cannot test locally.

That's probably a good thing! You should test in a sandbox.

Automated qemu tests exist and should be preferred for oneshot testing of changes.

For interactive testing, tools like libvirt via virt-manager or vagrant can be used to spin up machines and run experiments.

When running such interactive tests, consider creating a snapshot of the VM right before running the installer, so you can quickly roll back if something happens.

In general, it's a good idea to test on the closest you can get to the desired target environment. For example, when testing the Steam Deck planner it's a good idea to run that test in a Steam Deck VM as described in detail in the planner.

Adding a planner for specific hardware?

Please include an full guide on how to create the best known virtual testing environment for that device.

A link is not sufficient, it may break. Please provide a full summary of steps to take, link to any original source and give them credit if it is appropriate.

It's perfectly fine if they are manual or labor intensive, as these should be a one time thing and get snapshotted prior to running tests.

qemu VM tests

For x86_64 Linux we have some additional QEMU based tests. In nix/tests/vm-test there exists some Nix derivations which we expose in the flake via hydraJobs.

These should be visible in nix flake show:

❯ nix flake show
warning: Git tree '/home/ana/git/determinatesystems/nix-installer' is dirty
git+file:///home/ana/git/determinatesystems/nix-installer
# ...
├───hydraJobs
│   └───vm-test
│       ├───all
│       │   └───x86_64-linux
│       │       └───install-default: derivation 'all'
│       ├───fedora-v36
│       │   └───x86_64-linux
│       │       └───install-default: derivation 'installer-test-fedora-v36-install-default'
│       ├───rocky-v8
│       │   └───x86_64-linux
│       │       └───install-default: derivation 'installer-test-rocky-v8-install-default'
│       ├───rocky-v9
│       │   └───x86_64-linux
│       │       └───install-default: derivation 'installer-test-rocky-v9-install-default'
│       └───ubuntu-v22_04
│           └───x86_64-linux
│               └───install-default: derivation 'installer-test-ubuntu-v22_04-install-default'

To run all of the currently supported tests:

nix build .#hydraJobs.vm-test.all.x86_64-linux.all -L

To run a specific distribution listed in the nix flake show output:

nix build .#hydraJobs.vm-test.rocky-v8.x86_64-linux.all -L -j 4

You may wish to set -j 4 to some other number. Some OS's (Ubuntu 16.04) exhibit problems rapidly updating their users/groups on a system running dozens of VMs.

For PR review, you can also test arbitrary branches or checkouts like so:

nix build github:NixOS/nix-installer/${BRANCH}#hydraJobs.vm-test.ubuntu-v22_04.x86_64-linux.install-default -L
Adding a distro?

Notice how rocky-v8 has a v8, not just 8? That's so the test output shows correctly, as Nix will interpret the first -\d (eg -8, -123213) as a version, and not show it in the output.

Using v8 instead turns:

# ...
installer-test-rocky> Unpacking Vagrant box /nix/store/8maga4w267f77agb93inbg54whh5lxhn-libvirt.box...
installer-test-rocky> Vagrantfile
installer-test-rocky> box.img
installer-test-rocky> info.json
installer-test-rocky> metadata.json
installer-test-rocky> Formatting './disk.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=137438953472 backing_file=./box.img backing_fmt=qcow2 lazy_refcounts=off refcount_bits=16
# ...

Into this:

# ...
installer-test-rocky-v8-install-default> Unpacking Vagrant box /nix/store/8maga4w267f77agb93inbg54whh5lxhn-libvirt.box...
installer-test-rocky-v8-install-default> Vagrantfile
installer-test-rocky-v8-install-default> box.img
installer-test-rocky-v8-install-default> info.json
installer-test-rocky-v8-install-default> metadata.json
installer-test-rocky-v8-install-default> Formatting './disk.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=137438953472 backing_file=./box.img backing_fmt=qcow2 lazy_refcounts=off refcount_bits=16
# ...

Container tests

For x86_64 Linux we have some additional container tests. In nix/tests/container-test there exists some Nix derivations which we expose in the flake via hydraJobs.

These should be visible in nix flake show:

❯ nix flake show
warning: Git tree '/home/ana/git/determinatesystems/nix-installer' is dirty
git+file:///home/ana/git/determinatesystems/nix-installer
# ...
├───hydraJobs
│   ├───container-test
│   │   ├───all
│   │   │   └───x86_64-linux
│   │   │       ├───all: derivation 'all'
│   │   │       ├───docker: derivation 'all'
│   │   │       └───podman: derivation 'all'
│   │   ├───ubuntu-v18_04
│   │   │   └───x86_64-linux
│   │   │       ├───all: derivation 'all'
│   │   │       ├───docker: derivation 'vm-test-run-container-test-ubuntu-v18_04'
│   │   │       └───podman: derivation 'vm-test-run-container-test-ubuntu-v18_04'
│   │   ├───ubuntu-v20_04
│   │   │   └───x86_64-linux
│   │   │       ├───all: derivation 'all'
│   │   │       ├───docker: derivation 'vm-test-run-container-test-ubuntu-v20_04'
│   │   │       └───podman: derivation 'vm-test-run-container-test-ubuntu-v20_04'
│   │   └───ubuntu-v22_04
│   │       └───x86_64-linux
│   │           ├───all: derivation 'all'
│   │           ├───docker: derivation 'vm-test-run-container-test-ubuntu-v22_04'
│   │           └───podman: derivation 'vm-test-run-container-test-ubuntu-v22_04'

To run all of the currently supported tests:

nix build .#hydraJobs.container-test.all.x86_64-linux.all -L -j 4

You may wish to set -j 4 to some other number. Some OS's (Ubuntu 16.04) exhibit problems rapidly updating their users/groups on a system running dozens of VMs.

To run a specific distribution listed in the nix flake show output:

nix build .#hydraJobs.container-test.ubuntu-v22_04.x86_64-linux.docker -L

For PR review, you can also test arbitrary branches or checkouts like so:

nix build github:NixOS/nix-installer/${BRANCH}#hydraJobs.container-test.ubuntu-v22_04.x86_64-linux.podman -L
Adding a distro?

Notice how ubuntu-v20_02 has a v20, not just 20? That's so the test output shows correctly, as Nix will interpret the first -\d (eg -20, -123213) as a version, and not show it in the output.

Using v20 instead turns:

# ...
vm-test-run-container-test-ubuntu> machine # [   23.385182] dhcpcd[670]: vethae56f366: deleting address fe80::c036:c8ff:fe04:5832
vm-test-run-container-test-ubuntu> machine # this derivation will be built:
vm-test-run-container-test-ubuntu> machine #   /nix/store/9qb0l9n1gsmcyynfmndnq3qpmlvq8rln-foo.drv
vm-test-run-container-test-ubuntu> machine # [   23.424605] dhcpcd[670]: vethae56f366: removing interface
vm-test-run-container-test-ubuntu> machine # building '/nix/store/9qb0l9n1gsmcyynfmndnq3qpmlvq8rln-foo.drv'...
vm-test-run-container-test-ubuntu> machine # [   23.371066] systemd[1]: crun-buildah-buildah1810857047.scope: Deactivated successfully.
# ...

Into this:

# ...
vm-test-run-container-test-ubuntu-v18_04> machine # [   23.385182] dhcpcd[670]: vethae56f366: deleting address fe80::c036:c8ff:fe04:5832
vm-test-run-container-test-ubuntu-v20_04> machine # this derivation will be built:
vm-test-run-container-test-ubuntu-v20_04> machine #   /nix/store/9qb0l9n1gsmcyynfmndnq3qpmlvq8rln-foo.drv
vm-test-run-container-test-ubuntu-v18_04> machine # [   23.424605] dhcpcd[670]: vethae56f366: removing interface
vm-test-run-container-test-ubuntu-v20_04> machine # building '/nix/store/9qb0l9n1gsmcyynfmndnq3qpmlvq8rln-foo.drv'...
vm-test-run-container-test-ubuntu-v20_04> machine # [   23.371066] systemd[1]: crun-buildah-buildah1810857047.scope: Deactivated successfully.
# ...

WSL tests

On a Windows Machine with WSL2 enabled (and updated to support systemd) you can test using WSL the scripts in tests/windows:

.\tests\windows\test-wsl.ps1
.\tests\windows\test-wsl.ps1 -Systemd

If something breaks you may need to unregister the test WSL instance. First, look for the distro prefixed with nix-installer-test:

$ wsl --list
Windows Subsystem for Linux Distributions:
Ubuntu (Default)
nix-installer-test-ubuntu-jammy

Then delete it:

wsl --unregister nix-installer-test-ubuntu-jammy

You can also remove your $HOME/nix-installer-wsl-tests-temp folder whenever you wish.

Releases

Note

The documentation below describes a process that used to be mostly manual, and is now driven externally. The material below is generally kept up to date for documentation, manual releases, and external use purposes.

Versioning Scheme

This package follows the Nix project's versioning for major and minor version numbers:

  • Major.Minor: Matches the Nix version being installed (e.g., 2.33.x installs Nix 2.33)
  • Patch: Revision number for the installer itself (incremented for installer-specific changes)

This means version 2.33.0 is the first release of the installer for Nix 2.33, 2.33.1 would be a bugfix release, etc.

The check-version-consistency check in nix flake check verifies that the installer version's major.minor matches the Nix version in flake.nix.

You can use the check-semver command alias from within the development environment to validate your changes don't break semver.

To cut a release, run the GitHub Actions workflow propose-release.yml. Specify these parameters:

  • reference-id: provide a fresh UUID
  • version: in the X.Y.Z format. No leading v.
  • nix-version: The version of Nix to use in the flake.nix, in the format of X.Y.Z. No leading v.

This will:

  • Create a release branch from main (git checkout -b release-v0.0.1)

    • Release PRs should not contain any installer-related changes which require review

  • Ensure the flake.lock, Cargo.lock, and Rust dependencies are up-to-date with the following:

    • nix flake update --commit-lock-file
    • cargo update --aggressive
    • cargo outdated --ignore-external-rel --aggressive

  • Update the versions in the fixture data in test/fixtures/**/*.json

  • Open a pull request, where the GitHub Actions will run these tests:

    • nix flake check -L
    • nix build .#hydraJobs.container-test.all.x86_64-linux.all -L -j 6
    • nix build .#hydraJobs.vm-test.all.x86_64-linux.all -L -j 6

  • Once the PR tests pass and it has been reviewed, merge it.

  • Create a release / new tag named vX.Y.Z

    • Generate a changelog using the GitHub "make a changelog" button

  • CI will produce artifacts and upload them to the release

  • Once you are certain the release is good, cargo publish it

    • Warning: While you can re-release Github releases, it is not possible to do the same on crates.io

Who maintains nix-installer and why?

This fork is maintained by the community.

The upstream nix-installer is maintained by Determinate Systems in an effort to explore Nix installer ideas.

Determinate Systems has no plans to monetize or relicense nix-installer. If your enterprise requires a support contact in order to adopt a tool, please contact Determinate Systems and something can be worked out.