The Learning Journey Working Group is working on its next set of tutorial outlines.
We make these outlines so that contributors that want to help out and write tutorials can just pick something up and start working on something with minimal onboarding time.
We solicit feedback in this way because we’re a small team with limited Nix experience compared to many of the experts in this community, so we’d like to leverage the community’s expertise.
This is the second call for feedback, the first is posted here: 2023-06-19 Tutorial Series Call for Feedback #1. That call for feedback was posted in a relatively low-traffic part of this site, so we didn’t get much feedback (that’s on me).
The intention is to post these once per month since that’s the cadence at which we’ve decided to work on these tutorial outlines.
How you can help
Suggest activities
For each of these tutorials we’d like the user to walk through some activity that will put them into contact with the topic of the tutorial.
We’ll have some ideas of activities users can walk through on their own, but more suggestions at this stage of the process will always be better.
So, the first thing you can do is provide suggestions for activities that users can do on a particular topic.
Where do users get stuck?
The next thing you can do is provide us with insight into where users get stuck on these topics.
Even if all of us in the Working Group were experts, we don’t know everyone using Nix, and we certainly don’t know where everyone gets stuck.
If you have experience helping users with these topics, please point out the major pain points or stumbling blocks.
Make us aware of the traps
Anyone who has ever used a computer has had the “how hard could it be” experience that turns into a rabbit hole of complexity.
If you know that a particular topic we’ve chosen has hidden complexities, we’d like to hear about them so that we can keep the reader on a happy path until we intentionally decide to present any complexities.
For example, if you bring python310 and python310Packages.pip into a nix-shell -p environment, you can’t just install Python packages with pip install like you would outside of a Nix shell.
Tutorial ideas
Feel free to leave comments on the GitHub issues linked below or leave comments in this thread.
nix-shell -p
The intention is for this tutorial to be the first interaction a user has with Nix since it has minimal weirdness: you say “put me in a shell with these packages”.
The tutorial needs to provide an activity in which using nix-shell -p solves a real problem. Note that this doesn’t have to be a huge problem, it just has to be a real motivating example rather than a contrived situation in which nix-shell -p can be used to help you out of the situation.
The common use case for nix-shell -p is probably “I want to run a single command with this program and then I never want to see it again,” but it’s hard to write a tutorial around that.
Questions:
- Are there any common situations in which you’ve used
nix-shell -p? - Do you ever use reproducible scripts with
nix-shell -pi.e. do you have scripts that have a#!/usr/bin/env nix-shellline followed by a# nix-shell -i <interpreter> -p <packages>line?
shell.nix
This tutorial is already pretty well defined, but concrete ideas for which aspects of shell.nix you typically configure are welcome. For example, setting environment variables is trivial, but also really useful. Modifying hooks are useful for doing setup when you enter the environment.
Questions:
- Which configuration features of a
shell.nixfile do you use? - What’s your workflow when you use a
shell.nixto configure a development environment? Do you always typenix-shellor do you use something likedirenv? Do you have any automatic setup done for you with shell hooks or other mechanisms? If so, what’s the use case?
Pinning nixpkgs
The idea here is to show users why they might want to pin nixpkgs, and then show them how to do so with different levels of reproducibility/rigor. If you’re iterating on a package it can be surprising when it suddenly decides to rebuild/substitute a bunch of dependencies (“haven’t I already built this?”).
Questions
- Do you have any tricks or shortcuts for looking up the particular nixpkgs revision you want to pin to? This could be a script or one-liner that retrieves the commit hash, etc.
- Other than maximum reproducibility and avoiding rebuilds, do you have other use cases for pinning nixpkgs?
- Are there any aspects of pinning nixpkgs that you’d like to see discussed?