30.8  Contributor Guide

This book is maintained as a software project. Its pages are generated from Git-tracked source files, executed by a build system, and reviewed as code. This section explains the build, the Git workflow for contributions, optional use of coding agents, and the checks required for a patch. The same single-source, generated-artifact, and executable-document concerns arise in many machine learning documentation and experiment repositories.

30.8.1 How the Book Is Built

30.8.1.1 One Source, Many Artifacts

Each section is stored in a single Markdown file — for example, this one is chapter_appendix-tools-for-deep-learning/developers-guide.md. From these sources the build derives everything else:

chapter_*/*.md               source of truth (edit these)
├── chapter_*/*.qmd          generated Quarto input → HTML site and PDFs
├── _notebooks/<fw>/...      generated Jupyter notebooks, one per framework
│   └── outputs/...          executed outputs, committed to the repository
└── _slides/<fw>/...         generated lecture slides

This design has three practical consequences:

  • Never edit generated files. A .qmd or .ipynb edit is destroyed by the next build. Edit the .md source and regenerate.
  • Framework tabs live in one file. A code block tagged %%tab pytorch appears only in the PyTorch view; an untagged Python block appears in every framework’s notebook. One source file thus yields up to four notebooks that must all execute.
  • Cell identity is stable. Every Python block carries a permanent ID (assigned by tools/add_cell_ids.py) so that slides, executed outputs, and framework views can refer to a cell across renames and moves.

Why Markdown sources instead of committing notebooks directly? Version control. A .ipynb file is JSON that combines code, outputs, execution counts, and editor metadata, producing noisier diffs than the Markdown source. Markdown source produces readable prose diffs; executed outputs are stored separately (and only re-blessed when the code that produced them changes); and one file drives the website, the PDF, four notebook sets, and the slide decks without four copies drifting apart.

The d2l library you have imported all book long is generated the same way: every block marked #@save is extracted into the per-framework modules (d2l/torch.py, d2l/jax.py, …). Change the function where it is taught, rebuild, and every later chapter sees the fix — the reason those files also carry a “do not edit directly” banner.

30.8.1.2 The Repository at a Glance

d2l-neu/
├── chapter_*/            source Markdown, one directory per chapter
├── img/                  figures (SVG, generated by tools/gen_*_figures.py)
├── d2l/                  the generated d2l library
├── outputs/              committed store of executed notebook outputs
├── tools/                build scripts (preprocessing, notebooks, slides)
├── Makefile              entry point: make html, make slides, make lib ...
└── CLAUDE.md             build documentation, written for coding agents

make html renders the site from committed outputs on any laptop — no GPU required; executing notebooks that need accelerators is a separate, explicit step. The Makefile and CLAUDE.md document the supported targets.

30.8.2 Git in Five Minutes

If you already use Git daily, skip ahead. Otherwise, the commands below establish the main contribution workflow. First, make your own copy: click Fork on the repository page, then

git clone https://github.com/<your-username>/d2l-neu.git
cd d2l-neu
git switch -c fix-typo-in-attention    # a branch per change

Edit the source .md file, then record and publish the change:

git status                  # what changed?
git diff                    # show the exact edits
git add chapter_attention-mechanisms/attention.md
git commit -m "Fix transposed subscript in attention equation"
git push -u origin fix-typo-in-attention

GitHub will offer to open a pull request — your branch, proposed for merging, with a diff the maintainers can review and comment on. (The gh command-line tool does the same with gh pr create.) Small, focused pull requests are easier to review than changes spanning several chapters. The fork-branch-pull-request workflow is common in open-source projects and makes each proposed change explicit.

30.8.3 Working with a Coding Agent

Coding agents can assist with bounded repository tasks such as locating a definition, propagating a mechanical change, or running verification. Their use is optional, and generated edits require the same review as human-written changes. This repository supports agent-assisted work through three properties:

  • The build is self-describing. CLAUDE.md tells an agent how to regenerate, execute, and render the artifacts. The same explicit build instructions also support human contributors.
  • Verification is executable. The definition of “this edit works” is mechanical: the notebook executes top to bottom in all frameworks, the linter passes, the page renders. An agent can run the edit, regeneration, execution, and failure-inspection loop, but the contributor must review both the final diff and the evidence from the checks.
  • The tedious parts are mechanical. Keeping four framework implementations in sync, checking that every :numref: resolves, and regenerating figures are mechanical multi-file tasks that can be automated and then reviewed.

A useful workflow specifies the intended change and its verification, for example: “the momentum notebook’s contour plot mislabels the axes; correct the source and rerun the affected notebooks.” The agent may locate sources, edit, and run checks, but the contributor remains responsible for reviewing the diff and validating the technical result. Two cautions apply. Agents can share the newcomer failure mode of editing generated files unless the project documentation warns them (ours does). And an agent eager to make a failing check pass may weaken the check or the code instead of fixing the cause — “the notebook now runs” is not the same as “the notebook still teaches the right thing.” Review accordingly.

30.8.4 Contributing Your Changes

Contributions range from one-line corrections to executable content changes:

  • Small text fixes. For a one-line fix you do not even need a local checkout: open the source file on GitHub, press the edit (pencil) button, and GitHub walks you through fork, commit, and pull request in the browser.
  • Code and content changes. Clone, branch, edit the source .md, and verify before submitting: regenerate the affected notebooks and run them end to end and render the page with make html to check formatting, references, and figures. If you edit code that carries #@save, rebuild the library (make lib) and expect downstream notebooks to be affected.
  • Working in the notebook view. If you prefer editing in Jupyter or VS Code rather than raw Markdown, this repository ships a VS Code extension (under .vscode-extension/) designed for this workflow: it opens the generated notebook for any section with the right kernel preselected, switches between the PyTorch/TensorFlow/JAX/MXNet views of the same source, previews the section’s slide deck live, and syncs edits from the notebook back into the Markdown source so that generated files never become the thing you edited. make kernels registers the per-framework Jupyter kernels it uses.

Whatever the route, the review bar is the one this chapter has been teaching throughout: the change executes cleanly from a fresh state, in every framework it touches, and the source of truth — never a generated artifact — is what changed.

30.8.5 Summary

  • One Markdown source generates the website, PDFs, per-framework notebooks, executed outputs, slides, and the d2l library; generated files are never edited directly.
  • Markdown-as-source exists for version control: readable diffs and reviewable pull requests are what make a 250-notebook book maintainable.
  • The contribution loop is fork → branch → edit source → verify (execute notebooks, render) → small pull request.
  • Coding agents can automate parts of this workflow because the build is documented and verification is executable; contributors must review and take responsibility for submitted changes.
  • The VS Code extension bridges notebook-style editing and Markdown-source truth: framework views, slide preview, and sync-back.

30.8.6 Exercises

  1. Fork the repository, run make html, and render the book locally. How long does a no-op rebuild of one page take?
  2. Find the #@save block that defines a d2l function you have used, change its docstring, rebuild the library, and verify the change is visible from a notebook import.
  3. Use a coding agent for a real micro-contribution: have it find a typo or broken link in a chapter of your choice, fix the source, and verify the render — then review its diff as if you were the maintainer.
  4. Open the generated PyTorch and JAX notebooks of one section side by side (the VS Code extension makes this two keystrokes). What exactly differs, and where does that difference live in the source file?