diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 163 |
1 files changed, 82 insertions, 81 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 779bc3e..4f1b4bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,42 +1,62 @@ # 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. +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 | -| **Mingling Pathfinder** | `mingling_pathf/` | Build-time module path resolution for types | -| **Mingling Picker2** | `arg_picker/` | Mingling Arguments Parser | -| **Mingling Picker2 Macros** | `arg_picker_macros/` | Mingling Arguments Parser Macros | -| **Scaffolding tool** | `mling/` | Scaffolding tool `mingling-cli` | -| **Examples** | `examples/` | To add expected output tests, add a `test.toml` in the example's dir | -| **Documents** | `docs/` | All documents | -| **Dev Documents** | `docs/dev/` | Internal documents | -| **Resources** | `docs/res/` | All resources | -| **Development tools** | `.run/src/bin` | Contains scripts and Rust tools | -| **CI** | `.run/src/bin/ci.rs` | Can be invoked directly via `cargo ci` | -| **Temporary files** | `.temp/` | Ignored by `.gitignore` | +| Category | Path/Name | Description | +| ----------------------- | -------------------- | ----------------------------------------------------------------------- | +| Main | | | +| **Entry crate** | `mingling/` | Project entry point | +| **Mingling CLI** | `mingling_cli/` | Mingling's toolchains | +| **Core library** | `mingling_core/` | Imported as an external dependency | +| **Macro library** | `mingling_macros/` | Imported as an external dependency | +| **Mingling Pathfinder** | `mingling_pathf/` | Build-time module path resolution for types | +| **Arg Picker** | `arg_picker/` | Mingling Arguments Parser | +| **Arg Picker Macros** | `arg_picker_macros/` | Mingling Arguments Parser Macros | +| Documents | | | +| **Examples** | `examples/` | To add expected output tests, add a `test.toml` in the example's dir | +| **Help Documents** | `docs/pages/` | User-facing help documents (raw) | +| **Help Documents** | `docs/[LANG]/pages` | User-facing help documents (translations) | +| **Dev Documents** | `docs/dev/` | Internal documents | +| **Resources** | `docs/res/` | All resources | +| Dev Tools | | | +| **CI system** | `mingling_ci/` | CI crate built on the Mingling framework, invoked via `cargo ci` | +| **CI configs** | `.config/` | `ci-ignored-dirs.txt`, `verified-docs.toml`, `docs-lang.txt` | +| **CI orchestration** | `.run/src/bin/ci.py` | Full pipeline script (lock → checks → refresh → unlock) | +| **Development tools** | `.run/src/bin` | Contains scripts and Rust tools (`deploy-api-docs`, `install-mling`, …) | +| Misc | | | +| **Temporary files** | `.temp/` | Ignored by `.gitignore` | ## 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](https://github.com/mingling-rs/mingling/issues) page to confirm before starting work. +If you'd like to contribute to `mingling`, `mingling_core`, `mingling_macros`, or `mingling_pathf`, +first share your idea on the [Github Issue](https://github.com/mingling-rs/mingling/issues) 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 `cargo ci` locally (see [ABOUT CI](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/ci) for how it works). If `cargo ci` passes locally, your changes are most likely correct. +- **After finishing**, run the full CI pipeline locally (see [ABOUT CI](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/ci) for how it works): + +```bash +./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>/` +- Place each example in `examples/{{example-dir}}/` - Each dir must contain a `page.toml` file describing the example's metadata - `page.toml` format: @@ -51,7 +71,7 @@ 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 (`./run.sh test-examples`): +Optionally, each example may contain a `test.toml` file declaring expected output tests, which are executed by CI (`cargo ci example-check`): ```toml [[runs]] @@ -66,23 +86,14 @@ expect.result = "Hello, Alice!" If you change expected behavior, update the assertions in the example's `test.toml`. -After editing examples, run these scripts to keep things in sync: +After editing examples, run these commands to keep things in sync: ```bash -# Ensure code compiles -./run.sh build-all - -# Ensure code style -./run.sh clippy - -# Sync page.toml info to docs/example-pages/examples.json -./run.sh sync-examples - # Check all examples behave as expected -./run.sh test-examples +cargo ci example-check -# Sync examples content into mingling/src/example_docs.rs -./run.sh refresh-docs +# 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 @@ -92,21 +103,31 @@ After editing examples, run these scripts to keep things in sync: ### Documentation Contribution -To contribute docs, edit files under `docs/`. For other language translations, refer to the structure under `docs/zh_CN`. +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`. -- **When editing docs**, prioritize **Chinese docs** first, then **English docs** — since I ([@Weicao-CatilGrass](https://github.com/Weicao-CatilGrass)) am a native Chinese speaker, this is more efficient. -- If your changes involve code, check the [Code Verify System](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/code-verify-system), which explains how CI checks code. -- **Before submitting**, always run: +> [!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.** -```bash -# Fix code block issues in docsify -./run.sh docs-code-box-fix +#### 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. -# Generate sidebar -./run.sh docsify-sidebar-gen +You can verify the documentation with the following commands: + +```bash +# Fix code box issues and regenerate sidebars +cargo ci docsify-refresh # Verify all Markdown code blocks compile -./run.sh test-all-markdown-code +cargo ci markdown-check-all + +# Verify translated docs mirror the reference structure +cargo ci markdown-compare-all ``` ### Web Frontend Contribution @@ -121,58 +142,34 @@ No strict requirements here — just modify the relevant `*.html` files. Preview ### Dev Tool Contribution -`Mingling CI` code is under strict review. If you want to improve `mingling`'s CI pipeline or other dev tools (under `.run/`), **please** first file an [Issue](https://github.com/mingling-rs/mingling/issues) and contact [Weicao-CatilGrass](https://github.com/Weicao-CatilGrass)! +`Mingling CI` code is under strict review. If you want to improve `mingling`'s CI pipeline (`mingling_ci/`) or other dev tools (under `.run/`), +**please** first file an [Issue](https://github.com/mingling-rs/mingling/issues) and contact [Weicao-CatilGrass](https://github.com/Weicao-CatilGrass)! ## 3. 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 - -## 4. 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.sh docsify-sidebar-gen -./run.sh refresh-docs - -# Fix code block blank line issues -./run.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](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/ci) section to learn how "Mingling CI" works. + - For binary resource files (images, etc.), please be cautious about adding them to avoid repository bloat ## 5. Regarding AI Agent Usage 🤖 @@ -186,3 +183,7 @@ Mingling uses the **MIT + Apache 2.0** dual license. For details, please see: - [LICENSE-MIT](LICENSE-MIT) - [LICENSE-APACHE](LICENSE-APACHE) + +# Contributors ❤ + +<img src="https://contrib.rocks/image?repo=mingling-rs/mingling" /> |