flake-enabled readme 🎉

README.md

@@ -4,28 +4,41 @@ welcome to hacc nixfiles (haccfiles). this is the code describing our nix-based
 
 ## structure
 
-- `default.nix`: Entrypoint to the config
+- `flake.nix`: Entrypoint & dependencies
 - `common/`: configuration common to all hosts
-- `desktop/`: desktop-relevant communication
 - `modules/`: home-grown modules for hacc-specific services
-- `nix/`: sources files, managed with niv
 - `pkgs/`: packages we built and don't want to upstream
-- `hosts/`: configuration.nix per host
+- `hosts/`: configuration.nix per host (currently there's only one of those)
 - `services/`: all services we run; imported in appropriate host config
+- `websites/`: static websites we deploy somewhere
 
 ## working with the haccfiles
 
-deploy:
+You will need a flake-enabled nix installation, and have your ssh config set up
-``` shell
+so that `ssh parsons` will connect to `parsons.hacc.space`.
-nix build -f . deploy.$hostname && ./result switch
-```
 
-`$hostname` can be replaced with any hostname or group
+It's recommended to use [deploy_rs](https://github.com/serokell/deploy-rs):
+~~~shell
+deploy .#parsons -k [--dry-activate]
+~~~
+
+Alternatively, using just `nixos-rebuild`:
+~~~shell
+nixos-rebuild --flake .#parsons --target-host parsons \
+  --use-remote-sudo --use-substitutes [test|switch|dry-activate]
+~~~
+
+If for some reason you have `nix` but not `nixos-rebuild`, you can still build the
+system closure using:
+~~~shell
+nix build .#nixosConfigurations.parsons.config.system.build.toplevel
+~~~
+
+(but you might have trouble deploying it)
 
 ## I don't want to build this long dependency / want a cached version!
 
 If it's still available on parsons from a previous deploy, do:
-
 ```shell
 nix copy --from ssh://parsons /nix/store/...
 ```
@@ -36,12 +49,13 @@ don't know the actual outpath, look in the .drv file (should start with
 `Derive([("out","[the path you want]"...`)
 
 ## committing to haccfiles
-- Golden Rule: DO NOT COMMIT TO MAIN
+- Things on `main` should always reflect the config that's actually deployed on
-  - exceptions apply, if you are not sure where to commit, don't commit to main
+  parsons, except during testing / debugging sessions
 - split up commits, every commit is one atomic change
-  - e.g. no big "did some changes" but instead "updated service x", "updated service y", "update service z"
+- follow the commit format: "place: $change"
-- follow the commit format: "$prefix$place: $change"
+  - place: e.g. `modules/$module`, `services/$service` ...
-  - prefix: one of fixup, nothing
+  - change: describe your change. Please wrap your lines sensibly (or configure
-  - place: one of "modules/$module", "$hostname/service", "common/($place)", "pkgs/$pkgs" or "sources"
+    your editor to do this for you)
-  - change: describe your change, don't go over the character limit where git starts hiding/wrapping
 - Exception: autogenerated messages (merge commits, reverts, etc)
+- don't overuse merge commits, try to rebase things if possible with reasonable
+  effort