What a narrative and a tutorial need

The project is a uv project

uv is the tool that makes the Python environment of a project from its lockfile, uv.lock.

• Make the project a uv project from its first commit. Commit pyproject.toml with [project] and a build system, .python-version and uv.lock.
• Run every command through uv run or a just recipe. This rule holds in the notes and in the recipes.
• Never use the Python of the system, and never set PYTHONPATH. The environment of each step comes from the lockfile of that step.

The history

• Give each step one annotated tag. The message of the tag is the note that the audience sees.
• Keep the commits on a straight line. timewalk finds the moves on the first-parent line, and a straight line keeps every commit on it.
• Name the tags to match the glob of the walk. The default glob is step-*.

See Making the steps.

The description

• Give each walk a description in toc.toml. Say what the walk is about, in a sentence or two. The status band under the step bar shows it at the first step of the walk.
• Give each tag a short title, a blank line, and then a sentence or two. The band shows the title in bold.

See The status band.

The notes

Keep the notes file outside the repository, in the class folder. Give each step one ## step section. Each section has these parts:

• $ just setup as its first command.
• What the step builds, and why, in terms of the program.
• Each command, with the result to expect.
• Cues and questions for the class. A cue is a line that starts with > .
• Optionally, time:, the planned start of the step.
• Last, a line files:, with an item and its words for each file to read.

Write the text for a reader who knows the program, and not timewalk. See Write for a reader who has never heard of timewalk.

Use runs$ for a command that takes a long time, and main$ for a command that only reads your repository. See Notes.

The slides

• Give each walk a manifest of its own. The manifest is the TOML file that says which slides go with which step.
• Give every step an entry, even of one slide.
• Keep the slide files and their pictures in a slides folder of a walk. The page serves slides only from those folders.
• Keep the notes and toc.toml out of the slides folders.
• Never put a manifest at the top of the class folder.

See Slides and documents and Several walks.

The recipe just setup

The justfile of the project has a recipe setup. It makes the environment and the artifacts of the step, and nothing more.

• Make it safe to run again. A second run changes nothing.
• Make the environment, for example with uv sync.
• Make the artifacts that are missing.
• Never touch git. just setup makes no commit, branch or tag, and changes no config or hook. A step that changes git, for example to install a hook, gives it a recipe of its own. See just setup and git.

Artifacts

An artifact is a file that a step needs and that git does not hold, for example a corpus or a report.

• Put each artifact in a folder that git ignores.
• Make each artifact the same way each time, from the files of the step.
• Make it again when it is missing. A learner can jump straight to a later step. Then just setup at that step must make every artifact that the step needs.

Moves

A move is one small commit between two tags, on the first-parent line. The first-parent line is the line of commits that git follows back through the first parent of each merge.

• A move needs no name in its subject. timewalk names it by its place, so the subject can say anything, or nothing, as jj new leaves it. Its title comes from its ### heading in the notes.
• Keep the subject of the step on its last commit, for example step-02: the tests pass. That commit carries the tag.
• Expect no moves in the first step, or in a step of one commit.
• Give moves to the first steps after the first one, for example to step-01. Then the class meets moves early.
• Keep one step without moves after the first step. Then the class also meets a step of one commit, which ends with Next step.
• Give the tutorial every tag of its glob. A tutorial cannot have steps = [...]. For a tutorial on one part of the history, name its steps and moves with select. See Take a small walk out of a big one.

See Commits for a tutorial, Moves with jj, and Steps and moves as git.

Keep each move small

• Make each move one atomic action, small enough to type from the notes. An atomic action is one change that makes sense alone, for example one test or one new function.
• Make each move work alone. After each move, the anchor commands run and give the result that the notes state.
• Keep each move small enough to explain in a few paragraphs. The text tells the story of the move. The items under files:, their words and their excerpts are the reference that the learner checks the story against.

Write for a reader who has never heard of timewalk

A learner reads the notes in timewalk, or in a copy of the tutorial. A learner can also read them on a page that a class makes from the facts file of the walk. The facts file is the JSON file that timewalk-export --json writes. See The facts file.

The reader knows the program, or wants to learn it. The reader does not know timewalk, and does not need to. These rules hold for every walk, a narrative too.

