nixos/README.md

   1 # NixOS
   2
   3 NixOS is a Linux distribution based on the purely functional package
   4 management system Nix.  More information can be found at
   5 https://nixos.org/nixos and in the manual in doc/manual.
   6
   7 ## Testing changes
   8
   9 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`.
  10
  11 ## Commit conventions
  12
  13 - Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
  14
  15 - Format the commit messages in the following way:
  16
  17   ```
  18   nixos/(module): (init module | add setting | refactor | etc)
  19
  20   (Motivation for change. Link to release notes. Additional information.)
  21   ```
  22
  23   Examples:
  24
  25   * nixos/hydra: add bazBaz option
  26
  27     Dual baz behavior is needed to do foo.
  28   * nixos/nginx: refactor config generation
  29
  30     The old config generation system used impure shell scripts and could break in specific circumstances (see #1234).
  31
  32 ## Reviewing contributions
  33
  34 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.
  35
  36 ### Module updates
  37
  38 Module updates are submissions changing modules in some ways. These often contains changes to the options or introduce new options.
  39
  40 Reviewing process:
  41
  42 - Ensure that the module maintainers are notified.
  43   - [CODEOWNERS](https://help.github.com/articles/about-codeowners/) will make GitHub notify users based on the submitted changes, but it can happen that it misses some of the package maintainers.
  44 - Ensure that the module tests, if any, are succeeding.
  45   - You may invoke OfBorg with `@ofborg test <module>` to build `nixosTests.<module>`
  46 - Ensure that the introduced options are correct.
  47   - Type should be appropriate (string related types differs in their merging capabilities, `loaOf` and `string` types are deprecated).
  48   - Description, default and example should be provided.
  49 - Ensure that option changes are backward compatible.
  50   - `mkRenamedOptionModuleWith` provides a way to make renamed option backward compatible.
  51   - Use `lib.versionAtLeast config.system.stateVersion "24.05"` on backward incompatible changes which may corrupt, change or update the state stored on existing setups.
  52 - Ensure that removed options are declared with `mkRemovedOptionModule`.
  53 - Ensure that changes that are not backward compatible are mentioned in release notes.
  54 - Ensure that documentations affected by the change is updated.
  55
  56 Sample template for a module update review is provided below.
  57
  58 ```markdown
  59 ##### Reviewed points
  60
  61 - [ ] changes are backward compatible
  62 - [ ] removed options are declared with `mkRemovedOptionModule`
  63 - [ ] changes that are not backward compatible are documented in release notes
  64 - [ ] module tests succeed on ARCHITECTURE
  65 - [ ] options types are appropriate
  66 - [ ] options description is set
  67 - [ ] options example is provided
  68 - [ ] documentation affected by the changes is updated
  69
  70 ##### Possible improvements
  71
  72 ##### Comments
  73 ```
  74
  75 ### New modules
  76
  77 New modules submissions introduce a new module to NixOS.
  78
  79 Reviewing process:
  80
  81 - Ensure that all file paths [fit the guidelines](../CONTRIBUTING.md#file-naming-and-organisation).
  82 - Ensure that the module tests, if any, are succeeding.
  83 - Ensure that new module tests are added to the package `passthru.tests`.
  84 - Ensure that the introduced options are correct.
  85   - Type should be appropriate (string related types differs in their merging capabilities, `loaOf` and `string` types are deprecated).
  86   - Description, default and example should be provided.
  87 - Ensure that module `meta` field is present
  88   - Maintainers should be declared in `meta.maintainers`.
  89   - Module documentation should be declared with `meta.doc`.
  90 - Ensure that the module respect other modules functionality.
  91   - For example, enabling a module should not open firewall ports by default.
  92
  93 Sample template for a new module review is provided below.
  94
  95 ```markdown
  96 ##### Reviewed points
  97
  98 - [ ] module path fits the guidelines
  99 - [ ] module tests, if any, succeed on ARCHITECTURE
 100 - [ ] module tests, if any, are added to package `passthru.tests`
 101 - [ ] options have appropriate types
 102 - [ ] options have default
 103 - [ ] options have example
 104 - [ ] options have descriptions
 105 - [ ] No unneeded package is added to `environment.systemPackages`
 106 - [ ] `meta.maintainers` is set
 107 - [ ] module documentation is declared in `meta.doc`
 108
 109 ##### Possible improvements
 110
 111 ##### Comments
 112 ```