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.

---

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.