1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
# 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
- 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
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.
> [!TIP]
> You can check the [ABOUT CI](./ABOUT-CI.md) section to learn how "Mingling CI" works.
## 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)
|
