NixOS Contribution and Review Guidelines

# NixOS NixOS is a Linux distribution based on the purely functional package management system Nix. More information can be found at https://nixos.org/nixos and in the manual in doc/manual. ## Testing changes You can add new module to your NixOS configuration file (usually it’s `/etc/nixos/configuration.nix`). And do `sudo nixos-rebuild test -I nixpkgs=<path to your local nixpkgs folder> --fast`. ## Commit conventions - Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole. - Format the commit messages in the following way: ``` nixos/(module): (init module | add setting | refactor | etc) (Motivation for change. Link to release notes. Additional information.) ``` Examples: * nixos/hydra: add bazBaz option Dual baz behavior is needed to do foo. * nixos/nginx: refactor config generation The old config generation system used impure shell scripts and could break in specific circumstances (see #1234). ## Reviewing contributions When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people’s installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra. ### Module updates Module updates are submissions changing modules in some ways. These often contains changes to the options or introduce new options. Reviewing process: - Ensure that the module maintainers are notified. - The continuous integration system will make GitHub notify users based on the submitted changes, but it can happen that it misses some of the package maintainers. - Ensure that the module tests, if any, are succeeding. - You may invoke OfBorg with `@ofborg test <module>` to build `nixosTests.<module>` - Ensure that the introduced options are correct. - Type should be appropriate (string related types differs in their merging capabilities, `loaOf` and `string` types are deprecated). - Description, default and example should be provided. - Ensure that option changes are backward compatible. - `mkRenamedOptionModuleWith` provides a way to make renamed option backward compatible. - Use `lib.versionAtLeast config.system.stateVersion "24.05"` on backward incompatible changes which may corrupt, change or update the state stored on existing setups. - Ensure that removed options are declared with `mkRemovedOptionModule`.

This document introduces NixOS, a Linux distribution built on the Nix package manager, and provides guidelines for contributing to it. It covers how to test local changes, specifies commit message conventions for various types of modifications (e.g., `nixos/(module): (action)`), and details the review process for contributions. Special emphasis is placed on the careful review of bootloader changes due to their irreversible nature. For module updates, the review process includes notifying maintainers, ensuring tests pass, verifying the correctness and backward compatibility of new or changed options (including type, description, and examples), and proper handling of renamed or removed options.