From 79fb386395006aec7702a36cb2166e4096febbc8 Mon Sep 17 00:00:00 2001
From: stuebinm <stuebinm@disroot.org>
Date: Mon, 14 Nov 2022 18:38:43 +0100
Subject: [PATCH] flake-enabled readme :tada:

---
 README.md | 48 +++++++++++++++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 8bb2a18..81abc4c 100644
--- a/README.md
+++ b/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:
-``` shell
-nix build -f . deploy.$hostname && ./result switch
-```
+You will need a flake-enabled nix installation, and have your ssh config set up
+so that `ssh parsons` will connect to `parsons.hacc.space`.
 
-`$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
-  - exceptions apply, if you are not sure where to commit, don't commit to main
+- Things on `main` should always reflect the config that's actually deployed on
+  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: "$prefix$place: $change"
-  - prefix: one of fixup, nothing
-  - place: one of "modules/$module", "$hostname/service", "common/($place)", "pkgs/$pkgs" or "sources"
-  - change: describe your change, don't go over the character limit where git starts hiding/wrapping
+- follow the commit format: "place: $change"
+  - place: e.g. `modules/$module`, `services/$service` ...
+  - change: describe your change. Please wrap your lines sensibly (or configure
+    your editor to do this for you)
 - Exception: autogenerated messages (merge commits, reverts, etc)
+- don't overuse merge commits, try to rebase things if possible with reasonable
+  effort