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 ## Reviewing contributions
  12
  13 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.
  14
  15 ### Module updates
  16
  17 Module updates are submissions changing modules in some ways. These often contains changes to the options or introduce new options.
  18
  19 Reviewing process:
  20
  21 - Ensure that the module maintainers are notified.
  22   - [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.
  23 - Ensure that the module tests, if any, are succeeding.
  24 - Ensure that the introduced options are correct.
  25   - Type should be appropriate (string related types differs in their merging capabilities, `loaOf` and `string` types are deprecated).
  26   - Description, default and example should be provided.
  27 - Ensure that option changes are backward compatible.
  28   - `mkRenamedOptionModuleWith` provides a way to make option changes backward compatible.
  29 - Ensure that removed options are declared with `mkRemovedOptionModule`
  30 - Ensure that changes that are not backward compatible are mentioned in release notes.
  31 - Ensure that documentations affected by the change is updated.
  32
  33 Sample template for a module update review is provided below.
  34
  35 ```markdown
  36 ##### Reviewed points
  37
  38 - [ ] changes are backward compatible
  39 - [ ] removed options are declared with `mkRemovedOptionModule`
  40 - [ ] changes that are not backward compatible are documented in release notes
  41 - [ ] module tests succeed on ARCHITECTURE
  42 - [ ] options types are appropriate
  43 - [ ] options description is set
  44 - [ ] options example is provided
  45 - [ ] documentation affected by the changes is updated
  46
  47 ##### Possible improvements
  48
  49 ##### Comments
  50 ```
  51
  52 ### New modules
  53
  54 New modules submissions introduce a new module to NixOS.
  55
  56 Reviewing process:
  57
  58 - Ensure that the module tests, if any, are succeeding.
  59 - Ensure that the introduced options are correct.
  60   - Type should be appropriate (string related types differs in their merging capabilities, `loaOf` and `string` types are deprecated).
  61   - Description, default and example should be provided.
  62 - Ensure that module `meta` field is present
  63   - Maintainers should be declared in `meta.maintainers`.
  64   - Module documentation should be declared with `meta.doc`.
  65 - Ensure that the module respect other modules functionality.
  66   - For example, enabling a module should not open firewall ports by default.
  67
  68 Sample template for a new module review is provided below.
  69
  70 ```markdown
  71 ##### Reviewed points
  72
  73 - [ ] module path fits the guidelines
  74 - [ ] module tests succeed on ARCHITECTURE
  75 - [ ] options have appropriate types
  76 - [ ] options have default
  77 - [ ] options have example
  78 - [ ] options have descriptions
  79 - [ ] No unneeded package is added to environment.systemPackages
  80 - [ ] meta.maintainers is set
  81 - [ ] module documentation is declared in meta.doc
  82
  83 ##### Possible improvements
  84
  85 ##### Comments
  86 ```