openmlsys-zh/CONTRIBUTING/CONTRIBUTING.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.

---

---

贡献指南

注意： 本项目的 v1 版本已归档（位于 v1/ 目录），不再接受新的贡献。请将所有内容贡献提交至 v2（v2/ 目录）。

---

仓库结构说明

openmlsys/
├── v2/                        # 第二版（当前活跃版本，接受贡献）
│   ├── zh_chapters/           # 中文章节源文件
│   │   ├── 00_chapter_preface/    # 各章目录（数字前缀 + 名称）
│   │   ├── 01_chapter_introduction/
│   │   ├── ...
│   │   ├── index.md           # 全书首页
│   │   └── SUMMARY.md         # 由脚本自动生成，勿手动编辑
│   ├── en_chapters/           # 英文章节源文件（结构与中文章节一致）
│   ├── config/
│   │   ├── en_config/         # 英文版 mdBook 配置
│   │   └── zh_config/         # 中文版 mdBook 配置
├── v1/                        # 第一版（已归档）
├── CONTRIBUTING/              # 贡献指南与相关文档
├── img/                       # 全书共享图片资源
├── references/                # 参考文献目录
├── tools/                     # 构建与预处理脚本
│   ├── prepare_mdbook.py      # 核心预处理：解析自定义语法、生成 SUMMARY
│   └── mdbook_preprocessor.py # mdBook 预处理器入口
└── build_mdbook_v2.sh         # v2 一键构建脚本

重要：SUMMARY.md 由 tools/prepare_mdbook_zh.py 根据 index.md 中的 toc 块自动生成，请勿手动修改。

---

环境准备

# 1. 安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. 安装 mdBook
cargo install mdbook

# 3. 克隆仓库（需预先安装 Python 3）
git clone https://github.com/openmlsys/openmlsys.git
cd openmlsys

---

本地构建

构建 v2 中英文双版本

bash build_mdbook_v2.sh

构建产物输出至 .mdbook-v2-zh/book（中文）和 .mdbook-v2/book（英文）。

实时预览

# 中文版实时预览
cd v2/config/zh_config && mdbook serve --open
# 英文版实时预览
cd v2/config/en_config && mdbook serve --open

修改 zh_chapters/ 或 en_chapters/ 下的源文件后，浏览器将自动刷新。

注意：预处理脚本会在每次构建时重新生成 SUMMARY.md，如遇构建报错请先检查 index.md 中 toc 块的格式是否正确。

---

写作规范

详细的自定义语法（公式、图片标签、文献引用、代码块等）及图片规范，请参阅 写作样式规范。

---

提交流程

1. Fork 本仓库并创建功能分支：

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

2. 本地构建验证：修改完成后运行 bash build_mdbook_v2.sh，确保无报错

3. 提交代码：遵循语义化提交信息

   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"
   

   常用前缀：feat（新内容）、fix（修正错误）、refactor（重组结构）、style（格式调整）、ci（构建流程更新）

4. 发起 Pull Request：目标分支为 main，请使用 PR 模板：

   • 中文 PR 模板
   • 英文 PR 模板

5. 代码审查：PR要求至少有一位非本人Contributor进行检查，且github action将会自动验证新增内容是否可以编译通过

---

常见问题

Q：如何添加新章节？

• 在 v2/zh_chapters/ 下新建 chapter_<名称>/ 目录
• 创建 index.md，在其中使用 toc 块列出各节
• 在全书 v2/zh_chapters/index.md 的 toc 块中注册新章节
• 确保本地构建通过后再提交 PR

Q：参考文献如何添加？

在 mlsys.bib 中添加 BibTeX 格式的文献条目，然后在正文中使用 :cite:key`` 引用。

Q：构建时提示找不到图片怎么处理？

检查图片路径是否以 ../img/ 开头（相对于章节目录），以及图片文件是否已提交至 img/ 目录。