# Contributing to meta-unit-core

[中文](CONTRIBUTING-CN.md)

We warmly welcome your contributions to `meta-unit-core`, the foundational microkernel for the Dao OS. Your efforts help shape the future of CyberLife computation!

---

## 1. Before You Contribute

Before you start, please take a moment to review these guidelines:

* **Code of Conduct:** Please read and adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) (coming soon). We are committed to fostering an open and welcoming environment.
* **Development Guide:** Set up your development environment by following our [Development Guide](GUIDE.md). This ensures you have all the necessary tools and a consistent setup.
* **Understand the Vision:** Familiarize yourself with the overall vision of the [Dao Operating System Project](https://nest.doylee.cn/dao-os/Dao-OS-Project) and how `meta-unit-core` fits into it.

---

## 2. How to Contribute

We follow a **Trunk-Based Development (TBD)** workflow to ensure rapid iteration and continuous integration.

### Reporting Bugs

If you find a bug, please open an issue on our [Gitea Issue Tracker](https://nest.doylee.cn/dao-os/meta-unit-core/issues).

* **Search First:** Check existing issues to see if the bug has already been reported.
* **Clear Description:** Provide a clear and concise description of the bug.
* **Steps to Reproduce:** Include detailed steps to reproduce the bug.
* **Expected vs. Actual Behavior:** Describe what you expected to happen and what actually happened.
* **Environment:** Provide details about your environment (OS, Rust version, Docker version, etc.).

### Suggesting Enhancements or New Features

We love new ideas! If you have a suggestion:

* **Open an Issue:** Describe your idea in detail on the [Issue Tracker](https://nest.doylee.cn/dao-os/meta-unit-core/issues).
* **Justification:** Explain why this enhancement or feature would be valuable to the project.
* **Potential Design:** If you have thoughts on how it could be implemented, include them.

### Your First Code Contribution

For your first contribution, consider looking for issues marked with `good first issue` or `help wanted` on our [Issue Tracker](https://nest.doylee.cn/dao-os/meta-unit-core/issues).

### Code Contribution Workflow (TBD)

1.  **Pull Latest Main:** Always start by fetching and pulling the very latest changes from the `main` branch to your local machine.
    ```bash
    git pull origin main
    ```
2.  **Create a Short-Lived Feature Branch:** For your local development, create a new branch. This branch should focus on a single, small, atomic change and be merged back into `main` quickly.
    ```bash
    git checkout -b feature/my-new-awesome-thing
    # Or for a bug fix:
    git checkout -b bugfix/fix-that-issue
    ```
    *Naming Convention:* Prefer `feature/`, `bugfix/`, `docs/`, `refactor/` prefixes.
3.  **Develop & Test:**
    * **Test-Driven Development (TDD):** We encourage writing tests *before* writing the code to ensure correctness and maintainability.
    * Make small, logical commits with clear commit messages.
    * Ensure all existing tests pass (`cargo test`).
    * Add new tests for your changes.
4.  **Format and Lint:** Before committing, ensure your code adheres to our style guidelines.
    ```bash
    cargo fmt --all           # Apply formatting changes
    cargo clippy --all-targets --all-features -- -D warnings # Run linter, treating all warnings as errors
    ```
5.  **Push Your Branch:**
    ```bash
    git push origin your-branch-name
    ```
6.  **Create a Pull Request (PR):**
    * Go to our [Gitea repository](https://nest.doylee.cn/dao-os/meta-unit-core) and create a new Pull Request from your branch to the `main` branch.
    * **PR Title:** Use a clear, concise title summarizing your changes.
    * **PR Description:** Provide a detailed description of your changes, why they were made, any relevant issue numbers, and how to test them (if applicable).
    * **CI Checks:** Ensure all Continuous Integration (CI) checks pass.
7.  **Fast Review & Merge:** Your PR will be reviewed quickly. Once approved and CI passes, it will be merged into `main`. We aim for small, frequent merges.
8.  **Use Feature Flags for Large Features:** For larger or incomplete features that span multiple PRs or development cycles, commit directly to `main` but wrap the new code with [feature flags](https://docs.rs/feature-flags/latest/feature_flags/). This ensures the `main` branch always remains stable and releasable.

---

## 3. Code Style and Conventions

* **Rust Format:** We use `rustfmt` to enforce code style. Always run `cargo fmt` before committing.
* **Clippy:** We use `clippy` for linting. All `clippy` warnings must be resolved (`cargo clippy --all-targets --all-features -- -D warnings`).
* **Commit Messages:** Follow a clear and concise commit message convention (e.g., [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)).
    * *Example:* `feat: Add new IPC mechanism` or `fix: Resolve race condition in task scheduler`
* **Documentation:** All public functions, structs, enums, and modules should have clear Rustdoc comments (`///`). Examples are highly encouraged.

---

## 4. Community and Communication

* **Issue Tracker:** [https://nest.doylee.cn/dao-os/meta-unit-core/issues](https://nest.doylee.cn/dao-os/meta-unit-core/issues) (for bugs, features, and discussions)
* **Chat/Forum:** (Consider adding a Discord, Matrix, or forum link here if you set one up)
* **Pull Requests:** Used for submitting code changes.

Thank you for your interest in contributing to `meta-unit-core`! We look forward to your contributions.

---