openmlsys-zh/CONTRIBUTING/CONTRIBUTING_en.md

Contributing Guide

Note: The v1 version of this project has been archived (located in the v1/ directory) and no longer accepts new contributions. Please submit all content contributions to v2 (the v2/ directory).

---

Repository Structure

openmlsys/
├── v2/                        # Version 2 (active version, accepting contributions)
│   ├── zh_chapters/           # Chinese chapter source files
│   │   ├── 00_chapter_preface/    # Per-chapter directory (numeric prefix + name)
│   │   ├── 01_chapter_introduction/
│   │   ├── ...
│   │   ├── index.md           # Book homepage
│   │   └── SUMMARY.md         # Auto-generated by script — do not edit manually
│   ├── en_chapters/           # English chapter source files (same structure as zh_chapters)
│   ├── config/
│   │   ├── en_config/         # English mdBook configuration
│   │   └── zh_config/         # Chinese mdBook configuration
├── v1/                        # Version 1 (archived)
├── CONTRIBUTING/              # Contributing guides and documentation
├── img/                       # Shared image assets for the entire book
├── references/                # Reference directory
├── tools/                     # Build and preprocessing scripts
│   ├── prepare_mdbook.py      # Core preprocessor: parses custom syntax, generates SUMMARY
│   └── mdbook_preprocessor.py # mdBook preprocessor entry point
└── build_mdbook_v2.sh         # One-click build script for v2

Important: SUMMARY.md is auto-generated by tools/prepare_mdbook_zh.py based on the toc block in index.md. Do not edit it manually.

---

Environment Setup

# 1. Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Install mdBook
cargo install mdbook

# 3. Clone the repository (Python 3 must also be installed)
git clone https://github.com/openmlsys/openmlsys.git
cd openmlsys

---

Local Build

Build both Chinese and English versions of v2

bash build_mdbook_v2.sh

Build output is placed in .mdbook-v2-zh/book (Chinese) and .mdbook-v2/book (English).

Live Preview

# Live preview — Chinese version
cd v2/config/zh_config && mdbook serve --open
# Live preview — English version
cd v2/config/en_config && mdbook serve --open

After modifying source files under zh_chapters/ or en_chapters/, the browser will refresh automatically.

Note

: The preprocessing script regenerates SUMMARY.md on every build. If you encounter a build error, first check that the toc block format in index.md is correct.

---

Writing Guidelines

For detailed custom syntax (math, figure labels, citations, code blocks) and figure guidelines, refer to the Writing Style Guide.

Drawing Figures with AI Agents (Excalidraw Skill)

The repository includes a project-level agent skill, .claude/skills/excalidraw-diagram/. .agents/skills/excalidraw-diagram is a symlink to the same directory. Claude Code, and other agents that support the Agent Skills format, load it automatically when you ask them to draw a figure for the book.

The skill tells the agent to:

• keep the editable .excalidraw source next to the exported SVG/PNG in v1/img/ch<NN>/
• make separate -zh variants for figures that contain text
• follow a palette that stays legible in dark mode
• never reference PDF images

Lint figures and chapter references before you commit:

python3 .claude/skills/excalidraw-diagram/scripts/check_figures.py v1/img/ch06 v2/en_chapters/06_chapter_training_systems/index.md

---

Submission Workflow

1. Fork this repository and create a feature branch:

   git checkout -b feat/chapter-xxx-section-yyy
   

2. Validate locally: After making changes, run bash build_mdbook_v2.sh and confirm there are no errors.

3. Commit your changes: Follow semantic commit message conventions:

   git commit -m "feat(zh): 新增第X章第Y节内容"
   git commit -m "feat(en): Add content for chapter X section Y"
   git commit -m "ci: update main.yml"
   

   Common prefixes: feat (new content), fix (corrections), refactor (restructuring), style (formatting), ci (build pipeline updates)

4. Open a Pull Request targeting the main branch. Please use the provided PR templates:

   • Chinese PR template
   • English PR template

5. Code review: At least one contributor other than the author is required to review the PR. GitHub Actions will automatically verify that the new content builds successfully.

---

FAQ

Q: How do I add a new chapter?

• Create a chapter_<name>/ directory under v2/zh_chapters/
• Create index.md and list the sections inside a toc block
• Register the new chapter in the toc block of v2/zh_chapters/index.md
• Ensure the local build passes before submitting a PR

Q: How do I add a reference?

Add a BibTeX entry to mlsys.bib, then cite it in the body text using :cite:key``.

Q: The build says it cannot find an image — what should I do?

Check that the image path starts with ../img/ (relative to the chapter directory) and that the image file has been committed to the img/ directory.