cs249r_book/book/docs/CONTRIBUTING.md

Contributing to the ML Systems Textbook

The Machine Learning Systems project welcomes contributions from everyone. This project is maintained by a community of contributors from around the world. We appreciate your help!

Your contributions are welcome and can encompass a variety of tasks, such as:

• Identifying and reporting bugs or errors in the text
• Correcting typographical errors
• Improving chapter content or explanations
• Creating or improving figures and diagrams
• Adding quantitative examples or exercises
• Enhancing the accessibility of the material
• Suggesting topics for new content

Please read our Code of Conduct before contributing.

If you are unsure about whether a contribution is appropriate, feel free to open an issue or start a discussion.

Repository Structure

This is a two-volume textbook built with Quarto:

• Volume I: Introduction to Machine Learning Systems — Foundations for single-machine ML systems
• Volume II: Machine Learning Systems at Scale — Distributed systems at production scale

The key directories are:

book/quarto/contents/
├── vol1/          # Volume I chapters (introduction, training, hw_acceleration, etc.)
├── vol2/          # Volume II chapters (distributed_training, inference, etc.)
├── core/          # Shared content (dl_primer, frameworks)
├── frontmatter/   # Preface, acknowledgments
└── backmatter/    # Appendices, bibliography

Each chapter directory contains:

• A .qmd file (the chapter source)
• An images/ folder with png/ and svg/ subdirectories

Quarto configuration files are in book/quarto/config/ with volume-specific variants (e.g., _quarto-html-vol1.yml, _quarto-pdf-vol1.yml).

How to Contribute

1. Open an Issue

If there is an open issue for the contribution you would like to make, please comment on the issue to let us know you are working on it. If there is no open issue, please open one first.

2. Fork and Clone

Fork the repository on GitHub and clone your fork:

git clone https://github.com/YOUR_USERNAME/cs249r_book.git
cd cs249r_book
git remote add upstream https://github.com/harvard-edge/cs249r_book.git

The upstream remote is read-only. You will push to your fork and open a Pull Request to merge upstream.

3. Set Up the Development Environment

Run the one-time setup command:

./book/binder setup

This installs the pre-commit hooks declared in .pre-commit-config.yaml (EPUB source hygiene, vault corpus-guard, BibTeX validation, figure-div syntax, and ~60 other checks) and runs ./binder doctor to report the state of your tooling (Python, Quarto, Java, epubcheck, and so on).

Every book-check-* hook calls ./book/binder check <group> — the same commands you can run locally. See BINDER.md for the full check/fix reference and pre-commit mapping.

Without this step, the config file ships with the repo but the framework is never actually invoked on your commits — so bugs that the hooks would have blocked can slip through to CI and waste the maintainers' review time. Run it once per fresh clone.

If setup reports pre-commit is missing, install it with pip install pre-commit (or activate the project's virtualenv that includes it) and re-run.

4. Create a Branch

Always branch from dev, not main. Use descriptive branch names with the issue number:

git checkout dev
git pull origin dev
git checkout -b iss14-fix-typo-in-introduction

Examples: iss5-add-new-example, iss42-fix-figure-caption, iss100-improve-training-section.

5. Make Your Changes

Please make sure that your changes are consistent with the style of the existing content.

• Chapter content lives in book/quarto/contents/vol1/ or vol2/. Each chapter has its own directory.
• Images go in the chapter's images/png/ (raster) or images/svg/ (vector) subdirectory.
• Editorial standards: For prose contributions, please review the style conventions in the repository. We follow an academic textbook register (active voice, quantitative claims, no blog-post informality).
• Inline Python (LEGO cells): Quantitative examples use {python} cells with small scenario classes. See LEGO cell contract for placement, naming, and fmt conventions. Fmt/notation audits use book/tools/audit/fmt/README.md.

6. Commit Your Changes

Stage files explicitly (do not use git add .):

git add book/quarto/contents/vol1/introduction/introduction.qmd
git add book/quarto/contents/vol1/introduction/images/svg/new-figure.svg
git commit -m "Fix caption formatting in introduction chapter (issue #14)"

7. Render the Book

Please render the book to verify your contribution does not raise errors or warnings:

# Render a specific volume (recommended for faster builds)
quarto render --profile vol1-html
quarto render --profile vol2-html

8. Push and Open a Pull Request

git push origin your-branch-name

Submit PRs to the dev branch, not main.

Open a Pull Request with a brief description and the issue number (e.g., "Fix typo in introduction (issue #14)").

Opening an early PR is encouraged. This will allow us to provide feedback on your contribution and help you improve it. GitHub Actions will run on your PR and generate the book, so you can verify that your contribution renders correctly.

• If your PR is a work in progress, please add [WIP] to the title.

Bug Reports

When reporting errors or issues, please include:

1. Which volume and chapter is affected (e.g., "Vol1, Chapter: Training")
2. Section or page where the issue appears
3. Description of the error (typo, incorrect figure, broken cross-reference, etc.)
4. Suggested fix if you have one

Contributor Recognition

We use All Contributors to recognize everyone who helps improve the book.

How to Recognize a Contributor

After merging a PR or resolving an issue, comment:

@all-contributors please add @username for TYPE

Contribution Types

Type	Emoji	Use For
doc	📖	Wrote or improved content
review	👀	Reviewed chapters or PRs
translation	🌍	Translated content
design	🎨	Created diagrams or figures
bug	🐛	Found errors or typos
ideas	💡	Suggested improvements

Example

@all-contributors please add @contributor for doc, review