2023-04-06 - Learning Journey Working Group - Meeting Notes #3

Development Documentation
1

2023-04-06 - Learning Journey Working Group - Meeting Notes #3

Previous meeting notes: 2023-03-30 - Learning Journey Working Group - Meeting Notes #2

Previous action items

Next tutorial

  • @zmitchell: What should the next tutorial be? Turning an ephemeral shell into a declarative one in a shell.nix. Make it a continuation of the first tutorial, make some changes to have them be more aligned, use the same packages in the environment

    • @infinisil: That sounds like Declarative shell environments with shell.nix — nix.dev documentation

    • @zmitchell: Not sure if pinning should be a requirement

    • @fricklerhandwerk: Hard dependency is Nix language basics — nix.dev documentation, but pinning also, maybe with niv

      • effectively finding Nixpkgs hashes so far is not described anywhere really

    • @henrik-ch: Tutorial flow makes sense from top to bottom

    • @zmitchell: I don’t think the Nix language should be a strict requirement. E.g. just go to Nixpkgs and grab this identifier, add it to the packages list in mkShell. The requirement should be as minimal as possible

    • @fricklerhandwerk:

      • Onboarding story:
        • Show nix-shell -p, possibly shebang
        • Immediate next question is how to persist it, but then comes Python, Node, and more complicated things
        • Should show pinning (e.g. niv) and direnv, but then leads to home-manager, etc.
        • Reading the Nix language comes quickly, and preexisting programming language knowledge doesn’t help much
        • People are quickly confused by the need for parenthesis, semicolons, etc.
      • @zmitchell: Nix language basics — nix.dev documentation goes into details not necessary for the declarative shell. We can show the user a basic shell.nix and highlight parts of it, explaining what is input, output, key-value set, function body, etc. Beginners and experts see the same thing differently.
        • @khaled: Agreeing. But then continue with expansion on why this is not good enough. Add nixpkgs reproducibility, why we want it, step-by-step.
      • @zmitchell: direnv and home-manager shouldn’t be necessary here
        • @henrik-ch: Agreeing
        • @khaled: Agreeing. Do it more step-by-step, e.g. why you might not want to install it imperatively
      • @erooke: Python works with its own environments
        • @fricklerhandwerk: Later fan-out into what you can all pin more deterministically using Nix
      • @khaled: Npm also works unless you try to do global installments

    • @fricklerhandwerk: the example should not even be a function, it raises lots of questions:

      • @infinisil: system argument is needed for flakes but only later. Sounds alright to not have a function for now
      • @zmitchell: Minimal?
      • @fricklerhandwerk: Start out without pinning, only introduce it later. Flakes would solve this but it adds a lot on top. Should first understand how Nix works
      • @infinisil: First step is just about putting the command into a file, and <nixpkgs> is also what nix-shell -p uses, only the next step should be making it reproducible
      • @khaled: Keep it as simple as possible first, no pinning
      • @zmitchell: I’m not sure what angle brackets do, what is there in the NIX_PATH. Determinate systems installer might not install channels
      • @infinisil: That’s not great, there’s no common grounds
      • @fricklerhandwerk: Could fetch the channel inline using channel: URL syntax
      • @zmitchell: Also get rid of with pkgs; imo

    • @henrik-ch: How about we only link to specific sections of the language tutorial as a prerequisite

    • @zmitchell: Go from nix-shell -p into how to save that environment to a file

    • @zmitchell: Not sure which tools to pick. Python? Rust? If you want to install packages, do it this exact way that works

    • @fricklerhandwerk: lolcat, etc. was chosen to not capture (or lose) any specific audience. Any programming language or tooling needs config, packages, etc. which becomes harder and more involved with Nix

    • Example to anchor everything on:

      let pkgs = import (fetchTarball channel:nixos-22.11) {}; in
pkgs.mkShell {
    buildInputs = with pkgs; [
        git
        neovim
        nodejs
    ];
}
      • @infinisil, @zmitchell: Maybe no with pkgs;?
        • @fricklerhandwerk: reduces visual noise, appropriately represents the complexity of the task at hand
          • still easy to explain: names/items in the pkgs collection/object/dict/attrset are available for adding to that list directly
  • Conclusions:
    • Minimal amount of Nix language requirements
    • switch order of tutorials, move pinning to later
      1. Installation
      2. nix-shell -p
      3. shell.nix
  • @zmitchell: Not sure about which tools should appear in nix-shell -p and shell.nix tutorials. Some language? Which one?
    • @fricklerhandwerk: We’d have to check whether you can do Rust without running into problems, same for Python, Node, include all three, including neovim. Then later follow-up with home-manager for the user-facing setup of neovim, moving it out of the shell.nix
    • @henrik-ch: Could allow readers to select the tools. Maybe sizing up a smaller tutorial would be good too
    • @fricklerhandwerk: Branching is probably the best way to do things, because then one can go into fully working examples
    • otherwise you run the risk of people trying pip install -r and failing miserable
    • @erooke: Maybe flamegraph
    • @zmitchell: Something that doesn’t need configuration
      • @infinisil: make, jq, curl, curl the GitHub API, process with jq. Maybe a Python script without deps
    • Maybe not Python, could lead into problems with pip, etc.
      • @khaled: I like the Python idea
        • @infinisil: How about doing that later, start off without config
    • @fricklerhandwerk: GitHub - agarrharr/awesome-cli-apps: 🖥 📊 🕹 🛠 A curated list of command line apps
      • advanced replacements for POSIX tools, not installed by default anywhere:
        • tre, rg, fd, bat, exa
      • fancy CLI tools
        • ranger, entr, tmate
    • @infinisil: Maybe keep it simpler for the start, use tools most people will know
    • @zmitchell: Like the idea of querying the GitHub API using curl and jq
    • @fricklerhandwerk: What about gh, the GitHub CLI?
      • @infinisil We can use part of the API without logging in using just curl and jq
      • @fricklerhandwerk: yes, should use something with minimal dependencies
    • @infinisil: Show how users can figure out their GitHub ID, as necessary to be added as a maintainer, see here
  • Conclusions on tools for the shell.nix example:
    • should be relevant to software developers (target audience)
    • must be programming langauge agnostic
    • must be command-line only
    • must not require configuration or accounts
    • should not be trivially available on vanilla distributions

Action items

2 Likes
2

It’s a little morbid, but I made a small curl + pup ~demo script for no-look, no-leap Shell script dependencies that checks Wikipedia for recent notable deaths. You can borrow if it helps add velocity to a tutorial project.

3

Amazing work! I’m having FOMO for missing the meeting, which I think is a very good sign :rofl: