diff options
| -rw-r--r-- | .github/workflows/ci-check-only.yml | 47 | ||||
| -rw-r--r-- | .gitignore | 3 | ||||
| -rw-r--r-- | .run/src/bin/ci.rs | 14 | ||||
| -rw-r--r-- | .run/src/bin/update-version.rs | 18 | ||||
| -rw-r--r-- | .run/src/lib.rs | 4 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 131 | ||||
| -rw-r--r-- | docs/_zh_CN/index.html | 2 | ||||
| -rw-r--r-- | docs/dev/_sidebar.md | 2 | ||||
| -rw-r--r-- | docs/dev/index.html | 2 | ||||
| -rw-r--r-- | docs/dev/pages/abouts/ci.md (renamed from ABOUT-CI.md) | 9 | ||||
| -rw-r--r-- | docs/dev/pages/abouts/nightly-features.md (renamed from ABOUT-NIGHTLY.md) | 7 | ||||
| -rw-r--r-- | docs/doc.html | 2 |
12 files changed, 196 insertions, 45 deletions
diff --git a/.github/workflows/ci-check-only.yml b/.github/workflows/ci-check-only.yml new file mode 100644 index 0000000..1179ed0 --- /dev/null +++ b/.github/workflows/ci-check-only.yml @@ -0,0 +1,47 @@ +name: CI (Check only) + +on: + push: + branches-ignore: [main] + pull_request: + +jobs: + Check-Codes: + strategy: + matrix: + os: [ubuntu-latest, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - uses: actions-rust-lang/setup-rust-toolchain@v1 + + - name: Restore .temp cache + id: cache-temp + uses: actions/cache@v4 + with: + path: .temp + key: ${{ runner.os }}-mingling-temp-${{ hashFiles('Cargo.lock', 'dev_tools/Cargo.toml', 'verified-docs.toml', 'examples/test-examples.toml') }}-${{ hashFiles('dev_tools/src/**/*.rs') }} + restore-keys: | + ${{ runner.os }}-mingling-temp- + + - run: cargo ci --test-codes + + Check-Docs: + strategy: + matrix: + os: [ubuntu-latest, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - uses: actions-rust-lang/setup-rust-toolchain@v1 + + - name: Restore .temp cache + id: cache-temp + uses: actions/cache@v4 + with: + path: .temp + key: ${{ runner.os }}-mingling-temp-${{ hashFiles('Cargo.lock', 'dev_tools/Cargo.toml', 'verified-docs.toml', 'examples/test-examples.toml') }}-${{ hashFiles('dev_tools/src/**/*.rs') }} + restore-keys: | + ${{ runner.os }}-mingling-temp- + + - run: cargo ci --test-docs @@ -6,3 +6,6 @@ dev_tools/scripts/last_check # Drafts __*.md __*/ + +# Fuck +nul diff --git a/.run/src/bin/ci.rs b/.run/src/bin/ci.rs index f8aed79..2527ece 100644 --- a/.run/src/bin/ci.rs +++ b/.run/src/bin/ci.rs @@ -139,12 +139,12 @@ fn ci(test_docs: bool, test_codes: bool, run_all: bool) -> Result<(), i32> { } fn test_examples() -> Result<(), i32> { - run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --color always --bin test-examples") + run_cmd!("cargo run --manifest-path .run/Cargo.toml --color always --bin test-examples") } fn test_docs_code_blocks() -> Result<(), i32> { run_cmd!( - "cargo run --manifest-path dev_tools/Cargo.toml --color always --bin test-all-markdown-code" + "cargo run --manifest-path .run/Cargo.toml --color always --bin test-all-markdown-code" ) } @@ -214,11 +214,11 @@ fn test_all() -> Result<(), i32> { fn docs_refresh() -> Result<(), i32> { println_cargo_style!("Refresh: document at `./docs/`"); - run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --bin docs-code-box-fix")?; - run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --bin docsify-sidebar-gen")?; - run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --bin refresh-docs")?; - run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --bin refresh-feature-mod")?; - run_cmd!("cargo run --manifest-path dev_tools/Cargo.toml --bin sync-examples")?; + run_cmd!("cargo run --manifest-path .run/Cargo.toml --bin docs-code-box-fix")?; + run_cmd!("cargo run --manifest-path .run/Cargo.toml --bin docsify-sidebar-gen")?; + run_cmd!("cargo run --manifest-path .run/Cargo.toml --bin refresh-docs")?; + run_cmd!("cargo run --manifest-path .run/Cargo.toml --bin refresh-feature-mod")?; + run_cmd!("cargo run --manifest-path .run/Cargo.toml --bin sync-examples")?; run_cmd!("cargo fmt")?; Ok(()) diff --git a/.run/src/bin/update-version.rs b/.run/src/bin/update-version.rs index 475e54b..9d595bb 100644 --- a/.run/src/bin/update-version.rs +++ b/.run/src/bin/update-version.rs @@ -39,7 +39,9 @@ fn main() { let root_cargo_path = "Cargo.toml"; let root_cargo_content = std::fs::read_to_string(root_cargo_path).expect("Failed to read Cargo.toml"); - let cargo_value: toml::Value = root_cargo_content.parse().expect("Failed to parse Cargo.toml"); + let cargo_value: toml::Value = root_cargo_content + .parse() + .expect("Failed to parse Cargo.toml"); let current_ver = cargo_value["workspace"]["package"]["version"] .as_str() @@ -54,11 +56,11 @@ fn main() { println_cargo_style!("Version: {} -> {}", current_ver, new_ver); // Read version-files.toml - let config_path = Path::new("dev_tools").join("version-files.toml"); + let config_path = Path::new(".run").join("version-files.toml"); let config_str = - std::fs::read_to_string(&config_path).expect("Failed to read dev_tools/version-files.toml"); - let config: Config = toml::from_str(&config_str) - .expect("Failed to parse dev_tools/version-files.toml"); + std::fs::read_to_string(&config_path).expect("Failed to read .run/version-files.toml"); + let config: Config = + toml::from_str(&config_str).expect("Failed to parse .run/version-files.toml"); let mut updated_count = 0; let mut skipped_count = 0; @@ -94,5 +96,9 @@ fn main() { updated_count += 1; } - println_cargo_style!("Done: {} file(s) updated, {} file(s) skipped", updated_count, skipped_count); + println_cargo_style!( + "Done: {} file(s) updated, {} file(s) skipped", + updated_count, + skipped_count + ); } diff --git a/.run/src/lib.rs b/.run/src/lib.rs index d38a156..232afb3 100644 --- a/.run/src/lib.rs +++ b/.run/src/lib.rs @@ -316,8 +316,8 @@ pub fn cargo_tomls() -> Vec<std::path::PathBuf> { for entry in entries.flatten() { let path = entry.path(); if path.is_dir() { - // Skip the dev_tools directory - if path.file_name().and_then(|n| n.to_str()) == Some("dev_tools") { + // Skip the .run directory + if path.file_name().and_then(|n| n.to_str()) == Some(".run") { continue; } dirs.push(path); diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8e4bed..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 @@ -70,15 +157,15 @@ After editing documentation, refresh relevant files: These steps are included in `cargo ci`; running `cargo ci` will execute them automatically. > [!TIP] -> You can check the [ABOUT CI](./ABOUT-CI.md) section to learn how "Mingling CI" works. +> 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: diff --git a/docs/_zh_CN/index.html b/docs/_zh_CN/index.html index 7adaa98..ad21062 100644 --- a/docs/_zh_CN/index.html +++ b/docs/_zh_CN/index.html @@ -56,7 +56,7 @@ auto2top: true, loadSidebar: true, maxLevel: 0, - subMaxLevel: 3, + subMaxLevel: 0, search: { placeholder: "Search", noData: "No matches found.", diff --git a/docs/dev/_sidebar.md b/docs/dev/_sidebar.md index 5182676..e303735 100644 --- a/docs/dev/_sidebar.md +++ b/docs/dev/_sidebar.md @@ -5,6 +5,8 @@ * [Some Situations Where You'd Be Like "Shit!"](pages/issues/the-shit-time) * 💡 Abouts * [AI Translation Rule](pages/abouts/ai-translation-rule) + * [About Mingling CI Process](pages/abouts/ci) * [Markdown Code Verification System](pages/abouts/code-verify-system) + * [About Nightly Features](pages/abouts/nightly-features) * 📄 Templates * [Helpdoc Template](pages/templates/doc) diff --git a/docs/dev/index.html b/docs/dev/index.html index e62268d..1bfb5c5 100644 --- a/docs/dev/index.html +++ b/docs/dev/index.html @@ -141,7 +141,7 @@ auto2top: true, loadSidebar: true, maxLevel: 0, - subMaxLevel: 3, + subMaxLevel: 0, search: { placeholder: "Search dev docs…", noData: "No matches found.", diff --git a/ABOUT-CI.md b/docs/dev/pages/abouts/ci.md index 4cbcd6f..3a93c1c 100644 --- a/ABOUT-CI.md +++ b/docs/dev/pages/abouts/ci.md @@ -1,4 +1,7 @@ -# About Mingling CI Process +<h1 align="center">About Mingling CI Process</h1> +<p align="center"> + CI workflow and local execution guide for Mingling +</p> Mingling's CI process is built into the project, with its execution logic located in `.run/src/bin/ci.rs`. You can run it locally via the `cargo ci` command, which produces the same results as the `CI` workflow in GitHub Actions. @@ -12,13 +15,13 @@ An alias is defined in `.cargo/config.toml` at the project root: [alias] ci = "run --manifest-path .run/Cargo.toml --bin ci --quiet --" ``` - + Simply execute: ```bash cargo ci ``` - + ## CI Execution Flow `cargo ci` runs the following stages in order: diff --git a/ABOUT-NIGHTLY.md b/docs/dev/pages/abouts/nightly-features.md index f2d4ec7..13b666e 100644 --- a/ABOUT-NIGHTLY.md +++ b/docs/dev/pages/abouts/nightly-features.md @@ -1,4 +1,7 @@ -# About Nightly Rust +<h1 align="center">About Nightly Features</h1> +<p align="center"> + Using nightly Rust features in Mingling +</p> **Mingling** uses some features that are only available in the `nightly` toolchain. This requires you to enable the `nightly` feature: @@ -6,7 +9,7 @@ [dependencies] mingling = { version = "...", features = ["nightly"] } ``` - + ## Features > [!WARNING] diff --git a/docs/doc.html b/docs/doc.html index 783ccb4..a63fdd3 100644 --- a/docs/doc.html +++ b/docs/doc.html @@ -51,7 +51,7 @@ auto2top: true, loadSidebar: true, maxLevel: 0, - subMaxLevel: 3, + subMaxLevel: 0, search: { placeholder: "Search", noData: "No matches found.", |