2023-07-20 - Learning Journey Working Group - Meeting Notes #18

Development Documentation
1

Agenda

Notes

  • @zmitchell: Look at responses from call for feedback, add more details
    • From these past requests for feedback, it looks like most people ignore the proposal and talk about other things, very little feedback in general
    • Could change the format “We decided to work on this, please give feedback”, otherwise people are just suggesting ideas
    • How to get better feedback on these things?
    • How to reach the right people?
    • @henrik-ch: Be more concrete, put out a tutorial, ask people what’s wrong with it
    • @infinisil: Like @fricklerhandwerk’s tests of tutorials on new beginners. Maybe put tutorials on nix.dev already, but make it easier to give feedback and indicate that it’s new and needs it
    • @henrik-ch: Do like a Nix Hour style session where users can show up and go through a new tutorial
    • @zmitchell: Don’t have time for that, goal is to get on the right track first before writing tutorials.
    • @infinisil: Just write tutorials, don’t spend too much time reviewing and thinking about what they should cover. Then evaluate how different tutorials do in practice, encouraging feedback from users.
      • @zmitchell: Agree with getting it out the door quickly, not to bikeshed as much
      • @henrik-ch: I don’t think we need to A-B test the same tutorial, but just writing tutorials all over the place sounds good. If you think it could’ve been better, write a separate tutorial, also publish that, link them to each other.
      • @infinisil: Scan through linked tutorials on Matrix/Discourse/Reddit/Discord
      • @roberth: Volunteers do especially work on things they like. Merge fast, not go too detailed into reviews to make it more pleasurable.
      • @infinisil: Separate moving to nix.dev and curation, merge fast
      • @fricklerhandwerk: Disagree with taking contributions as they are, kind of like wiki then. Instead we could link to third-party tutorials and related material more often.
        • @infinisil: Can’t update easily
          • @fricklerhandwerk: Need to take ownership to update it. Less but better documentation.
        • @infinisil: Idea to merge things quickly, but warn that it gets removed after e.g. 1 year and remove them after 2 years if people aren’t indicating in an issue that they’re using it.
    • @roberth: The community doesn’t know how we work, should be clear about that
  • @zmitchell: add outline for trivial builders tutorial by brianmcgee · Pull Request #623 · NixOS/nix.dev · GitHub was closed, let’s look at it

Reviewing nix.dev #650

  • Have a default.nix containing a let pkgs = ...; in { hello = callPackage ./hello.nix { }; } (why attribute? Easier to later add more, good practice, can use the same command as for Nixpkgs)
  • Have a hello.nix as in the tutorial, instead of nix-build -E ..., nix-build -A hello
  • Don’t use builtin fetchers for sources (generally, only use builtin fetchers for private sources or Nix expressions (things needed for evaluation))
    • Then people also wouldn’t run into the builtins.fetchFromGitHub error
  • Introduce pkgs set and how it interacts with callPackage when first used, not only once lib is needed. Also: Don’t have pkgs in the arguments, bad practice.
  • fakeSha256 not needed anymore, empty hash is supported by recent releases (need to check if the stable Nix version in NixOS 22.11 (2.11) supports this already)

Restarting nix.dev #623

Purpose

  • Trivial builders: Create “simple” derivations as conveniently and ergonomically as possible.
  • Learning objective: Create modular components that the learner can put together in other derivations.

Prerequisites

  • Nix language
  • Derivations and store paths

Activity

  • Create a small utility first using runCommand then showing a more rigorous version with writeShellApplication
  • Use “This Month in Nix Docs” creation script as an example
  • Question: What is the distinction between writeFile, toFile, writeText, etc? Should we use those at all instead of writeShellApplication?

You could also create a small utility that uses pandoc to convert a file to a PDF:

# stuff.nix
let
  pkgs = import <nixpkgs> {};
  myStuff = ''
    # hello world
    
    this is some random stuff
  '';
  moreStuff = builtins.readFile ./foo.md;
  myFile = builtins.toFile myStuff + moreStuff;
in
pkgs.runCommand "blurb" {} ''
  ${pkgs.pandoc}/bin/pandoc -f pdf -i ${myFile} > $out
'';

$ nix-build stuff.nix
$ open ./result