aboutsummaryrefslogtreecommitdiff
path: root/docs/dev/pages/abouts/ci.md
diff options
context:
space:
mode:
author魏曹先生 <1992414357@qq.com>2026-07-10 18:17:39 +0800
committer魏曹先生 <1992414357@qq.com>2026-07-10 18:17:39 +0800
commit6be5894f40b2c2543f23aab7f7b4ffc73dbd0d77 (patch)
treed8e9e98b0fd2c0637503a1b73a8d388f56c3c1ba /docs/dev/pages/abouts/ci.md
parent70060f1bb395c684b64a2fb94b76442120097409 (diff)
docs: migrate ABOUT-CI and ABOUT-NIGHTLY to dev docs site
Replace relative file links with absolute URLs and add centered page headers to the migrated docs. Update the dev sidebar to include the new pages.
Diffstat (limited to 'docs/dev/pages/abouts/ci.md')
-rw-r--r--docs/dev/pages/abouts/ci.md71
1 files changed, 71 insertions, 0 deletions
diff --git a/docs/dev/pages/abouts/ci.md b/docs/dev/pages/abouts/ci.md
new file mode 100644
index 0000000..3a93c1c
--- /dev/null
+++ b/docs/dev/pages/abouts/ci.md
@@ -0,0 +1,71 @@
+<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.
+
+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 .run/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`.