Merge pull request #459 from Weathercold/contrib-rewrite

CONTRIBUTING.md: rewrite

CONTRIBUTING.md

@@ -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 option *must* be set and the user should get an error if they try to
-- The setting should merge with the user's settings (typical for list or set options).
+  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
+## 2. Adding Entry
-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.
+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*.

README.md

@@ -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.
@@ -189,9 +194,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