diff options
| -rw-r--r-- | ABOUT-CI.md | 68 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 59 |
2 files changed, 94 insertions, 33 deletions
diff --git a/ABOUT-CI.md b/ABOUT-CI.md new file mode 100644 index 0000000..762fab8 --- /dev/null +++ b/ABOUT-CI.md @@ -0,0 +1,68 @@ +# About Mingling CI Process + +Mingling's CI process is built into the project, with its execution logic located in `dev_tools/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. + +During development, you can run `cargo ci` at any time to verify that your code hasn't introduced regressions. + +## Running Locally + +An alias is defined in `.cargo/config.toml` at the project root: + +```toml +[alias] +ci = "run --manifest-path dev_tools/Cargo.toml --bin ci --quiet --" +``` + +Simply execute: + +```bash +cargo ci +``` + +## CI Execution Flow + +`cargo ci` runs the following stages in order: + +### 1. Code Checking Stage (run by default, or individually via `--test-codes`) + +- **Scan and build all crates**: Recursively finds all `Cargo.toml` files in the project and runs `cargo build` for each crate in parallel. +- **Run Clippy on all crates**: Executes `cargo clippy ... -- -D warnings` in parallel; any warning will cause a failure. +- **Run unit tests for all crates**: Executes `cargo test` in parallel. + +### 2. Documentation and Example Checking Stage (run by default, or individually via `--test-docs`) + +- **Test all examples**: Runs the `test-examples` tool. +- **Verify Markdown code blocks compile**: Runs the `test-all-markdown-code` tool to check code blocks in all `*.md` files. See [ABOUT_CODE_VERIFY](docs/_ABOUT_CODE_VERIFY.md) for details. +- **Check if documentation is up to date**: Runs the following documentation refresh tools in sequence: + - `docs-code-box-fix` + - `docsify-sidebar-gen` + - `refresh-docs` + - `refresh-feature-mod` + - `sync-examples` +- Finally, runs `cargo fmt` to unify code formatting. + +### 3. File Normalization + +Runs `git add --renormalize .` to ensure file attributes such as line endings conform to the repository configuration. + +## Workspace Cleanliness and Temporary Commits + +To ensure reproducible CI results, `ci.rs` imposes strict requirements on the workspace state: + +- If the current workspace is not clean and `--dirty` has not been specified, the script will prompt whether to create a temporary commit: + - The commit message is `[DO NOT PUSH] CI TEMP [DO NOT PUSH]`. + - Use `-y` to auto-confirm without interaction. +- After CI finishes, the script automatically restores the workspace: + - First, `git reset --hard` discards all changes. + - If a temporary commit was created, it then runs `git reset --soft HEAD~1` and unstages everything, restoring the state to before CI started. +- If `--dirty` is specified, the temporary commit and the final cleanliness check are skipped. + +> **Warning**: `git reset --hard` is executed at the end of CI. If you use `--dirty`, ensure you have no unsaved important changes. + +## GitHub Actions Workflow + +`.github/workflows/ci.yml` defines the project's CI: + +- Triggered on `push` to the `main` branch. +- Runs `cargo ci` in parallel on `ubuntu-latest` and `windows-latest`. +- After CI passes, the `unreleased` tag is automatically moved to the latest commit on `main`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf66adc..d90db4a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,54 +4,48 @@ 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** | `dev_tools/` | Contains scripts and Rust tools | -| Scripts | `dev_tools/scripts/` | Helper `.sh`/`.ps1`/`.py` scripts, executed via `./run-tools.sh` or `.\run-tools.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` | - - +| 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** | `dev_tools/` | Contains scripts and Rust tools | +| Scripts | `dev_tools/scripts/` | Helper `.sh`/`.ps1`/`.py` scripts, executed via `./run-tools.sh` or `.\run-tools.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. **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** + - Submit a GitHub Pull Request and @Reviewer **[Weicao-CatilGrass](https://github.com/Weicao-CatilGrass)** for review + - Or send patches to **catil_grass@qq.com** 2. **Commit Messages** - - Clearly and concisely describe the changes, no stringent requirements - - Provide more detail for complex changes, keep it brief for simple changes - - But: if you use [Conventional Commits](https://www.conventionalcommits.org/), it would make me even happier :) + - Clearly and concisely describe the changes, no stringent requirements + - Provide more detail for complex changes, keep it brief for simple changes + - But: if you use [Conventional Commits](https://www.conventionalcommits.org/), it would make me even happier :) 3. **CHANGELOG** - - If the submission includes functional changes or fixes, **the PR must include modifications to CHANGELOG.md** to describe the changes - - For minor changes like typo fixes, **CHANGELOG.md modification is not required**, and we will merge faster + - If the submission includes functional changes or fixes, **the PR must include modifications to CHANGELOG.md** to describe the changes + - For minor changes like typo fixes, **CHANGELOG.md modification is not required**, and we will merge faster 4. **Multi-commit PR** - - A PR can contain multiple commits - - However, at least one commit must modify CHANGELOG.md + - A PR can contain multiple commits + - However, at least one commit must modify CHANGELOG.md 5. **Review** - - After submission, please notify [Weicao-CatilGrass](https://github.com/Weicao-CatilGrass) for review — this is the most efficient way to get feedback + - After submission, please notify [Weicao-CatilGrass](https://github.com/Weicao-CatilGrass) for review — this is the most efficient way to get feedback 6. **Binary Resources** - - For binary resource files (images, etc.), please be cautious about adding them to avoid repository bloat - - + - For binary resource files (images, etc.), please be cautious about adding them to avoid repository bloat ## 3. Documentation Contribution @@ -75,7 +69,8 @@ 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. ## 4. Regarding AI Agent Usage @@ -83,8 +78,6 @@ These steps are included in `cargo ci`; running `cargo ci` will execute them aut - **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 Mingling uses the **MIT + Apache 2.0** dual license. For details, please see: |