pyrox.dev
1# NixOS
2
3NixOS is a Linux distribution based on the purely functional package management system Nix.
4More information can be found at https://nixos.org/nixos and in the manual in doc/manual.
5
6## Testing changes
7
8You can add new module to your NixOS configuration file (usually it’s `/etc/nixos/configuration.nix`).
9And 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
34When changing the bootloader installation process, extra care must be taken.
35Grub installations cannot be rolled back, hence changes may break people’s installations forever.
36For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra.
37
38### Module updates
39
40Module updates are submissions changing modules in some ways.
41These often contains changes to the options or introduce new options.
42
43Reviewing process:
44
45- Ensure that the module maintainers are notified.
46 - 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.
47- Ensure that the module tests, if any, are succeeding.
48 - You may invoke OfBorg with `@ofborg test <module>` to build `nixosTests.<module>`
49- Ensure that the introduced options are correct.
50 - Type should be appropriate (string related types differs in their merging capabilities, `loaOf` and `string` types are deprecated).
51 - Description, default and example should be provided.
52- Ensure that option changes are backward compatible.
53 - `mkRenamedOptionModuleWith` provides a way to make renamed option backward compatible.
54 - Use `lib.versionAtLeast config.system.stateVersion "24.05"` on backward incompatible changes which may corrupt, change or update the state stored on existing setups.
55- Ensure that removed options are declared with `mkRemovedOptionModule`.
56- Ensure that changes that are not backward compatible are mentioned in release notes.
57- Ensure that documentations affected by the change is updated.
58
59Sample template for a module update review is provided below.
60
61```markdown
62##### Reviewed points
63
64- [ ] changes are backward compatible
65- [ ] removed options are declared with `mkRemovedOptionModule`
66- [ ] changes that are not backward compatible are documented in release notes
67- [ ] module tests succeed on ARCHITECTURE
68- [ ] options types are appropriate
69- [ ] options description is set
70- [ ] options example is provided
71- [ ] documentation affected by the changes is updated
72
73##### Possible improvements
74
75##### Comments
76```
77
78### New modules
79
80New modules submissions introduce a new module to NixOS.
81
82Reviewing process:
83
84- Ensure that all file paths [fit the guidelines](../CONTRIBUTING.md#file-naming-and-organisation).
85- Ensure that the module tests, if any, are succeeding.
86- Ensure that new module tests are added to the package `passthru.tests`.
87- Ensure that the introduced options are correct.
88 - Type should be appropriate (string related types differs in their merging capabilities, `loaOf` and `string` types are deprecated).
89 - Description, default and example should be provided.
90 - Defaults may only be omitted if both:
91 1. The user is required to set the default in order to properly use the service.
92 2. The lack of a default does not break evaluation when the module is not enabled.
93- Ensure that module `meta` field is present
94 - Maintainers should be declared in `meta.maintainers`.
95 - Module documentation should be declared with `meta.doc`.
96- Ensure that the module respect other modules functionality.
97 - For example, enabling a module should not open firewall ports by default.
98
99Sample template for a new module review is provided below.
100
101```markdown
102##### Reviewed points
103
104- [ ] module path fits the guidelines
105- [ ] module tests, if any, succeed on ARCHITECTURE
106- [ ] module tests, if any, are added to package `passthru.tests`
107- [ ] options have appropriate types
108- [ ] options have default
109- [ ] options have example
110- [ ] options have descriptions
111- [ ] No unneeded package is added to `environment.systemPackages`
112- [ ] `meta.maintainers` is set
113- [ ] module documentation is declared in `meta.doc`
114
115##### Possible improvements
116
117##### Comments
118```
119
120See also [./README-modular-services.md](./README-modular-services.md).