diff options
| -rw-r--r-- | .github/workflows/ci-check-only.yml | 47 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 129 |
2 files changed, 155 insertions, 21 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 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: |