2023-07-27 - Learning Journey Working Group - Meeting Notes #19

Development Documentation
1

Notes

Updates

Let’s work on outlines

Trivial builders

  • writeTextFile, runCommand, writeShellApplication or writeShellScript with ${pkgs...}
  • @infinisil: Could we just link to the reference? What to teach on top?
  • @zmitchell: Need to know how to use these functions and for which use cases
  • @infinisil: builtins.toFile, then run into limitations → writeText
    • @roberth: Shouldn’t teach the builtin, only an optimisation [also it breaks when you have a reference]
  • @roberth: Maybe it only needs to be mentioned, not make it complicated
  • @infinisil: Maybe it should only be a How-to and reference, there’s no reusable skills to be taught
  • @brianmcgee: Should make it more explicit when each should be used, what their differences are
  • @roberth: Framed as a skill: String interpolation, graph of derivations
  • @infinisil: Tutorial for depending on derivations sounds good, some ideas:
    • String interpolation (+1)
    • Paths in string interpolation (+1)
    • string context (+1)
    • outPath ↔ derivation in string interpolation
    • nix-store --query
      • A bit more advanced, but could be good to know
      • @infinisil: Allows people to see the dependencies instead of just talking about it
      • @roberth: Link to reference
    • Build-time vs runtime-dependencies/output references
    • In another tutorial:
      • .drv files, nix show-derivation
  • @roberth: Generally start with reference docs then build a tutorial from that
  • In this case, skills are different from the original topic
  • @zmitchell: Let’s not PR outlines, outlines can be in issues
  • @brianmcgee: Could write a tutorial, but might be missing the boat
    • @infinisil: Draft PR after e.g. an hour of work, wait for feedback, slowly move forward
  • @zmitchell: Not doing trivial builders tutorial? → No
    • @infinisil: But we can improve reference docs
    • @brianmcgee: Mention footguns and tradeoffs
    • We can have a how-to guide
      • Discussion about where it should be in nix.dev, what title it should have
      • Let’s just brain dump and open a draft PR to review
  • @zmitchell: Will try to pick up shell.nix tutorial: Nix language primer with `shell.nix` · Issue #516 · NixOS/nix.dev · GitHub
  • Let’s think about merging things quicker even if not perfect

Action Items

  • @brianmcgee: Looking at reference docs for trivial builders, an hour
  • @zmitchell: Writing a shell.nix tutorial for an hour
  • @zmitchell: If time, looking at the redirect issue
1 Like