architecture-docs/on-flakes.md: add some initial notes

architecture-docs/on-flakes.md

@@ -0,0 +1,45 @@
+# 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
+
+While its RFC was [drafted](https://github.com/NixOS/rfcs/pull/49) and implemented by Nix creator Eelco Dolstra thru Tweag (which is now divided on flakes) on behalf of Target (which we no longer have indication still uses nix), its 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 - appears to have yielded mixed results, flying in the face of the Unix philosophy, and drawing criticism from various prominent community members, including:
+
+- [samueldr](https://samuel.dionne-riel.com/blog/2023/09/06/flakes-is-an-experiment-that-did-too-much-at-once.html) (author of NixOS Mobile): trying too many things at once (Unix philosophy)
+- [jade](https://jade.fyi/blog/flakes-arent-real/) (Lix core member): locking dependencies of subprojects
+<!-- - [fricklerhandwerk](https://nix.dev/concepts/flakes#why-are-flakes-controversial) (Tweag, head of documentation): no parameterization, defying Unix philosophy -->
+- [raitobezarius](https://discourse.nixos.org/t/nix-flakes-is-an-experiment-that-did-too-much-at-once/32707/3) (board observer, Lix core member): technical issues
+- [infinisil](https://discourse.nixos.org/t/experimental-does-not-mean-unstable-detsyss-perspective-on-nix-flakes/32703/2) (constitutional assembly): dependency explosion, no support to pass arguments, eagerly copying flake directories to the store, bad UX
+- [sandro](https://discourse.nixos.org/t/introducing-flakehub/32044/31) (one of the biggest contributors to nixpkgs): making semantic versioning part of commercial project Flakehub rather than of Nix itself
+- [alyssais](https://github.com/NixOS/rfcs/pull/49#pullrequestreview-262606855) (authored Spectrum OS): inability to patch flakes
+- [tazjin](https://news.ycombinator.com/item?id=40060403) (thru TVL co-authored Tvix): complexity
+- [jtojnar](https://discourse.nixos.org/t/why-are-flakes-still-experimental/29317/12): not awaiting RFC process
+- [piegames](https://discourse.nixos.org/t/introducing-flakehub/32044/52) (formerly member of the moderation team, further [contributed 25 commits to dependency management alternative `npins`](https://github.com/andir/npins/commits?author=piegamesde)): integration into Nix core
+- [solene](https://discourse.nixos.org/t/introducing-flakehub/32044/24): commercial interests
+<!-- - [open letter](https://save-nix-together.org/): undermining community processes by declaring flakes stable -->
+
+Alternatives:
+
+- dependency management: potentially better done using `npins`, which makes this more explicit, whereas flakes offer performance improvements when interacting with a large Nix package repository like 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