From fe2f3405f518e5ad34fc6f6e409fdfafbb10e8d9 Mon Sep 17 00:00:00 2001 From: 魏曹先生 <1992414357@qq.com> Date: Fri, 10 Jul 2026 19:06:23 +0800 Subject: feat: add CI check workflow and update contributing guide --- CONTRIBUTING.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 108 insertions(+), 21 deletions(-) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ffb0064..f63832a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,26 +4,113 @@ First of all, thank you for your interest in Mingling! 🎉 Whether it's fixing Before contributing, we recommend reading [README](README.md) to get an overview of the project. -## 1. Project Structure - -| Category | Path/Name | Description | -| ---------------------------- | ------------------------- | ------------------------------------------------------------------------- | -| **Entry crate** | `mingling/` | Project entry point | -| **Core library** | `mingling_core/` | Imported as an external dependency | -| **Macro library** | `mingling_macros/` | Imported as an external dependency | -| **Examples** | `examples/` | To add expected output tests, modify `examples/test-examples.toml` | -| **Documentation, resources** | `docs/` | All documentation and resource files | -| **Development tools** | `.run/src/bin` | Contains scripts and Rust tools | -| Scripts | `.run/src/bin` | Helper `.sh`/`.ps1`/`.py` scripts, executed via `./run.sh` or `.\run.ps1` | -| Rust tools | `dev_tools/src/bin/` | Same as above | -| CI check entry | `dev_tools/src/bin/ci.rs` | Can be invoked directly via `cargo ci` | -| **Scaffolding tool** | `mling/` | Scaffolding tool `mingling-cli` | -| **Temporary files** | `.temp/` | Ignored by `.gitignore` | - -## 2. Submission Guide +## 1. Project Structure 📦 + +| Category | Path/Name | Description | +| ----------------------- | -------------------- | ------------------------------------------------------------------ | +| **Entry crate** | `mingling/` | Project entry point | +| **Core library** | `mingling_core/` | Imported as an external dependency | +| **Macro library** | `mingling_macros/` | Imported as an external dependency | +| **Mingling Pathfinder** | `mingling_pathf/` | Build-time module path resolution for types | +| **Scaffolding tool** | `mling/` | Scaffolding tool `mingling-cli` | +| **Examples** | `examples/` | To add expected output tests, modify `examples/test-examples.toml` | +| **Documents** | `docs/` | All documents | +| **Dev Documents** | `docs/dev/` | Internal documents | +| **Resources** | `docs/res/` | All resources | +| **Development tools** | `.run/src/bin` | Contains scripts and Rust tools | +| **CI** | `.run/src/bin/ci.rs` | Can be invoked directly via `cargo ci` | +| **Temporary files** | `.temp/` | Ignored by `.gitignore` | + +## 2. How to Contribute + +### Code Contribution + +If you'd like to contribute to `mingling`, `mingling_core`, `mingling_macros`, or `mingling_pathf`, first share your idea on the [Github Issue](https://github.com/mingling-rs/mingling/issues) page to confirm before starting work. + +- **Before making changes**, make sure your branch stays **as close as possible** to the upstream `main` branch. +- **After finishing**, run `cargo ci` locally (see [ABOUT CI](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/ci) for how it works). If `cargo ci` passes locally, your changes are most likely correct. + +### Example Code Contribution + +To add or modify examples under `examples/`, follow these rules: + +- Place each example in `examples/<example-dir>/` +- Each dir must contain a `page.toml` file describing the example's metadata +- `page.toml` format: + +```toml +[example] +id = "example-id" # Unique identifier +name = "Example Name" # Display name (optional, defaults to dir name) +icon = "📦" # Icon (optional, defaults to "📦") +category = "" # Category (optional) +desc = "Description" # Description (optional) +tags = ["tag1", "tag2"] # Tags (optional) +files = ["Cargo.toml", "src/main.rs"] +``` -1. **Pull Request** +If you change expected behavior, update the test assertions in `examples/test-examples.toml`. + +After editing examples, run these scripts to keep things in sync: + +```bash +# Ensure code compiles +./run.sh build-all + +# Ensure code style +./run.sh clippy + +# Sync page.toml info to docs/example-pages/examples.json +./run.sh sync-examples + +# Check all examples behave as expected +./run.sh test-examples +# Sync examples content into mingling/src/example_docs.rs +./run.sh refresh-docs + +# (Optional) Preview the Example Viewer in a browser +# Requires: Python +./run.sh http-page-preview +# http://127.0.0.1:3000/ +``` + +### Documentation Contribution + +To contribute docs, edit files under `docs/`. For other language translations, refer to the structure under `docs/zh_CN`. + +- **When editing docs**, prioritize **Chinese docs** first, then **English docs** — since I ([@Weicao-CatilGrass](https://github.com/Weicao-CatilGrass)) am a native Chinese speaker, this is more efficient. +- If your changes involve code, check the [Code Verify System](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/code-verify-system), which explains how CI checks code. +- **Before submitting**, always run: + +```bash +# Fix code block issues in docsify +./run.sh docs-code-box-fix + +# Generate sidebar +./run.sh docsify-sidebar-gen + +# Verify all Markdown code blocks compile +./run.sh test-all-markdown-code +``` + +### Web Frontend Contribution + +No strict requirements here — just modify the relevant `*.html` files. Preview with: + +```bash +# Requires: Python +./run.sh http-page-preview +# http://127.0.0.1:3000/ +``` + +### Dev Tool Contribution + +`Mingling CI` code is under strict review. If you want to improve `mingling`'s CI pipeline or other dev tools (under `.run/`), **please** first file an [Issue](https://github.com/mingling-rs/mingling/issues) and contact [Weicao-CatilGrass](https://github.com/Weicao-CatilGrass)! + +## 3. Submission Guide 🖊 + +1. **Pull Request** - Submit a GitHub Pull Request and @Reviewer **[Weicao-CatilGrass](https://github.com/Weicao-CatilGrass)** for review - Or send patches to **catil_grass@qq.com** @@ -47,7 +134,7 @@ Before contributing, we recommend reading [README](README.md) to get an overview 6. **Binary Resources** - For binary resource files (images, etc.), please be cautious about adding them to avoid repository bloat -## 3. Documentation Contribution +## 4. Documentation Contribution 📕 ### Documentation Location @@ -72,13 +159,13 @@ These steps are included in `cargo ci`; running `cargo ci` will execute them aut > [!TIP] > You can check the [ABOUT CI](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/ci) section to learn how "Mingling CI" works. -## 4. Regarding AI Agent Usage +## 5. Regarding AI Agent Usage 🤖 - You are free to use AI agents to assist development — no restrictions - **Humans are the final decision-makers**, everything is subject to human judgment - Please **DO NOT** leave AI instruction files like `CLAUDE.md` in the repository root. Mingling currently has no plans to introduce **Harness Engineering** -## 5. License +## 6. License 📖 Mingling uses the **MIT + Apache 2.0** dual license. For details, please see: -- cgit