Merge pull request #5795 from sellout/nix-cache-instructions

Add instructions for updating the Nix cache

Author: ceedubs

nix/README.md

@@ -105,3 +105,51 @@ nix develop '.#cabal-unison-parser-typechecker'
 cd unison-cli
 cabal run --enable-profiling unison-cli-main:exe:unison -- +RTS -p
 ```
+
+## updating the Nix cache
+
+There is [a cache for Unison artifacts on Cachix](https://unison.cachix.org). It is primarily used for two purposes:
+
+1. to keep an up-to-date development environment for Unison contributors and
+2. to maintain built versions of the last few releases.
+
+Correspondingly, CI automatically updates the cache on merges to trunk (to satisfy the first use case) and on release tags to mostly satisfy the second.
+
+### updating when the development environment changes
+
+Any PR that affects the Nix development environment (e.g., touches flake.nix or files in nix/) should ensure the cache is updated before it’s merged into trunk – to avoid there being any time when contributors end up rebuilding the tooling locally.
+
+The easiest way to do this is to manually run the [Nix development cache](https://github.com/unisonweb/unison/actions/workflows/nix-dev-cache.yaml) workflow on the PR’s branch (which may be located on your fork).
+
+Depending on how much needs to be rebuilt, some or all of the jobs may fail. In this case, you can populate the cache from another machine[^1].
+
+``` bash
+nix build .#all --accept-flake-config --json --keep-going --system ${system} \
+  | jq --raw-output '.[].outputs | to_entries[].value' \
+  | cachix --verbose push unison
+```
+(adapted from [the Cachix documentation](https://docs.cachix.org/pushing#pushing-runtime-closure))
+
+`system` is generally the Nix system (e.g., `x86_64-linux`, `aarch64-darwin`) you are running this on, but you can also use different systems in some cases. E.g.,
+if you are running on an Apple silicon Mac, you can also run the above command using `--system x86_64-darwin` to cache Intel Mac derivations.
+
+Another issue @sellout has run into is that `cachix` seems to crash a lot on at least some Macs. To keep re-trying until it succeeds, try
+
+``` bash
+until
+  nix build .#all --accept-flake-config --json --keep-going \
+    | jq --raw-output '.[].outputs | to_entries[].value' \
+    | cachix --verbose push unison
+do :
+done
+```
+
+### updating after a release
+
+After a release tag is made, we additionally need to [pin](https://unison.cachix.org#pins) the new releases in the cache, so they don’t expire.
+
+```bash
+cachix pin unison "ucm-${version}-${system}" "/nix/store/${hash}-unison-cli-main-exe-unison-0.0.0"
+```
+
+__NB__: Since the Cabal files don’t have the version set, the version in the Nix store will always be “0.0.0”, regardless of the actual release.

nix/haskell-nix-flake.nix

@@ -34,6 +34,7 @@
           pkgs.cachix
           pkgs.gettext # for envsubst, used by unison-src/builtin-tests/interpreter-tests.sh
           pkgs.hpack
+          pkgs.jq # helpful when pushing to Cachix
           pkgs.pkg-config
           pkgs.stack-wrapped
         ];