focus on tech over people

architecture-docs/on-flakes.md

@@ -0,0 +1,44 @@
+# Use more principled dependency management than flakes
+
+As per [nix.dev](https://nix.dev/concepts/flakes#should-i-use-flakes-in-my-project):
+
+> Flakes emphasize reproducible artifacts and convenience for their consumers, while classic Nix tools center around composable building blocks and customisation options for developers.
+
+We have currently used nix flakes to:
+
+- manage project dependencies
+- specify:
+
+Parts of our project that touch upon flakes:
+
+- our dependency management
+- how we interface with dependencies
+- how we (might) expose packages at upstream repositories, to facilitate e.g. `nix run`
+- the interface we expose (to users + nixops4)
+  - architectures
+  - formatter
+  - checks
+  - pre-commit hooks
+  - development shell
+  - configuration for nixos / nixops
+
+Flakes aim to address various topics at once - as per their [introduction](https://www.tweag.io/blog/2020-05-25-flakes/#what-problems-do-flakes-solve) including composability, reproducibility, offering a consistent UI, and discoverability. [Technical issues](https://discourse.nixos.org/t/nix-flakes-is-an-experiment-that-did-too-much-at-once/32707/3) aside, they have drawn criticism including:
+
+- [trying too many things at once](https://samuel.dionne-riel.com/blog/2023/09/06/flakes-is-an-experiment-that-did-too-much-at-once.html) (Unix philosophy)
+- [dependency explosion, no support to pass arguments, eagerly copying flake directories to the store, bad UX](https://discourse.nixos.org/t/experimental-does-not-mean-unstable-detsyss-perspective-on-nix-flakes/32703/2)
+- [locking dependencies of subprojects](https://jade.fyi/blog/flakes-arent-real/)
+<!-- - [inability to patch flakes](https://github.com/NixOS/rfcs/pull/49#pullrequestreview-262606855) -->
+<!-- - [complexity](https://news.ycombinator.com/item?id=40060403) -->
+<!-- - [no parameterization, defying Unix philosophy](https://nix.dev/concepts/flakes#why-are-flakes-controversial) -->
+<!-- - [not awaiting RFC process](https://discourse.nixos.org/t/why-are-flakes-still-experimental/29317/12) -->
+<!-- - [integration into Nix core](https://discourse.nixos.org/t/introducing-flakehub/32044/52) -->
+<!-- - [making semantic versioning part of commercial project Flakehub rather than of Nix itself](https://discourse.nixos.org/t/introducing-flakehub/32044/31) -->
+<!-- - [commercial interests](https://discourse.nixos.org/t/introducing-flakehub/32044/24) -->
+<!-- - [open letter](https://save-nix-together.org/): undermining community processes by declaring flakes stable -->
+
+Alternatives:
+
+- dependency management: after a [bug](https://github.com/andir/npins/issues/57) fix maybe better done using `npins`, which makes this more explicit, while flakes' caching may help for say Nixpkgs
+- how we interface with dependencies: mostly can be done without flakes, which may in fact help prevent pulling in recursive dependencies we do not use
+- how we (might) expose packages at upstream repositories, to facilitate e.g. `nix run`: no good alternatives for `nix run` exist [currently](https://github.com/NixOS/nix/pull/4702#issuecomment-2233787312), aside from it seeming preferable to defer deviating from the norm here to community RFCs
+- the interface we expose: flakes ignore unstaged files, cache at the cost of eagerly copying flake directories to the store, don't support passing arguments, make it harder to evaluate just part of a project