WAIT — Stale — last commit 2y ago

• 17 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

d2l-zh is the Chinese-language version of 'Dive into Deep Learning,' an interactive, runnable deep learning textbook that teaches concepts, mathematics, and code implementation together. It's published as Jupyter notebooks with embedded executable Python code across multiple frameworks (PyTorch, TensorFlow, MXNet, Paddle), deployed as HTML via static site generation to zh.d2l.ai, and used by 500+ universities across 70+ countries. Monorepo organized by chapter: chapter_* directories (chapter_attention-mechanisms, chapter_appendix-tools-for-deep-learning, chapter_computational-performance, etc.) each contain paired markdown files (*.md for Chinese content and *_origin.md likely for English source). Static site generator workflow (build_html.sh) converts markdown+embedded code to HTML. GitHub Actions orchestrates builds: setup_env_vars/action.yml configures environments, submit-job/action.yml triggers cloud jobs (likely SageMaker per sagemaker.md content).

Undergraduate and graduate students learning deep learning in Chinese; instructors building curricula (the book explicitly supports UC Berkeley's STAT-157 course and similar programs); practitioners transitioning from theory to implementation who want working code examples alongside mathematical explanations.

Highly mature and actively maintained. The project is used by 500+ universities worldwide, has published hardcover editions, maintains synchronized translations with the English d2l-en repository, and runs comprehensive CI/CD workflows (build-docker.yml, ci.yml) across multiple deep learning frameworks. Active community with 70+ contributor graphs visible and ongoing issue discussions on discuss.d2l.ai.

Low technical risk for core content, but infrastructure complexity is significant: the codebase must build and test against PyTorch, TensorFlow, MXNet, and Paddle simultaneously (visible in .github/workflow_scripts/ with framework-specific build shells). Single-point-of-failure risk in the build pipeline if workflow orchestration in build_and_deploy.sh breaks. Dependency fragility: supporting four ML frameworks means breaking changes in any upstream library could invalidate chapters. No visible package.json/requirements.txt in top-level file list, suggesting build config may be in submodules or hidden.

Active synchronization with English version (d2l-en referenced in README); maintaining framework parity across PyTorch, TensorFlow, MXNet, Paddle build pipelines; likely preparing updates as deep learning frameworks evolve. CI workflow (ci.yml) suggests continuous testing. Docker builds (build-docker.yml) indicate containerized deployment infrastructure.

git clone --recursive https://github.com/d2l-ai/d2l-zh.git
cd d2l-zh
# Framework-specific setup (see .github/workflow_scripts/):
bash .github/workflow_scripts/build_pytorch.sh  # or build_tf.sh, build_mxnet.sh, build_paddle.sh
# Or use Docker:
bash .github/workflows/build-docker.yml

Note: .gitmodules present indicates submodule dependencies; recursive clone is essential.

Daily commands: Build chapters locally: bash .github/workflow_scripts/build_pytorch.sh (or framework of choice). Generate HTML: bash .github/workflow_scripts/build_html.sh. Run Jupyter notebooks directly from chapter directories (implied by 'runnable code' in README). CI automatically builds on PR via .github/workflows/ci.yml.

• README.md — Entry point documenting the project's mission, pedagogical approach, and installation instructions for all framework implementations (PyTorch, TensorFlow, MXNet, PaddlePaddle).
• .github/workflows/ci.yml — CI/CD pipeline that validates and builds content across multiple deep learning frameworks; core to ensuring code examples remain executable.
• STYLE_GUIDE.md — Defines content formatting, code block conventions, and markdown structure that every contributor must follow to maintain consistency across 600+ files.
• TERMINOLOGY.md — Centralized glossary mapping Chinese/English technical terms used across all chapters; essential for maintaining translation consistency.
• .github/workflow_scripts/utils.sh — Shared build utilities supporting multi-framework compilation; used by all framework-specific build pipelines (PyTorch, TensorFlow, MXNet, PaddlePaddle).
• chapter_appendix-tools-for-deep-learning/index.md — Starting point for appendix content; demonstrates the dual-file pattern (_origin) used throughout for managing translations and source content.
• .gitmodules — Declares git submodules for the d2l package and documentation dependencies; critical for reproducible environment setup.

Add a new chapter on a deep learning topic

1. Create chapter directory: chapter_<topic_name>/ (chapter_<topic_name>/index.md)
2. Create index.md with Chinese content following STYLE_GUIDE.md; include code blocks with #@save markers for framework-agnostic snippets (chapter_<topic_name>/index.md)
3. Create index_origin.md as English source; content tools auto-translate or you manually maintain both (chapter_<topic_name>/index_origin.md)
4. For each major section, create <section>.md and <section>_origin.md following the dual-file pattern (chapter_<topic_name>/<section>.md)
5. Verify terminology consistency by cross-referencing TERMINOLOGY.md for all technical terms (TERMINOLOGY.md)
6. Test code execution: CI will auto-extract code blocks and run via build_pytorch.sh, build_tf.sh, etc. (.github/workflows/ci.yml)

Add a new runnable code example or Jupyter notebook

1. Embed code in markdown with framework-specific markers; PyTorch blocks marked as Python code, TensorFlow alternatives in separate subsections (chapter_*/section.md)
2. Use #@save to mark functions/classes for automatic extraction into reusable d2l library (chapter_*/section.md)
3. Include #@tab(pytorch|tensorflow|mxnet|paddle) directives for framework switching in HTML output (chapter_*/section.md)
4. Build script (build_pytorch.sh) extracts code into .ipynb files and executes them; ensure all imports and data loading work offline (.github/workflow_scripts/build_pytorch.sh)
5. Test locally: run jupyter notebook and verify outputs match expected results before pushing (chapter_*/section.md)

Support a new deep learning framework (e.g., PyTorch → add JAX)

1. Create .github/workflow_scripts/build_jax.sh mimicking build_pytorch.sh: define JAX-specific imports, device handling, and data loading (.github/workflow_scripts/build_jax.sh)
2. Update .github/workflows/ci.yml to call build_jax.sh as a new job step (.github/workflows/ci.yml)
3. Update .github/workflows/build-docker.yml to add JAX Docker image building (.github/workflows/build-docker.yml)
4. Add JAX-specific code blocks to chapters using #@tab(jax) markers; maintain parity with existing framework examples (chapter_*/section.md)
5. Update TERMINOLOGY.md if JAX introduces new concepts or API naming diverging from PyTorch/TensorFlow (TERMINOLOGY.md)
6. Document setup in chapter_appendix-tools-for-deep-learning/index.md with JAX installation and GPU setup instructions (chapter_appendix-tools-for-deep-learning/index.md)

Fix a broken code example or update for framework API changes

1. Locate the chapter and section: e.g., chapter_computer-vision/fcn.md for semantic segmentation code (chapter_computer-vision/fcn.md)
2. Update the code block with the new API; ensure #@save functions remain stable to avoid breaking downstream uses (chapter_computer-vision/fcn.md)
3. Mirror changes to _origin.md if English version exists (chapter_computer-vision/fcn_origin.md)
4. Run build script locally: bash .github/workflow_scripts/build_pytorch.sh to verify code executes without errors (.github/workflow_scripts/build_pytorch.sh)
5. Commit and push; CI will re-run all framework builds and flag regressions (.github/workflows/ci.yml)

• Markdown + Jupyter notebooks — Educational content must be readable as text and executable; dual format allows web rendering and local experimentation.
• GitHub Actions CI/CD — Multi-framework validation at scale; every commit verified across PyTorch, TensorFlow, MXNet, PaddlePaddle without manual testing overhead.
• Shell scripts (utils.sh, build_*.sh) — Framework-agnostic, portable CI orchestration; easily extended for new frameworks without rewriting core pipeline logic.
• Dual-file translation pattern (_origin.md) — Manages Chinese and English versions in sync; avoids translation divergence as content evolves across 500+ university adoptions.
• Docker multi-framework images — Reproducible environments for students and practitioners; eliminates 'works on my machine' by containerizing PyTorch, TensorFlow, etc. with identical dependencies.
• Submodule for d2l library — Separates reusable Python library (#@save functions) from book content; library versions pinned and released independently.

• Multi-framework code (PyTorch + TensorFlow + MXNet + PaddlePaddle) in single chapters

  • Why: Maximizes reachability—students use preferred framework—but increases maintenance burden and chapter length.
  • Consequence: Contributors must test across all frameworks; larger markdown files with #@tab directives; HTML rendering hides non-selected implementations.

• undefined

  • Why: undefined
  • Consequence: undefined

Submodule initialization: .gitmodules present but contents unknown from file list—cloning without --recursive will fail silently on builds. Framework environment isolation: Four parallel build scripts (build_pytorch.sh, build_tf.sh, build_mxnet.sh, build_paddle.sh) suggest they use different conda/venv environments; switching between them without cleanup may cause conflicts. Cloud job submission: submit-job/action.yml suggests AWS/SageMaker integration—GitHub Actions must have AWS credentials configured (IAM role or secrets); local builds may not work without setup. Markdown→HTML pipeline: Static site generation flow is inferred but exact tool (Sphinx, Jupyter Book, custom) is not in file list; may require obscure build dependencies. Origin file sync: Parallel *_origin.md files suggest a split-source system; editing only .md without syncing origin may cause divergence in future translations.

• Attention Mechanisms — Multiple dedicated chapters (chapter_attention-mechanisms/) on attention, self-attention, multihead-attention, and Transformer architecture are foundational to modern NLP and vision models; understanding the progression from Nadaraya-Watson to Transformers is core to the curriculum
• Multi-Framework Implementation — d2l-zh explicitly teaches the same concepts in PyTorch, TensorFlow, MXNet, and Paddle (build scripts for each); understanding how to translate between frameworks' APIs is a practical skill for production ML engineers
• Literate Programming — The book's architecture (markdown + embedded code + static site generation) follows Donald Knuth's literate programming philosophy; chapters interleave explanations with runnable code as primary design pattern
• Computational Performance Optimization — Dedicated chapter (chapter_computational-performance/) on asynchronous computation, mixed precision, distributed training; critical for practitioners scaling from toy examples to production
• Localization and Terminology Mapping — TERMINOLOGY.md maintains bidirectional Chinese-English technical glossary (e.g., '卷积' ↔ 'convolution'); this abstraction layer is invisible but crucial for maintaining coherence across 500+ pages and 70+ countries
• Static Site Generation for Interactive Content — The codebase converts Jupyter-like markdown to static HTML that is both SEO-friendly and interactive (zh.d2l.ai serves 500+ universities); understanding the build pipeline (build_html.sh) is essential for contributors
• Asynchronous Computation in Deep Learning — chapter_computational-performance/async-computation.md teaches non-blocking GPU/CPU operations; practical knowledge for optimizing training speed and resource utilization

• d2l-ai/d2l-en — The canonical English-language source repository; d2l-zh is a synchronized translation that must track updates and architectural decisions from d2l-en
• fastai/fastai — Alternative top-down, code-first deep learning course that shares d2l's philosophy of teaching through executable notebooks; direct competitor for student mindshare
• pytorch/tutorials — Official PyTorch tutorials that cover many of the same topics; d2l-zh chapters often complement or extend official docs for the PyTorch framework
• tensorflow/docs — Official TensorFlow documentation and guides; d2l-zh provides structured curriculum where TensorFlow docs provide reference; some chapters reuse or link to TF tutorials
• d2l-ai/berkeley-stat-157 — The UC Berkeley STAT-157 course materials (lectures, slides-zh) that use d2l-zh as primary textbook; shows real-world classroom adoption and feedback loop

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create unified test framework for code snippets across all chapter files

The repo contains hundreds of markdown files with embedded code examples (in chapter_*/ directories) but there's no systematic validation that these code snippets actually run. This is critical for an educational resource used by 500+ universities. A test framework would catch breaking changes when dependencies update and ensure code examples match the text explanations.

• [ ] Create .github/workflows/test-code-snippets.yml to extract and validate Python/PyTorch/TensorFlow code blocks from all chapter_*/**.md files
• [ ] Add a script in .github/workflow_scripts/validate_notebooks.sh that runs jupyter nbconvert on generated notebooks from markdown code blocks
• [ ] Document the code snippet testing process in STYLE_GUIDE.md with requirements for code block format (language tags, executable flags, dependencies)

Add multi-framework compatibility test matrix for chapter_computational-performance/ sections

The repo maintains separate build scripts for MXNet, PyTorch, TensorFlow, and Paddle (.github/workflow_scripts/build_*.sh exist) but there's no automated testing that examples in chapter_computational-performance/ (which covers framework-specific optimizations like multiple-gpus, hybridize, etc.) work across all supported frameworks. This is essential since different frameworks have different parallelization APIs.

• [ ] Extend .github/workflows/ci.yml to add a matrix strategy testing chapter_computational-performance/*.md code examples against PyTorch, TensorFlow, and Paddle versions
• [ ] Create .github/workflow_scripts/test_distributed_examples.sh that validates multi-GPU examples work on different frameworks
• [ ] Update TERMINOLOGY.md or create FRAMEWORK_COMPAT.md documenting which sections apply to which frameworks

Automate synchronization between _origin.md and translated .md files in chapters

Every chapter has paired files (e.g., attention-cues.md and attention-cues_origin.md) suggesting a translation workflow, but there's no automated validation that translations stay in sync with originals when originals are updated. This causes stale translations that confuse learners. A diff-based CI check would surface when originals change without corresponding translation updates.

• [ ] Create .github/workflow_scripts/check_translation_sync.sh that compares _origin.md vs .md file pairs to detect sections that changed in origin but weren't updated in translation
• [ ] Add .github/workflows/translation-sync-check.yml as a CI check that fails if untranslated sections exceed a threshold, with output listing specific files needing updates
• [ ] Document the translation maintenance workflow in CONTRIBUTING.md (mentioned in the file structure) with step-by-step instructions for keeping paired files synchronized

• Add test validation for code examples in chapter_attention-mechanisms: Write a Python script that extracts and runs all code blocks from chapter_attention-mechanisms/*.md files to catch broken examples before deployment (similar to nbval or ci-skip patterns).: The large number of chapters and framework variants means examples can silently break; no visible test infrastructure for content validation in the file list.
• Document the build environment setup in a new BUILD.md file: Explain how to configure conda environments for each of the four frameworks (PyTorch, TensorFlow, MXNet, Paddle), list exact version constraints, and provide troubleshooting for common setup failures.: contributing.md exists but build setup is encoded in shell scripts (.github/workflow_scripts/*.sh) and is not easily discoverable or reproducible locally.
• Create a linter/checker for TERMINOLOGY.md compliance: Build a pre-commit hook or GitHub Actions check that scans all chapter_/.md files for inconsistent Chinese-English term usage (e.g., detects if '卷积' and 'convolution' are used without matching pairs).: The project explicitly maintains TERMINOLOGY.md but there's no visible automation to enforce it; manual review of 500+ pages is error-prone.

This is an educational deep learning repository with moderate security posture. The primary concerns are around CI/CD pipeline security (shell scripts, GitHub Actions configuration) and missing dependency audit trails. No obvious secrets or hardcoded credentials were found in the provided file structure. The codebase appears to be a documentation/educational project rather than a production service, which lowers the overall risk profile. Recommendations focus on workflow hardening, dependency management, and input validation in shell scripts.

• Medium · Potential Shell Injection in Workflow Scripts — .github/workflow_scripts/*.sh (build_and_deploy.sh, build_html.sh, setup_git.sh, utils.sh, etc.). The repository contains multiple shell scripts in .github/workflow_scripts/ that are executed as part of CI/CD pipelines. Without reviewing the actual content, there's a risk of shell injection if these scripts process untrusted input (e.g., branch names, commit messages) without proper sanitization. Fix: Review all shell scripts for proper input validation and quote all variables. Use shellcheck for static analysis of shell scripts. Avoid eval() and use safer alternatives.
• Medium · GitHub Actions Security Configuration — .github/workflows/*.yml. The repository uses GitHub Actions workflows (ci.yml, build-docker.yml, clear-cache.yml) which may have overly permissive permissions or insufficient secret management practices. Default GITHUB_TOKEN permissions could be excessive. Fix: Review workflow files to ensure: (1) GITHUB_TOKEN permissions are minimized with 'permissions' scope, (2) secrets are not logged or exposed in job output, (3) third-party actions are pinned to specific commit hashes rather than tags/branches.
• Low · Missing Dependency Manifest — Repository root. No package.json, requirements.txt, or other dependency management files were provided in the analysis. This makes it impossible to audit for known vulnerable dependencies. Fix: Maintain and regularly audit all dependency files. Use tools like: npm audit, pip-audit, or Dependabot to automatically detect and alert on vulnerable dependencies.
• Low · Git Configuration Exposure Risk — .gitmodules. The presence of .gitmodules file indicates use of git submodules. If these submodules point to external repositories, there's a supply chain risk if those repositories are compromised. Fix: Verify all submodule sources are trusted and under your control or from reputable organizations. Use git verify-commit to validate signed commits from submodule sources.
• Low · Docker Build Security — .github/workflows/build-docker.yml. A Docker build workflow exists (build-docker.yml) but without visibility into the Dockerfile, potential security issues cannot be fully assessed (e.g., using 'latest' tags, running as root, missing security scanning). Fix: Ensure Dockerfile: (1) uses specific base image versions, (2) runs services as non-root user, (3) includes multi-stage builds to minimize image size, (4) integrates image scanning (Trivy, Snyk) in CI/CD pipeline.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/d2l-ai/d2l-zh shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live d2l-ai/d2l-zh repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/d2l-ai/d2l-zh.

What it runs against: a local clone of d2l-ai/d2l-zh — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in d2l-ai/d2l-zh | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 678 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of d2l-ai/d2l-zh. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/d2l-ai/d2l-zh.git
#   cd d2l-zh
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of d2l-ai/d2l-zh and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "d2l-ai/d2l-zh(\\.git)?\\b" \\
  && ok "origin remote is d2l-ai/d2l-zh" \\
  || miss "origin remote is not d2l-ai/d2l-zh (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f "STYLE_GUIDE.md" \\
  && ok "STYLE_GUIDE.md" \\
  || miss "missing critical file: STYLE_GUIDE.md"
test -f "TERMINOLOGY.md" \\
  && ok "TERMINOLOGY.md" \\
  || miss "missing critical file: TERMINOLOGY.md"
test -f ".github/workflow_scripts/utils.sh" \\
  && ok ".github/workflow_scripts/utils.sh" \\
  || miss "missing critical file: .github/workflow_scripts/utils.sh"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 678 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~648d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/d2l-ai/d2l-zh"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.