Upgrade nixpkgs to current master and add an upgrade checklist (#1579)

* simplify haskell packages overrides based on new nixpkgs * update Nix gitignore * simplify Haskell packages overlay Co-authored-by: monacoremo <monacoremo>
2020-09-09 19:08:16 -05:00
parent bd2160db26
commit 7af54c5813
12 changed files with 188 additions and 90 deletions
@@ -0,0 +1,91 @@
+# Checklist for upgrading Nix dependencies
+
+The Nix dependencies of PostgREST should be updated regularly, in most cases it
+should be a very simple operation.
+
+```bash
+# Update pinned version of Nixpkgs
+nix-shell --run nixpkgs-upgrade > nix/nixpkgs-version.nix
+
+# Verify that everything builds
+nix-build
+```
+
+The following checklist guides you through the complete process in more detail.
+
+## Upgrade the pinned version of `nixpkgs`
+
+The pinned version of [`nixpkgs`](https://github.com/NixOS/nixpkgs) is defined
+in [`nix/nixpkgs-version.nix`](nixpkgs-version.nix). The pin refers directly to
+a GitHub tarball for the given revision, which is more efficient than pulling
+the complete Git repository. To upgrade it to the current `master` of
+`nixpkgs`, you can use a small utility script defined in
+[`nix/nixpkgs-update.nix`](nixpkgs-update.nix):
+
+```bash
+# From the root of the repository, enter nix-shell
+nix-shell
+
+# Run the utility script to pin the latest revision in master
+nixpkgs-upgrade > nix/nixpkgs-version.nix
+
+# Exit the nix-shell with Ctrl-d
+
+```
+
+## Update pinned version of `static-haskell-nix`
+
+We pin [`static-haskell-nix`](https://github.com/nh2/static-haskell-nix) in
+[`nix/static-haskell-package.nix`](static-haskell-package.nix). Upgrade the
+pinned revision and the tarball hash if necessary. See
+[`nix/nixpkgs-upgrade.nix`](nixpkgs-upgrade.nix) for how to get the correct
+tarball hash, or just change the hash to an arbitrary value of correct length,
+run `nix-build` and use the expected value from the resulting error message.
+
+## Review overlays
+
+Check whether the individual [overlays](overlays) are still required.
+
+## Check if patches are still required and update them as needed
+
+We track a number of PostgREST-specific patches in [`nix/patches`](patches).
+Check whether the pull-requests/issues linked in the
+[`default.nix`](patches/default.nix) have progressed and remove/modify the
+patches if they did. If conflicting changes occurred, you might have to rebase
+the respective patches.
+
+## Build everything
+
+Using the PostgREST binary Nix cache is recommended. Install
+[Cachix](https://cachix.org/) and run `cachix use postgrest`.
+
+Run `nix-build` in the root directory of the project to build all PostgREST
+artifacts. This might take a long time, e.g. when our static GHC version needs
+to be rebuilt due to changes to some underlying package. If there are any
+errors, this is probably due to one of our patches. Try to fix them and re-run
+`nix-build` until everything builds.
+
+## Update the PostgREST binary cache
+
+If you have access to the PostgREST cachix signing key, you can push the
+artifacts that you built locally to the binary cache. This will accelerate the
+CI builds and tests, sometimes dramatically. This might sometimes even be
+required to avoid build timeouts in CI.
+
+You'll need to set the `CACHIX_SIGNING_KEY` before proceeding, e.g. by creating
+a file containing `export CACHIX_SIGNING_KEY=...` and sourcing that file, which
+avoids having the secret in you shell history.
+
+To push all new artifacts to Cachix, run:
+
+```
+nix-store -qR --include-outputs $$(nix-instantiate) | cachix push postgrest
+
+# Or, equivalently
+make cachix-push-all
+
+```
+
+The `nix-store` command will query the nix-store to list all dependencies and
+build artifacts of PostgREST. The `cachix` command will efficiently push
+everything that is not yet cached to the binary cache.