10.nixos-hardware/CONTRIBUTING.md

Contributing a Device Profile

Please submit your contributions from a feature branch, not from your master branch:

git checkout -b my-new-hardware-profile

1. Writing profiles

Create an appropriate directory and start writing your expression.

When setting an option, use lib.mkDefault unless:

• The option must be set and the user should get an error if they try to override it.
• The setting should merge with the user's settings (typical for list or set options).

For example:

{ lib }: {
  # Using mkDefault, because the user might want to disable tlp
  services.tlp.enable = lib.mkDefault true;
  # No need to use mkDefault, because the setting will merge with the user's setting
  boot.kernelModules = [ "tmp_smapi" ];
}

Where possible, use module imports to share code between similar hardware variants. In most cases, import:

• a cpu module;
• a gpu module;
• either the pc or the laptop module;
• either the HDD or the SSD module.

Try to avoid "opinionated" settings relating to optional features like sound, bluetooth, choice of bootloader etc. You can mention these in the readme.

Profiles should favor usability and stability, so performance improvements should either be conservative or be guarded behind additional NixOS module options. If it makes sense to have a performance-focussed config, it can be declared in a separate profile.

2. Optional: Add a README

Profiles can include a README.md with device-specific documentation such as:

• Firmware update instructions
• BIOS settings
• Known issues and workarounds
• Links to external resources

See framework/13-inch/7040-amd/README.md for a good example.

3. Adding Entry

Add your profile to both README.md and flake.nix.

README.md: Add a row to the table in alphabetical order by manufacturer:

| [Manufacturer Model](manufacturer/model)    | `<nixos-hardware/manufacturer/model>`    | `manufacturer-model`    |

The columns are:

1. Model name linking to the profile directory
2. Channel path (for imports = [ <nixos-hardware/...> ])
3. Flake module name (for nixos-hardware.nixosModules.<name>)

flake.nix: Add an entry to the nixosModules attribute set:

manufacturer-model = import ./manufacturer/model;

The flake module name should use hyphens (e.g., dell-xps-15-9500).

4. Multiple Variants

For devices with multiple configurations (e.g., different GPU options), create subdirectories with a shared base module. For example:

dell/xps/15-9560/
├── default.nix          # Base profile (or one default variant)
├── intel/default.nix    # Intel-only variant
├── nvidia/default.nix   # Nvidia variant
└── xps-common.nix       # Shared configuration

Each variant needs its own entry in README.md and flake.nix:

dell-xps-15-9560 = import ./dell/xps/15-9560;
dell-xps-15-9560-intel = import ./dell/xps/15-9560/intel;
dell-xps-15-9560-nvidia = import ./dell/xps/15-9560/nvidia;

5. Testing

Before opening a pull request, test your profile by pointing to your fork.

Using channels:

sudo nix-channel --add https://github.com/<github-user>/nixos-hardware/archive/<branch>.tar.gz nixos-hardware
sudo nix-channel --update
sudo nixos-rebuild test

Using flakes:

Update your flake.nix input temporarily:

inputs.nixos-hardware.url = "github:<github-user>/nixos-hardware/<branch>";

Then run:

sudo nixos-rebuild test --flake .

You can also run nix run .#run-tests to evaluate all hardware profiles. Because profiles can only be tested with the appropriate hardware, quality assurance is up to you.

Compatibility

Profiles should work with both NixOS unstable and the current stable release.

Deprecating Modules

When renaming or removing a module, add deprecation warnings for both flake and channel users.

For flake users, use the deprecated helper in flake.nix:

old-module-name = deprecated "issue-number" "old-module-name" (import ./new/path);

For channel users, add an assertion in the old module's default.nix:

{ ... }:

{
  assertions = [
    {
      assertion = false;
      message = "Importing path/to/old/module (default.nix) directly is deprecated! See https://github.com/NixOS/nixos-hardware/blob/master/path/to/DEPRECATION.md for more details";
    }
  ];
}

Include a markdown file explaining the migration path. See asus/zephyrus/ga402x/ATTR-SET-DEPRECATION.md for an example.

Getting Help

For questions and discussions, join us in the #nixos-hardware:nixos.org Matrix channel.

For reviewers:

Any nixpkgs committer can review and approve pull requests in this repository.

This repository uses GitHub merge queues for merging pull requests.

Review checklist

1. README.md entry: Verify the contribution adds the device to the table in README.md
2. flake.nix entry: Verify the profile is exposed in flake.nix
3. Common profiles: Since testing on real hardware isn't always possible, check that the profile re-uses appropriate common profiles (e.g., cpu, gpu, laptop/pc, ssd/hdd modules)
4. Previous contributors: For changes to existing profiles, consider requesting feedback from previous contributors who may have access to the hardware