2023-04-13 - Learning Journey Working Group - Meeting Notes #4

zmitchell · April 13, 2023, 2:37pm

2023-04-13 - Learning Journey Working Group - Meeting Notes #4

Previous meeting notes
Attendees: @zmitchell @khaled @infinisil
Notes taken by: @infinisil

Agenda

Previous action items
Closing the loop on the nix-shell -p tutorial
Drafting an outline for the shell.nix tutorial

Notes

@zmitchell: Created documentation categories (PR not yet created). Not sure about what goes where, a lot of loosely categorized tutorials, making the tree deeper would be a better
- @infinisil: Should tutorials be linear or graph-based? How to integrate with the tree structure?
- @khaled: Linear might not make sense, some people e.g. don’t care about NixOS
- @zmitchell: Imo the first steps should be linear, but after that it’s more free form.
- @khaled: Choose your own adventure - style
- @infinisil: Have pre-requisites and next steps linked from the tutorials, in and out-nodes of the directed graph.
- @zmitchell: Django has First Steps with sequential steps, but after that more topic-based docs
- @infinisil: Agree that only first steps linear is good
@zmitchell: In my own learning journey, while moving from poetry to Nixpkgs, struggling with the fact that it’s Flake-based
- @infinisil: Beta docs page?
- @zmitchell,@khaled: Just marking as experimental sounds better
- @infinisil: Beta page allows having a separate self-contained flake sequence, doesn’t show multiple ways of doing the same way
- @khaled: Shouldn’t be interleaved, can be a separate tree node or a link. Having official flake docs is important, it’s time
- @zmitchell: It’s experimental but it doesn’t break enough to scare people away
- @khaled: We should be able to still make breaking changes to it
- @infinisil: Also what RFC 136 is about
@zmitchell: Tutorials, have the nix-shell -p one, wanted some more useful tooling, iirc jq and curl
- @infinisil: Assigned to @erooke in last week’s action items
@zmitchell: shell.nix tutorial, was on @khaled’s action items
- We don’t have an issue for this yet, created Nix language primer with `shell.nix` · Issue #516 · NixOS/nix.dev · GitHub, see also Add issue templates by zmitchell · Pull Request #501 · NixOS/nix.dev · GitHub
- @khaled: Wasn’t sure where to put it, created HedgeDoc - Collaborative markdown notes, will put into the issue
- What should be part of the tutorial
- @zmitchell: Probably should remove direnv
  - @infinisil: Agreed
- @infinisil: Should have nix.dev fetch repositories and integrate their documentation, could maybe also do that with third-party repos like direnv
  - @zmitchell: direnv is not nix-specific though
  - @khaled: There’s GitHub - nix-community/nix-direnv: A fast, persistent use_nix/use_flake implementation for direnv [maintainer=@Mic92 / @bbenne10] · GitHub too though
- @zmitchell: Regarding fetching the channel
  - @infinisil: Using channel:nixos-22.11 doesn’t require flakes, nix-channels and it doesn’t require pinning
  - @khaled: Requires knowing about channels, flakes?
  - @infinisil: Flakes still indirectly uses channels via the e.g. nixos-22.11 branch which Hydra updates on successful channel evaluations
  - @infinisil: Maybe channels should be introduced before this tutorial? nix-shell -p → channels → shell.nix with channel:...
  - DetSys installer leaves NIX_PATH empty, but <nixpkgs> is still available, making nix-shell -p work
  - @infinisil: Common grounds is that every installation has a <nixpkgs> available, can use that
  - @zmitchell: Where it comes from should also be documented
  - @infinisil: Currently it sucks because nix-channel is being deprecated, but the Flake registry has similar impurities
  - @infinisil: We could use nix-shell -p hello -I nixpkgs=channel:nixpkgs-unstable
  - @khaled: Flake registries seem bad, only the CLI should have it
  - Conclusion (@zmitchell, @infinisil, @khaled): Let’s go with the assumption that <nixpkgs> works in a Nix installation without going into details how it works
@zmitchell: Just cargo and rustc works fine for a Rust project without managing deps with Nix
Removed the learning journey project board by merging it into the documentation team project board using a new field “Subgroup”, a new view was created to filter just for learning journey issues: Nix documentation · GitHub

Action items

@khaled: Move HedgeDoc - Collaborative markdown notes to Nix language primer with `shell.nix` · Issue #516 · NixOS/nix.dev · GitHub with short notes. Figure out what should be capture from those
@zmitchell: Continue working on Tracking issue - re-shape current content into a structure based on Diataxis · Issue #499 · NixOS/nix.dev · GitHub

fricklerhandwerk · April 13, 2023, 9:00pm

This. I thought we converged on the example last time. The advantage of specifying a release explicitly gets us close to a habit of actually pinning things. A release channel does not change that much.

zmitchell · April 14, 2023, 2:25pm

@Infinisil can you chime in, I’m still fuzzy on the details because it appears my particular Nix setup is non-standard.

Infinisil · April 14, 2023, 4:44pm

I’m now thinking we should not use channel:nixpkgs-unstable, because it depends on special URLs and channels.nixos.com, which won’t be a requirement for pinning.

Instead I think we should go for fetchTarball "https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable", which only needs GitHub knowledge and leads very well into pinning.

In sequence:

Introduce nix-shell -p without explicitly specifying where nixpkgs comes from, underneath nix-shell just accesses <nixpkgs>, which works in any installation.
Introduce a shell.nix that copies the nix-shell -p behavior exactly by using <nixpkgs>, explain how <nixpkgs> is provided impurely by the system installation of Nix
Change the shell.nix to use fetchTarball "https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable" instead of <nixpkgs>, showing how this removes the system installation impurity, replacing it with an evaluation impurity (because the nixpkgs-unstable branch changes every so often). We don’t need to go into details as to when the branch updates.
For the pinning tutorial we can then initially just replace nixpkgs-unstable with a git revision, manually at first

Infinisil · April 14, 2023, 4:51pm

@zmitchell The difference between a standard installation and a flake-only installation is that:

A standard installation sets up a default channel using nix-channel and adds a NIX_PATH entry for it. <nixpkgs> will then point to the fetched channel. Channel updates can then be managed using nix-channel --update
A flake-only installation however doesn’t really need a NIX_PATH, since everything should be done via Flakes, so nix flake update is used to update Nixpkgs instead. But for backwards compatibility, <nixpkgs> will still point to a Nixpkgs version (though fetched with Flakes). This also makes nix-shell -p still work (because internally it uses <nixpkgs>).

fricklerhandwerk · April 14, 2023, 5:43pm

I agree with the general proposal, but why would you point to unstable? That is going to change quite rapidly and will tend to produce broken examples. With a release branch we at least have a good chance of avoiding inscrutable surprises for beginners.

Infinisil · April 14, 2023, 5:46pm

Good point, release branch sounds better, though it shouldn’t be release-22.11 (that’s where PR’s go directly), but rather nixos-22.11 (that’s only updated when Hydra checked that the PR’s didn’t break anything)