meta-unit-core/GUIDE.md

Development Guide for meta-unit-core

中文

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
• JetBrains Gateway (for RustRover): The recommended IDE for remote development.
  • Download JetBrains 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:

   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.
   • 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:

cargo build

To build in release mode (optimized for performance):

cargo build --release

---

4. Running Tests

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

cargo test

To run a specific test:

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:

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.

   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.

   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.

   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. 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.

---