2023-05-11 - Learning Journey Working Group - Meeting Notes #8

Development Documentation
4

Can you list the learning goals that somebody following this would achieve?

Sure, no problem:

  • nix-shell -p python310
    • You can create an ephemeral shell environment that has certain packages in it that will no longer be in your environment when you leave the shell. This is useful for experimentation.
  • shell.nix
    • Note: We give a short shell.nix scaffold here and point the reader at literally two lines: including Python and setting an environment variable. We also tell the reader that the language will be explained in the next tutorial (not a nebulous “later”, literally the next tutorial).
    • Once you’ve experimented with packages in an ephemeral shell environment you can “save” and declaratively configure that shell environment.
    • You have avenues to declaratively configure other aspects of that environment, such as code to execute before entering the environment (shell hooks), setting environment variables, etc.
  • Nix language
    • Understand the basics of the Nix language such that you can understand the details of the shell.nix used in the previous tutorial.
    • Note: we intentionally introduce shell.nix before the language tutorial so that the reader isn’t just learning the Nix language for the language’s sake, they’re learning it via a specific application of the language.
  • Pinning nixpkgs
    • Your package dependencies have to come from somewhere, and that somewhere is nixpkgs.
    • In order for your build to be truly reproducible you have to pin your shell/derivation to a specific revision of nixpkgs.
    • Whether you want your build to be truly reproducible is up to you, and if you don’t want or need it to be so then you have options for how to specify where your packages come from.
  • Including Python dependencies
    • Self explanatory, how to include Python dependencies through nixpkgs rather than pip, poetry, etc.

That’s what we have right now, there are several more steps and subsequent meetings will fill out steps that come after what I’ve listed here. We’ve spent the last few meetings building out that knowledge graph and choosing the specifics of the project to meet a few goals:

  • Not be too difficult
  • Take the reader through a likely use case
  • Cover a wide variety of topics

Judging from this and prior discussions, which are kind of circling around the same set issues without conclusion,

I disagree with this characterization pretty strongly. Like I said, we spent a few meetings considering a range of possible projects the reader could walk through, discovering the difficulties that you run into in each case, and finally landing on the current project. In that sense we have a conclusion so I don’t know where “without conclusion” is coming from.

we may want to focus on pulling apart the concepts and skills involved in even the simplest setup

That’s what we’ve been doing until now. The other consideration is that I’d like the learner to be building towards something, not doing isolated tasks. That’s why it took us a while to settle on a project, there’s a lot of design constraints and finding a project that’s useful and threads the needle of learning small enough concepts in the right order is not easy.

Dumping a full 50LOC example on learners will not fly.

Not sure what you’re referring to here, the only things we’re “dumping” on the learners would be

  1. a short Python script, which is not what we’re trying to teach so I feel justified saying “just trust us that this makes a server”
  2. a shell.nix that looks like this:
# Don't worry if this looks alien, we'll explain it in the next tutorial!
{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  buildInputs = [
    pkgs.python310  # Add a package here
  ];
}

This is 6 lines, not 50, and we immediately explain it in the next tutorial. It sounds like there’s concern about cognitive overhead presenting new topics to the learner, and I hear that and wholeheartedly agree, but 6 lines feels manageable.

Happy to answer other questions or address concerns about the approach. I think we’ve chosen a path that has merit, but if there are other approaches that would better serve learners that also meet the design constraints I’m happy to hear those ideas.

3 Likes