| 12 Jan 2024 |
 infinisil | 9999years: I think it's more that Nix is the underlying foundation, Nixpkgs is based on Nix, and NixOS is based on Nixpkgs | 01:10:06 |
| infinisil | So the dependency chain is strictly NixOS -> Nixpkgs -> Nix. There's no arrows back | 01:11:00 |
| infinisil | So generally I don't think there should be explanations of concepts making use of such back-arrows.
However, in order to find information, I'd be in favor of a mechanism that automatically inserts back-links in all documentation | 01:12:06 |
| infinisil | So if Nixpkgs links from stdenv.mkDerivation's docs to the ones for derivation, in the derivation docs you'd see a little "this page is linked to from the stdenv.mkDerivation docs" link | 01:12:48 |
 @qyriad:matrix.org | In reply to @infinisil:matrix.org
9999years: I think it's more that Nix is the underlying foundation, Nixpkgs is based on Nix, and NixOS is based on Nixpkgs this helps you understand how the Nix ecosystem is implemented, not how it's used or how and why it's useful | 01:13:33 |
 @9999years:matrix.org | i mean it would certainly be useful to say in the nix manual "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in nixpkgs" | 01:13:47 |
| @9999years:matrix.org | having recently helped several beginners get started with nix i can confirm this sort of thing trips new users up pretty consistently | 01:14:18 |
| infinisil | 9999years: Maybe yeah, but also, I've thought multiple times before to just ditch builtins.derivation and use builtins.strictDerivation instead in Nixpkgs, which would then outdate the docs on the Nix side | 01:15:08 |
| infinisil | The Nix codebase generally really doesn't know how it's used. And there could be various Nixpkgs versions that are each implemented differently | 01:16:11 |
| @9999years:matrix.org | yeah i mean, this is one of the issues with nix's docs -- nixpkgs and nix are deeply intertwined, but they can't be versioned together, even trivial stuff like lib | 01:16:47 |
| infinisil | I think such automated back-links might be a good compromise tbh | 01:17:01 |
| infinisil | Needs a unified docs building infrastructure though | 01:17:11 |
| @9999years:matrix.org | yeah automated back-links would be great. i still think additional human-written context would be useful but back-links would be a fantastic start | 01:17:28 |
| @9999years:matrix.org | (and lots more backlinks) | 01:17:42 |
| @qyriad:matrix.org | agreed | 01:17:50 |
| @qyriad:matrix.org | automated backlinks would be great, but why should we compromise on providing clear, understandable information in documentation? | 01:18:18 |
| infinisil | Wrong docs are imo worse than missing docs | 01:18:35 |
| @9999years:matrix.org | e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv | 01:18:48 |
| infinisil | And if we write information about Nixpkgs in Nix, that can easily become wrong | 01:18:53 |
| @qyriad:matrix.org | In reply to @9999years:matrix.org
e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv oh wow it doesn't even do that? o.o | 01:19:03 |
| @9999years:matrix.org | i'm not saying we should have a ton of nixpkgs docs, but we should feel comfortable referring to high-level nixpkgs concepts that are unlikely to change (like mkDerivation, the override and overlay systems, etc.) | 01:19:33 |
| infinisil | I'd be okay with that yeah | 01:19:51 |
| @9999years:matrix.org | explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix | 01:20:09 |
| @9999years:matrix.org | but right now you basically just have to ask an expert or read the source code, and the nixpkgs source code for the stdenv stuff, overlays, overrides, and so on is gnarly especially for beginners | 01:20:33 |
| @qyriad:matrix.org | In reply to @infinisil:matrix.org
And if we write information about Nixpkgs in Nix, that can easily become wrong vice versa is also true. certainly what's cross-explained can be limited, but something as simple as "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in Nixpkgs. See link for more information" | 01:20:38 |
| infinisil | In reply to @9999years:matrix.org
explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix Reminds me of https://github.com/NixOS/nixpkgs/pull/248220 and https://github.com/NixOS/nixpkgs/pull/255132 | 01:20:58 |
| @qyriad:matrix.org | In reply to @9999years:matrix.org
explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix this would be fantastic | 01:21:54 |
| @9999years:matrix.org | In reply to @infinisil:matrix.org
Reminds me of https://github.com/NixOS/nixpkgs/pull/248220 and https://github.com/NixOS/nixpkgs/pull/255132 those PRs look great! what's blocking them from being merged? | 01:22:16 |
| @9999years:matrix.org | i see this 'perfect is the enemy of the good' stuff a lot with nix docs, where PRs that improve docs are rejected or bikeshed because they're not perfect. but they don't need to be perfect, they just need to be better than they were before | 01:22:46 |
| @qyriad:matrix.org | In reply to @infinisil:matrix.org
And if we write information about Nixpkgs in Nix, that can easily become wrong * vice versa is also true. certainly what's cross-explained can be limited, but something as simple as "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in Nixpkgs. See link for more information" would help a lot for little overhead | 01:22:47 |
