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 to get an overview of the project.

1. Project Structure 📦

2. How to Contribute

To ensure your contribution goes smoothly, please choose the guide that best fits your contribution area.

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 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 the full CI pipeline locally (see ABOUT CI for how it works):

./run.sh ci

If it passes locally, your changes are most likely correct. (./run.sh ci runs python .run/src/bin/ci.py, which locks the workspace, runs every check and refresh step, then unlocks — the final unlock fails if the run left the tree dirty.)

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:

[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"]

Optionally, each example may contain a test.toml file declaring expected output tests, which are executed by CI (cargo ci example-check):

[[runs]]
input = ["greet", "Alice"]

expect.exit-code = 0
expect.result = "Hello, Alice!"

• input is the list of CLI arguments passed to the example binary
• expect.exit-code / expect.result assert the expected process exit code and stdout output

If you change expected behavior, update the assertions in the example's test.toml.

After editing examples, run these commands to keep things in sync:

# Check all examples behave as expected
cargo ci example-check

# Sync examples content into mingling/src/example_docs.rs and examples.json
cargo ci example-refresh

# (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 to the documentation, please edit the files under docs/. For translations into other languages, refer to the directory structure under docs/zh_CN.

[!Warning]

Mingling's API is currently unstable, so adding documentation content may not be the best use of effort at this stage.

It is recommended to only fix typos, grammar issues, etc.

Verify

Documentation is checked by cargo ci markdown-check-all and cargo ci markdown-compare-all to ensure that all languages have consistent documentation structure and that the code compiles.

You can verify the documentation with the following commands:

# Fix code box issues and regenerate sidebars
cargo ci docsify-refresh

# Verify all Markdown code blocks compile
cargo ci markdown-check-all

# Verify translated docs mirror the reference structure
cargo ci markdown-compare-all

Web Frontend Contribution

No strict requirements here — just modify the relevant *.html files. Preview with:

# 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 (dev/ci/) or other dev tools (under .run/), please first file an Issue and contact Weicao-CatilGrass!

3. Submission Guide 🖊

1. Pull Request

   • Submit a GitHub Pull Request and @Reviewer 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, 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 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

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

6. License 📖

Mingling uses the MIT + Apache 2.0 dual license. For details, please see:

• LICENSE-MIT
• LICENSE-APACHE

Contributors ❤