2023-07-25 14:56:42 +00:00
# NixOS
2007-02-05 15:12:47 +00:00
2007-02-06 21:38:59 +00:00
NixOS is a Linux distribution based on the purely functional package
management system Nix. More information can be found at
2020-04-18 20:51:19 +00:00
https://nixos.org/nixos and in the manual in doc/manual.
2023-07-25 16:17:24 +00:00
2023-08-04 18:02:54 +00:00
## 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` .
2023-10-24 02:51:50 +00:00
## 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 ).
2023-08-14 02:49:15 +00:00
## Reviewing contributions
2023-07-25 16:17:24 +00:00
2023-08-14 17:03:56 +00:00
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.
2023-08-14 02:49:15 +00:00
### Module updates
2023-07-25 16:17:24 +00:00
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.
- [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.
- Ensure that the module tests, if any, are succeeding.
2023-10-26 12:06:05 +00:00
- You may invoke OfBorg with `@ofborg test <module>` to build `nixosTests.<module>`
2023-07-25 16:17:24 +00:00
- 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.
2023-10-26 12:06:05 +00:00
- `mkRenamedOptionModuleWith` provides a way to make renamed option backward compatible.
2024-05-31 18:17:44 +00:00
- Use `lib.versionAtLeast config.system.stateVersion "24.05"` on backward incompatible changes which may corrupt, change or update the state stored on existing setups.
2023-10-26 12:06:05 +00:00
- Ensure that removed options are declared with `mkRemovedOptionModule` .
2023-07-25 16:17:24 +00:00
- Ensure that changes that are not backward compatible are mentioned in release notes.
- Ensure that documentations affected by the change is updated.
Sample template for a module update review is provided below.
```markdown
##### Reviewed points
- [ ] changes are backward compatible
- [ ] removed options are declared with `mkRemovedOptionModule`
- [ ] changes that are not backward compatible are documented in release notes
- [ ] module tests succeed on ARCHITECTURE
- [ ] options types are appropriate
- [ ] options description is set
- [ ] options example is provided
- [ ] documentation affected by the changes is updated
##### Possible improvements
##### Comments
```
2023-08-14 02:49:15 +00:00
### New modules
2023-07-25 16:17:24 +00:00
New modules submissions introduce a new module to NixOS.
Reviewing process:
2023-10-26 12:06:05 +00:00
- Ensure that all file paths [fit the guidelines ](../CONTRIBUTING.md#file-naming-and-organisation ).
2023-07-25 16:17:24 +00:00
- Ensure that the module tests, if any, are succeeding.
2024-08-13 18:23:41 +00:00
- Ensure that new module tests are added to the package `passthru.tests` .
2023-07-25 16:17:24 +00:00
- 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 module `meta` field is present
- Maintainers should be declared in `meta.maintainers` .
- Module documentation should be declared with `meta.doc` .
- Ensure that the module respect other modules functionality.
- For example, enabling a module should not open firewall ports by default.
Sample template for a new module review is provided below.
```markdown
##### Reviewed points
- [ ] module path fits the guidelines
2024-08-13 18:23:41 +00:00
- [ ] module tests, if any, succeed on ARCHITECTURE
- [ ] module tests, if any, are added to package `passthru.tests`
2023-07-25 16:17:24 +00:00
- [ ] options have appropriate types
- [ ] options have default
- [ ] options have example
- [ ] options have descriptions
2023-10-26 12:06:05 +00:00
- [ ] No unneeded package is added to `environment.systemPackages`
- [ ] `meta.maintainers` is set
- [ ] module documentation is declared in `meta.doc`
2023-07-25 16:17:24 +00:00
##### Possible improvements
##### Comments
```