• Keep timewalk’s words out of the text. “step”, “commit”, “Start”, “Before the moves” and a name such as step-02.4 are timewalk’s words. Do not write them in the text of the notes. The heading ### step-02.1 Title keeps its name, because timewalk needs it. Only its title is for the reader.
• Say once what a move is, in the intro of every tutorial. Always write this explanation. The intro is the text of the notes before the first step, or the walk’s intro. A move is one small change, made by one patch or one command. The learner makes each move, and the page checks the learner’s files against it. After the intro, the text can use the word “move” anywhere.
• Open a step with what we build, and why, in terms of the program. For example, write “We cannot tell whether tally still works after a change, so we write tests.” Do not write “The commits of this step add tests.”
• Open a move with the problem, and the change that solves it. Do not open with “Now we add X”, and do not open with a list of files or a link to a diff.
• Then give the change, piece by piece. Each piece says in the shared text what it changes, and why. The shared text is the text outside the blocks for one mode. See Write for both modes.
  • Each file of the move comes from one line. A do$ line gives a command that writes the file. A patch$ line names a file that the move changes by a patch. Do not copy the code into the notes. The code comes from the project. See patch$ lines.
  • In do mode, say what to read in each patch, and where in the file, for example “after the line X” or “in place of the function f”.
  • In watch mode, say what the change does, and where to see it. “Read the change of pyproject.toml.” alone explains nothing.
• Then give the check. Give a command, what it prints, and what that shows.
• Last, write files:, with an item and its words for every file of the change, uv.lock too. Do not write a list of the files in prose, such as “These files change:”. A page made from the facts file makes that list from the facts.
• Keep the same rules in the text of a small walk. Its intro and the text at its stops are for the same reader. See Write a move to read alone.

The diffs are the data that the learner checks against. They help, but they are not the explanation. So the text above files: must explain the change without them.

patch$ lines

A line patch$ PATH says that the move changes the file PATH by a patch. The patch is the diff of the move’s commit for that file. Write a path with a space in backticks, for example patch$ `my file.py` . Put the line in the section of the move, in the shared text, after the words that explain the change.

A script, `scripts/corpus.py`, writes `data/corpus.txt`, 2000 words from a short list. The script comes
whole, as a patch.

patch$ scripts/corpus.py

• In do mode, the line shows a button. ⇣ Apply patch PATH applies the patch to the learner’s file. If the learner has changed the file, ⇄ Replace with the move’s file PATH shows instead. See patch$ buttons.
• In watch mode, the line is one button that opens the diff. It says what the move does to the file. A new file reads ± See the new file PATH, and a changed one ± See the change to PATH.
• In the copies and on a class’s pages, the do mode gives a command that applies the patch from GitHub. The watch mode links to the diff.

A file that a do$ line writes needs no patch$ line. If the move then changes that file further, it needs a patch$ line too. Make each move as small as it can be. A move does one thing, a patch or one do$ line. A command on a file that a patch brings in gets a move of its own.

The section of each move

Write the text of the step before its first move section. That text is about the whole step. The notes column shows it in a section of its own, under the title of the step. Put $ just setup there, and say what the step builds, and why.

Give each move a ### step-NN.k Title section, in the order of the commits. Each section has these parts, in this order:

• The problem, and the change that solves it, in the shared text, for both modes.
• The change, piece by piece. Each file comes from a do$ line or a patch$ line, in the shared text. In a do block, say what to read in each patch, and where in the file. Copy no code. In a watch block, say what the change does, and where to see it. See Write for both modes.
• One or more anchor commands, in the shared text. An anchor command is the check of the move. Make it safe to run again, and say what it prints and what that shows. A test that fails is a good anchor, if the notes say that it fails. The notes column shows the anchor commands under the label “Check it”.
• Last, a line files:, with items. Give an item to every file of the commit, uv.lock too. Give every item words that say what to look for in the file.
• A show: line for the main line of the move. Under its item, quote that line of the change. The notes draw it as an excerpt, and the reader marks it. Put the line in one backtick. If the line has a backtick in it, put it in two backticks, for example show: ``The command `wikiapp` runs.``. See Quote a line with backticks.

files:
- diff `src/tally/__init__.py`: one word, `lower()`, answers the failing test.
  show: `for word in text.lower().split():`

