CONTRIBUTING.md: rewrite

This commit is contained in:
Weathercold 2022-09-10 01:08:51 -04:00
parent 7866333317
commit 3040e3422d
2 changed files with 36 additions and 19 deletions

View file

@ -1,8 +1,14 @@
# Writing profiles
# Contributing a Device Profile
## 1. Writing profiles
Create an appropriate directory and start writing your expression.
When setting an option, use `lib.mkDefault` unless:
- The option *must* be set and the user should get an error if they try to override it.
- The setting should merge with the user's settings (typical for list or set options).
- The option *must* be set and the user should get an error if they try to
override it.
- The setting should merge with the user's settings (typical for list or set
options).
For example:
@ -15,17 +21,29 @@ For example:
}
```
Try to avoid "opinionated" settings relating to optional features like sound, bluetooth, choice of bootloader etc.
Where possible, use module imports to share code between similar hardware
variants. In most cases, import:
- a cpu module;
- a gpu module;
- either the pc or the laptop module;
- either the HDD or the SSD module.
Where possible, use module imports to share code between similar hardware variants.
Try to avoid "opinionated" settings relating to optional features like sound,
bluetooth, choice of bootloader etc. You can mention these in the readme.
# Performance
Profiles should favor usability and stability, so performance improvements
should either be conservative or be guarded behind additional NixOS module
options. If it makes sense to have a performance-focussed config, it can be
declared in a separate profile.
Profiles should favor usability and stability, so performance improvements should either be conservative or
be guarded behind additional NixOS module options.
## 2. Adding Entry
If it makes sense to have a performance-focussed config, it can be declared in a separate profile.
Link the profile in the table in README.md and in flake.nix.
# Testing
## 3. Testing
Because profiles can only be tested with the appropriate hardware, quality assurance is up to *you*.
Run ./tests/run.py to test building. The test script script will parse all the
profiles from the README.md.
Because profiles can only be tested with the appropriate hardware, quality
assurance is up to *you*.

View file

@ -24,9 +24,10 @@ imports = [
New updates to the expressions here will be fetched when you update the channel.
## Using nix flakes support
### Using nix flakes support
There is also experimental flake support. In your `/etc/nixos/flake.nix` add the following:
There is also experimental flake support. In your `/etc/nixos/flake.nix` add
the following:
```nix
{
@ -60,6 +61,10 @@ imports = [
Unlike the channel, this will update the git repository on a rebuild. However,
you can easily pin to a particular revision if you desire more stability.
## How to contribute a new device profile
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## List of Profiles
See code for all available configurations.
@ -188,9 +193,3 @@ See code for all available configurations.
| [System76 Darter Pro 6](system76/darp6) | `<nixos-hardware/system76/darp6>` |
| [Toshiba Chromebook 2 `swanky`](toshiba/swanky) | `<nixos-hardware/toshiba/swanky>` |
| [Tuxedo InfinityBook v4](tuxedo/infinitybook/v4) | `<nixos-hardware/tuxedo/infinitybook/v4>` |
## How to contribute a new device profile
1. Add your device profile expression in the appropriate directory
2. Link it in the table in README.md and in flake.nix
3. Run ./tests/run.py to test it. The test script script will parse all the profiles from the README.md