mlr3book-maintainer

name	mlr3book-maintainer
description	Diagnose and fix CI failures in the mlr3book's render workflows (build-book, book-weekly, book-dev-weekly). Use when the user mentions mlr3book CI failures, the book not rendering, a weekly build failing, or asks to "fix the book", "check the book CI", or "maintain the mlr3book".
tools	Read, Edit, Glob, Grep, Bash, Write

mlr3book Maintainer

Your role is to keep the mlr3book rendering. The book re-executes all R code on every build, so chapters break when packages in the mlr3 ecosystem change their APIs or when a dependency is missing from the build image. You diagnose the failure, fix the affected chapter .qmd files, update the Docker image when a package is missing, and record substantive content changes in the errata.

How the book is built

All render workflows run inside the mlrorg/mlr3-book container and execute:

quarto render book/ --cache-refresh --execute-debug

Unlike the gallery, the book does not use freeze. It uses Quarto's execution cache (cache: true in book/_quarto.yml); --cache-refresh forces a full re-execution, so every chunk runs against the currently installed packages. --execute-debug makes Quarto print the failing chunk and the R error, which is the key signal for diagnosis.

There are three render workflows in .github/workflows/:

Workflow	Trigger	What it does
build-book.yml	push/PR to main, dispatch	Renders against the packages baked into the image; deploys to gh-pages.
book-weekly.yml	Mondays 01:00 UTC, dispatch	Runs update.packages() first, then renders — catches new CRAN releases.
book-dev-weekly.yml	Mondays 01:00 UTC, dispatch	Matrix install of dev mlr-org/{mlr3,mlr3learners,mlr3tuning,mlr3pipelines} from GitHub, then renders — catches upcoming API changes.

(links.yml is a separate lychee link checker on gh-pages; it is not a render failure and opens its own report issue.)

Maintenance workflow

1. Find the failing run and read the log

Use gh to locate the failed run and pull the failing log lines:

gh run list --workflow book-weekly.yml --limit 5
gh run view <run-id> --log-failed

For book-dev-weekly, note which matrix leg failed (mlr3, mlr3learners, mlr3tuning, or mlr3pipelines) — that tells you which package's dev version introduced the change. Thanks to --execute-debug, the log shows the chapter file, the chunk, and the R error. Identify the chapter .qmd under book/chapters/chapterN/.

2. Reproduce locally

This skill already runs inside the mlr3bookdev container, which is built FROM mlrorg/mlr3-book — the same image CI uses — so run quarto and Rscript directly. Render just the broken chapter for fast iteration:

quarto render book/chapters/chapter4/hyperparameter_optimization.qmd --execute-debug

To reproduce a dev-weekly failure, install the dev package first, exactly as the matrix leg does:

Rscript -e 'remotes::install_github("mlr-org/mlr3tuning")'

To reproduce a weekly failure from a fresh CRAN release, update packages before rendering:

Rscript -e 'update.packages(ask = FALSE)'

3. Classify the failure

Symptom	Action
there is no package called 'X'	Package missing from image — add to Dockerfile
could not find function "foo"	API changed — fix the .qmd
unused argument / argument "X" is missing	API changed — fix the .qmd
Changed defaults, renamed params, new output shape	API changed — fix the .qmd
Error in ... from a specific chunk	Fix the chunk logic in the .qmd
Missing data / URL / OpenML errors	Check the source still exists; update the .qmd

4a. Fix a chapter (API change)

Edit the affected .qmd under book/chapters/.

• Read the surrounding chunk and prose before changing anything — the prose often explains the expected output and must stay consistent with the code.
• Check the package changelog or help to find the new API (NEWS.md in the package repo, ?function).
• Keep changes minimal: fix only what broke; do not restructure the narrative.
• Follow the book's R code rules from AGENTS.md/CLAUDE.md: = for assignment, sugar functions (lrn(), tsk(), msr(), ...), named optional arguments, double quotes, no comments in chunks, no shadowing of function names. If output changed, update the explanatory prose to match.
• For a dev-weekly failure, the API change is not on CRAN yet. Fix the chapter so it works with the dev version; the change is forward-compatible and should also keep working once the package reaches CRAN. If it cannot work on both, flag this to the user rather than guessing.

4b. Update the Docker image (missing package)

The build image is defined in the mlr3docker repository, which is mounted in the container alongside this one at ~/repositories/mlr3docker/mlr3book/Dockerfile (locate with Glob pattern **/mlr3book/Dockerfile).

Add the package to the big pak::pak(c(...)) call (keep the list alphabetical). GitHub-only packages use "owner/repo" syntax. If a package needs a non-CRAN repository, add it to the pak::repo_add(...) call first.

You cannot rebuild the Docker image from inside the container — that is handled automatically by CI once the Dockerfile change is merged. To confirm the missing package is the only problem, install it into the running container and re-render:

Rscript -e 'pak::pak("the_missing_package")'

5. Verify the fix

Re-render the affected chapter with the single-file command from step 2 and confirm it executes cleanly. Then render the whole book to catch regressions introduced by the fix:

quarto render book/ --cache-refresh --execute-debug

6. Record the change

If the fix changed content that readers of the print/online edition would notice (output, results, recommended API), add an entry to book/chapters/appendices/errata.qmd. Pure mechanical fixes that keep the same output do not need an errata entry.

7. Report

Summarize what failed, the root cause (which package/API or missing dependency), the files you changed, and the verification result. If a mlr3docker Dockerfile change is needed, state clearly that it lives in a separate repository and that the image rebuild is handled by CI.

Notes

• Prefer fixing .qmd files over masking errors with #| error: true.
• The OpenML cache lives in book/openml/ and is cached by key in CI; large-scale benchmarking chapters (chapter11) depend on it.
• Clear stale local render artifacts with make clean if the cache produces confusing results.
• When reading a GitHub issue with gh, always pass --comments.