meta-unit-core/GUIDE.md

# Development Guide for meta-unit-core

[中文](GUIDE-CN.md)

This guide will walk you through setting up your development environment for `meta-unit-core` using Dev Containers (recommended for consistency) and the necessary Rust toolchains.

---

## 1. Prerequisites

Before you begin, ensure you have the following installed on your system:

* **Docker Desktop (or Docker Engine):** Required for running Dev Containers.
    * [Download Docker Desktop](https://www.docker.com/products/docker-desktop)
* **JetBrains Gateway (for RustRover):** The recommended IDE for remote development.
    * [Download JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/)
    * Alternatively, you can use VS Code with the Dev Containers extension.

---

## 2. Setting Up the Development Environment (Recommended: Dev Containers)

We use Dev Containers to provide a consistent and isolated development environment for all contributors.

1.  **Clone the Repository:**
    ```bash
    git clone https://nest.doylee.cn/dao-os/meta-unit-core.git
    cd meta-unit-core
    ```

2.  **Open with JetBrains Gateway:**
    * Launch **JetBrains Gateway**.
    * Select the **"Dev Containers"** tab.
    * Click **"Connect to Dev Container"** or a similar option.
    * Navigate to and select the `meta-unit-core` project directory (where you cloned the repository). JetBrains Gateway will automatically detect the `.devcontainer/devcontainer.json` file.
    * Follow the prompts to connect. Gateway will build the container (if it's the first time) and open RustRover connected to the remote environment.

3.  **Initial Setup within the Container:**
    Upon first connection, the `postCreateCommand` defined in `.devcontainer/devcontainer.json` (`cargo update && cargo check`) will automatically run. This fetches all Rust dependencies and performs an initial sanity check.

    If you're not using Dev Containers, you'll need to manually ensure you have:
    * **Rust Toolchain:** Install `rustup` from [rustup.rs](https://rustup.rs/).
    * **WASM Target:** Add the WASM target: `rustup target add wasm32-unknown-unknown`
    * **Cargo Subcommands:** Install useful subcommands like `cargo-watch`, `cargo-edit`, `cargo-tarpaulin` (for coverage), `mdbook` (for docs).
    * **Protobuf Tools:** `protoc` compiler and `protoc-gen-prost` (for Rust code generation) if you're working directly with `.proto` files outside the `meta-unit-proto` project's build process.

---

## 3. Building the Project

Once inside the Dev Container, you can build the project:

```bash
cargo build
```

To build in release mode (optimized for performance):

```bash
cargo build --release
```

---

## 4. Running Tests

We prioritize Test-Driven Development (TDD). To run all tests:

```bash
cargo test
```

To run a specific test:

```bash
cargo test <test_name_or_regex>
```

---

## 5. Formatting and Linting

Before submitting your code, please ensure it adheres to our code style and passes lint checks:

```bash
cargo fmt --all -- --check # Check formatting without applying changes
cargo fmt --all           # Apply formatting changes

cargo clippy --all-targets --all-features -- -D warnings # Run linter with all warnings as errors
```

---

## 6. Contributing Workflow (Trunk-Based Development)

We follow a **Trunk-Based Development (TBD)** workflow:

1.  **Pull Latest Main:** Always start by pulling the latest changes from the `main` branch.
    ```bash
    git pull origin main
    ```
2.  **Create a Short-Lived Feature Branch:** For your local development, create a new branch. This branch should be merged back into `main` quickly.
    ```bash
    git checkout -b my-feature-branch
    ```
3.  **Develop & Test (TDD):** Make small, atomic commits. Write tests first, then code to pass them.
4.  **Push and Create Pull Request (PR):** Push your branch and open a Pull Request against the `main` branch on Gitea.
    ```bash
    git push origin my-feature-branch
    ```
5.  **Fast Review & Merge:** Your PR will be reviewed quickly. Once approved and CI passes, it will be merged into `main`.
6.  **Use Feature Flags:** For larger or incomplete features, commit directly to `main` but wrap the new code with [feature flags](https://docs.rs/feature-flags/latest/feature_flags/). This ensures `main` always remains releasable.

---

## 7. Troubleshooting

* **Container fails to build:** Check `meta-unit-core/.devcontainer/Dockerfile` and `docker-compose.yml` for syntax errors. Ensure Docker Desktop is running and has enough resources.
* **"No such file or directory" for `Dockerfile`:** Double-check that `Dockerfile`, `docker-compose.yml`, and `devcontainer.json` are all in the `meta-unit-core/.devcontainer/` directory, and that `docker-compose.yml`'s `build` context is set correctly (`context: .` and `dockerfile: Dockerfile`).
* **Permissions errors in container:** Ensure the user running inside the container (if not root) has appropriate permissions to the mounted `/app` directory. You might need to adjust ownership/permissions on your host system.
* **Slow `cargo build`:** Ensure Docker Desktop has sufficient CPU and memory allocated. Leverage `sccache` for faster builds.

---