See Tutorial walks and The items under files.

Write for both modes

A tutorial has two modes, and the class can change the mode at any time.

• Do mode: the learner makes each move by hand. So the learner must be able to make the move from the notes alone.
• Watch mode: timewalk checks out the commit of each move. The code jumps. So the notes and “What changed” must say what happened.

Most of a move reads the same in both modes. Only the doing and the showing differ. Put the words of one mode in a block for that mode, ::: do or ::: watch, closed by a line :::. The page shows a block only in its mode, and the text outside the blocks in both modes. Call that text the shared text.

Put as much as you can in the shared text, as long as it reads well in both modes. Keep the blocks short, with only what differs between the modes.

• In the shared text, keep what both modes need:
  • the problem, and the change that solves it, before the blocks. For example, write “tally prints every word, and a long text fills the screen. An option --top N prints only the N most common words.”
  • the explanation of each piece of the change
  • a patch$ line for each file that the move changes by a patch
  • each command that makes the move, as a do$ line, which the part below explains
  • the commands that check what happened, for example $ just test and $ uv run tally --top 3 data/corpus.txt. The checks at the end of the move are its anchor commands.
  • last, the line files: with its items and show: lines
• In a do block, say what to read in each patch, and where in the file. Copy no code. The learner applies the patch with its button, or makes the change by hand. The tab Yours and step-NN.k shows what still differs.
• In a watch block, say what the change does, and where to see it. The code is already there, so name the file and the line.

### step-02.2 A test of an empty text

An empty file is a text with no words. `count` must give an empty dictionary for it, and not fail. A
test in a file of its own, `tests/test_empty.py`, says so, and keeps it true after later changes.

patch$ tests/test_empty.py

::: do
Read its one test, `test_empty`, before you run it.
:::

::: watch
The new file `tests/test_empty.py` holds one test, `test_empty`. It gives `count` the empty text `""`,
and expects the empty dictionary `{}`.
:::

$ uv run python -m unittest discover -s tests -q

The new test passes at once. `split()` finds no words in an empty text, so `count` gives `{}`.

files:
- diff `tests/test_empty.py`: an empty text counts nothing.
  show: `self.assertEqual(count(""), {})`

git runs a hook only if the hook is executable. This command makes it so:

do$ chmod +x hooks/pre-commit

### step-06.1 The formatter

The code of tally mixes single and double quotes, and the blank lines differ from one function to the
next. A formatter writes every file in one style, so that a later change shows only what it changes.
ruff is a formatter and a linter. A linter reads the code and reports mistakes that the tests do not find.

First we install ruff in the group `dev`. The group `dev` is for the people who work on tally, so a user
who installs tally does not get ruff. `uv add` writes ruff into `pyproject.toml` and `uv.lock`, and
installs it in `.venv`:

do$ uv add --dev ruff

::: watch
In `pyproject.toml`, the table `[dependency-groups]` now has the group `dev`, with the line
`"ruff>=0.17.0",`. In `uv.lock`, the entry `name = "ruff"` gives the exact version that `just setup`
installs.
:::

$ uv run ruff --version

The command prints the version of ruff, so ruff is installed.

Then we format the code, and let the linter fix what it can fix:

do$ uv run ruff format src tests
do$ uv run ruff check --fix src tests

::: watch
In `src/tally/__init__.py`, each string now has double quotes, and two blank lines come before each
function. The code does the same as before.
:::

$ just test
$ uv run tally --top 3 data/corpus.txt

The tests pass, and the command prints the same three lines as before. So the formatter changed how the
code looks, and not what it does.

files:
- diff `pyproject.toml`: ruff, a tool for development only.
  show: `"ruff>=0.17.0",`
- diff `uv.lock`: the exact version of ruff, which every learner gets with `just setup`.
  show: `name = "ruff"`
- diff `src/tally/__init__.py`: double quotes and blank lines. The code does the same.

Write a move to read alone

A small walk can take one move, or a few moves, out of the tutorial. Its notes column then shows the section of the move without the text of its step, and without the moves before it. See One notes file for several walks. So write each move section to read well alone:

