mirror of
https://github.com/openmlsys/openmlsys-zh.git
synced 2026-03-31 09:20:50 +08:00
9c289782cc
Split each bilingual CONTRIBUTING file into _en.md and _zh.md variants: - CONTRIBUTING.md → CONTRIBUTING_en.md + CONTRIBUTING_zh.md - style.md → style_en.md + style_zh.md - info.md → info_en.md + info_zh.md - issue.md → issue_en.md + issue_zh.md - reference_guide.md → reference_guide_en.md + reference_guide_zh.md terminology.md kept as-is (bilingual lookup table by nature). Update README.md to link to _zh.md files, README_EN.md to _en.md files. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# 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)**.
|
|
|
|
---
|
|
|
|
## 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.
|