From 491b034d02856dc64fb9e632e0d3e566a517247c Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Mon, 18 May 2026 15:30:42 +0800
Subject: Add contribution guidelines

---
 CONTRIBUTING.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 CONTRIBUTING.md

(limited to 'CONTRIBUTING.md')

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..db5e288
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,92 @@
+# Contribution Guide
+
+First of all, thank you for your interest in Mingling! 🎉 Whether it's fixing bugs, improving documentation, adding new features, or making suggestions, we welcome all contributions.
+
+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` |
+
+
+
+## 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**
+
+2. **Commit Messages**
+   - Clearly and concisely describe the changes, no stringent requirements
+   - Provide more detail for complex changes, keep it brief for simple changes
+
+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
+
+4. **Multi-commit PR**
+
+   - 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
+
+6. **Binary Resources**
+   - For binary resource files (images, etc.), please be cautious about adding them to avoid repository bloat
+
+
+
+## 3. Documentation Contribution
+
+### Documentation Location
+
+- English documentation: `docs/pages/`
+- Chinese documentation: `docs/_zh_CN/pages/`
+
+### Documentation Build
+
+After editing documentation, refresh relevant files:
+
+```bash
+# Refresh sidebar and README sync
+./run-tools.sh docsify-sidebar-gen
+./run-tools.sh refresh-docs
+
+# Fix code block blank line issues
+./run-tools.sh docs-code-box-fix
+```
+
+These steps are included in `cargo ci`; running `cargo ci` will execute them automatically.
+
+
+
+## 4. 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
+
+Mingling uses the **MIT + Apache 2.0** dual license. For details, please see:
+
+- [LICENSE-MIT](LICENSE-MIT)
+- [LICENSE-APACHE](LICENSE-APACHE)
-- 
cgit