• Do not lean on the text of the step before the move. Do not write “as we said above” or “the file from the last move”. Say again what the reader needs.
• Name the files of the move. Write each path in full, in the text and in the items.
• Name the commands of the move. Give each command to type, and its anchor commands, in the section of the move.
• Put the setup at the top of the section of the step. The commands before the first words of the step’s section, for example $ just setup, show at the Start of every small step. Put there each command that a move needs before it starts. The text after them shows only at a whole step.

## step-05 Types

$ just setup

ty checks the types. The step adds it, then types in the code and the tests.

### step-05.3 The linter asks for types

A small step of step-05.3 shows $ just setup, then the section of step-05.3. It leaves out the sentence about ty.

Settings

• Set moves = "do" or moves = "watch" in toc.toml, for the mode that the tutorial starts in.
• Set sync for each walk. With sync = true, the default, the slides follow the moves.
• Quote the slide keys of moves, for example "step-02.1" = ["moves.md#1"].

What timewalk-check reports

timewalk-check stops at the first mistake in toc.toml, and reports it as an error:

Then it checks each walk, and reports every problem that it finds:

In a tutorial, it checks the items, the show: lines and the anchor commands in each mode. A warning for one mode names it, for example “step-02.1 has no command in watch mode”.

timewalk-check exits with code 1 when it finds an error. timewalk runs the same checks when it starts, and does not start after an error.

Where each file comes from

A file of a move gets its content in one of two ways. A do$ line writes it, for example uv add writes pyproject.toml and uv.lock. Or a patch brings it in, and a patch$ line names it. The notes copy no code for the reader to type. Every diff and every file that a reader sees comes from the history of the project, or from the learner’s own files.

timewalk-check runs the do$ lines of each move at the commit before the move, in a scratch clone. It notes the files that each line writes, and warns of these cases:

• a file that no do$ line writes, and no patch$ line names
• a file that the move changes after its do$ line, with no patch$ line
• a do$ line that writes outside the move
• a do$ line that fails. One case is not a warning. The line is the move’s last do$ line, and it ends with an error code from 1 to 125. It writes a file of the move that no patch$ line names, and the move has no other problem. A timeout, or a command that is not found, is always a warning. For example, ruff check --fix writes its fixes to the files. Then it ends with error code 1, because of the problems that it cannot fix.

Each warning marks a move that does not do one thing. A patch$ line that names a file that the move does not change is an error. See timewalk-check.

timewalk-export --json puts the result in the facts. It gives the files that each do$ line writes, and for each file, where it comes from and its patch. A class’s pages show the patches from there.

Run the commands of a walk

A command in the notes must work at the commit where a learner meets it. timewalk-check runs the do$ lines, but not the checks. Run each command at its place:

• In a narrative, run the commands of a step at its tag.
• In a tutorial, run the commands of a step before its first move at the start of the step. The start is the tag before it.
• In a move, run the commands of its section at the commit of the move.

A short Python script can do this through the code of timewalk, in a throwaway replay copy:

import subprocess, sys
from pathlib import Path
import timewalk
from timewalk.walks import load_toc

repo_path, toc, walk_id, replay = Path(sys.argv[1]), Path(sys.argv[2]).resolve(), sys.argv[3], Path(sys.argv[4])
walk = next(w for w in load_toc(toc) if w.id == walk_id)
repo = timewalk.Repo(repo_path, replay=replay)     # a replay copy to throw away; a move keeps edits on a saved branch
repo.select(walk.tags, walk.steps, tutorial=walk.kind == "tutorial")
notes = timewalk.parse_notes(walk.notes.read_text())
for step in repo.steps:
    repo.move(step.index)               # a narrative step at its tag; a tutorial step at its start
    names = [m.name for m in repo.moves[step.index]]
    for part in notes.get(step.name, {}).get("parts", []):
        if part["kind"] == "move" and part["name"] in names:
            repo.move(step.index, move=names.index(part["name"]) + 1)   # a move at its own commit
        elif part["kind"] == "command":
            where = repo.main if part["track"] == "main" else repo.work
            done = subprocess.run(part["text"], shell=True, cwd=where)
            print(step.name, repo.position(), "exit", done.returncode, part["text"])

In a clone of timewalk, run it with uv run python run.py repo toc.toml tutorial /tmp/replay. Then compare each exit code with what the notes say. A test that the notes say fails gives exit code 1.