Commit notebooks without cell outputs, execution counts or editor metadata (such as
collapsed or scrolled), so that diffs show only real changes. A pre-commit hook strips
them for you:
pip install pre-commit
pre-commit install # once per clone: the hook then runs on every `git commit`
pre-commit run --all-files # check (and fix) every file nowCI runs the same hook and fails if it would change a notebook.
- Python: black with the settings in
pyproject.toml. - Shell: shfmt with 4-space indentation (
shfmt -i 4). - Scala: scalafmt with
.scalafmt.conf, forsource/*.sc, theriscv/project and the code cells of the notebooks.
The pre-commit hooks above run black and shfmt. scalafmt needs a separate binary (download the
version named in .scalafmt.conf from its releases, or cs install scalafmt); then
python3 tools/format-scala.py # formats source/*.sc, riscv/ and every notebook's Scala cells
python3 tools/format-scala.py --check # what CI runstools/format-scala.py leaves alone the cells that scalafmt cannot parse, such as a deliberate
syntax error (see its docstring). CI checks all three styles.
Out of scope: the shell commands inside the Dockerfile and the workflow run: steps. The formatter versions are pinned in .pre-commit-config.yaml
and .scalafmt.conf; bump them by hand (pre-commit autoupdate for the hooks; a new scalafmt
version also needs its checksum in .github/workflows/checks.yml).
python3 tools/check-versions.py # pinned versions agree across the repository
python3 tests/test_notebooks.py --self-test # links, images, alt text, removed APIs, runtest.pytools/check-versions.py compares every pinned version with the Dockerfile (the files and
patterns are in its CHECKS table) and checks that FIRTOOL_VERSION is the firtool version
Chisel was published against. To upgrade a version, change it everywhere the script reports.
tests/test_notebooks.py rejects mentions of removed Chisel 3 APIs (its REMOVED_APIS). A
deliberate mention, such as a migration note, is
allowed by adding <notebook> <API> to tests/lint-allowlist.txt; code cells are never allowed.
runtest.py runs notebooks in the Scala kernel and compares the errors they raise with the
expected ones (exercises with ??? and cells that fail on purpose raise errors by design).
In the Docker image, without network access:
docker build -t chisel-bootcamp .
docker run --rm --network none chisel-bootcamp python3 runtest.py 2.1_first_module.ipynb
docker run --rm --network none chisel-bootcamp python3 runtest.py # every notebookLocally (see Install.md), run python3 runtest.py <notebook> from the repository root.
BOOTCAMP_CELL_TIMEOUT sets the per-cell timeout in seconds (default 600). runtest.py treats
every deprecation warning as an unexpected error. The warning names the deprecated call, except
for code in source/load-ivy.sc, which only gets a count: compile the suspect definitions in a
cell of their own to see the details.
Exercises in riscv/src/ contain ???; their reference solutions are in riscv/solutions/ at the
same paths (see riscv/DESIGN.md). tools/check-solutions.sh checks that the scaffold compiles
and that the solutions pass every test; run it after changing either.
- Add an entry to the
notebooksdict inruntest.pywith the errors it is expected to raise, in order. CI runs every registered notebook on pushes todevand nightly; a pull request runs a smoke subset plus the notebooks it changes, or every notebook when it changes shared files such assource/or the Dockerfile (seetools/ci-notebooks.py). - Link it from the previous notebook's Prev/Next links (and link back to the previous one
from the new notebook), and add it to the outline in
README.md. - Give every image non-empty alt text.
- Format its Scala cells (
tools/format-scala.py), then run the checks above andruntest.pyon the new notebook.