# 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

```bash
# 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
bash build_mdbook_v2.sh
```

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

### Live Preview

```bash
# 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](style_en.md)**.

### Drawing Figures with AI Agents (Excalidraw Skill)

The repository includes a project-level agent skill,
[`.claude/skills/excalidraw-diagram/`](../.claude/skills/excalidraw-diagram/SKILL.md).
`.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:

```bash
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:
   ```bash
   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:
   ```bash
   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](.github/PULL_REQUEST_TEMPLATE/zh.md)
   - [English PR template](.github/PULL_REQUEST_TEMPLATE/en.md)

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.