diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 109 |
1 files changed, 51 insertions, 58 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e34e93..60c1dbe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,35 +1,45 @@ # 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 | -| **CI system** | `mingling_ci/` | CI crate built on the Mingling framework, invoked via `cargo ci` | -| **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`, …) | -| **CI configs** | `.config/` | `ci-ignored-dirs.txt`, `verified-docs.toml`, `docs-lang.txt` | -| **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** | `dev/ci/` | CI crate built on the Mingling framework, invoked via `cargo ci` | +| **CI configs** | `dev/configs/` | `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 the full CI pipeline locally (see [ABOUT CI](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/ci) for how it works): @@ -38,13 +48,15 @@ If you'd like to contribute to `mingling`, `mingling_core`, `mingling_macros`, o ./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.) +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: @@ -77,12 +89,6 @@ If you change expected behavior, update the assertions in the example's `test.to After editing examples, run these commands to keep things in sync: ```bash -# Ensure code compiles -cargo ci build-check - -# Ensure code style -cargo ci clippy-check - # Check all examples behave as expected cargo ci example-check @@ -97,11 +103,21 @@ cargo ci example-refresh ### 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`. + +> [!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 -- **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: +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: ```bash # Fix code box issues and regenerate sidebars @@ -126,7 +142,8 @@ 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 (`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)! +`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](https://github.com/mingling-rs/mingling/issues) and contact [Weicao-CatilGrass](https://github.com/Weicao-CatilGrass)! ## 3. Submission Guide 🖊 @@ -154,30 +171,6 @@ No strict requirements here — just modify the relevant `*.html` files. Preview 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 -# Fix code block blank line issues and regenerate sidebars -cargo ci docsify-refresh - -# Regenerate example docs module and examples index -cargo ci example-refresh -``` - -These steps are part of the full pipeline; `./run.sh ci` executes them automatically and fails if they leave the tree dirty (i.e. the generated files were stale). - -> [!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. - ## 5. Regarding AI Agent Usage 🤖 - You are free to use AI agents to assist development — no restrictions @@ -191,6 +184,6 @@ Mingling uses the **MIT + Apache 2.0** dual license. For details, please see: - [LICENSE-MIT](LICENSE-MIT) - [LICENSE-APACHE](LICENSE-APACHE) -# Contributors +# Contributors ❤ <img src="https://contrib.rocks/image?repo=mingling-rs/mingling" /> |