Files

- 新增贡献指南、开发指南和README的中文版本
- 创建Dev Container配置文件，包括Dockerfile、docker-compose.yml和devcontainer.json
- 初始化项目结构，创建必要的目录和文件
- 设置Rust开发环境，包括依赖和工具链

2025-06-05 13:59:19 +08:00

4.9 KiB

Raw Permalink Blame History

meta-unit-core 开发指南

English

本指南将引导你设置 meta-unit-core 的开发环境，我们推荐使用 Dev Containers 以确保环境的一致性，并涵盖必要的 Rust 工具链。

1. 前提条件

在开始之前，请确保你的系统已安装以下软件：

Docker Desktop (或 Docker Engine)： 运行 Dev Containers 所必需。
- 下载 Docker Desktop
JetBrains Gateway (用于 RustRover)： 推荐用于远程开发的 IDE。
- 下载 JetBrains Gateway
- 或者，你也可以使用安装了 Dev Containers 扩展的 VS Code。

2. 设置开发环境（推荐：Dev Containers）

我们使用 Dev Containers 为所有贡献者提供一致且隔离的开发环境。

克隆仓库：

git clone https://nest.doylee.cn/dao-os/meta-unit-core.git
cd meta-unit-core

使用 JetBrains Gateway 打开：
- 启动 JetBrains Gateway。
- 选择 "Dev Containers" 选项卡。
- 点击 "Connect to Dev Container" 或类似选项。
- 导航并选择 meta-unit-core 项目目录（你克隆仓库的位置）。JetBrains Gateway 将自动检测到 .devcontainer/devcontainer.json 文件。
- 按照提示连接。Gateway 将构建容器（如果是首次连接），并打开连接到远程环境的 RustRover。
容器内的初始设置： 首次连接时，.devcontainer/devcontainer.json 中定义的 postCreateCommand (cargo update && cargo check) 将自动运行。这将获取所有 Rust 依赖项并执行初步的健全性检查。

如果你不使用 Dev Containers，你需要手动确保以下工具已安装：
- Rust 工具链： 从 rustup.rs 安装 rustup。
- WASM 目标： 添加 WASM 目标：rustup target add wasm32-unknown-unknown
- Cargo 子命令： 安装有用的子命令，如 cargo-watch、cargo-edit、cargo-tarpaulin（用于覆盖率）、mdbook（用于文档）。
- Protobuf 工具： 如果你直接处理 .proto 文件（而非通过 meta-unit-proto 项目的构建过程），则需要 protoc 编译器和 protoc-gen-prost（用于 Rust 代码生成）。

3. 构建项目

进入 Dev Container 后，你可以构建项目：

cargo build

以发布模式（优化性能）构建：

cargo build --release

4. 运行测试

我们优先采用测试驱动开发 (TDD)。运行所有测试：

cargo test

运行特定测试：

cargo test <测试名称或正则表达式>

5. 格式化和代码检查

在提交代码之前，请确保它符合我们的代码风格并通过了代码检查：

cargo fmt --all -- --check # 检查格式而不应用更改
cargo fmt --all           # 应用格式更改

cargo clippy --all-targets --all-features -- -D warnings # 运行 linter，将所有警告视为错误

6. 贡献工作流（基于主干开发）

我们遵循基于主干开发 (Trunk-Based Development - TBD) 的工作流：

拉取最新主干代码： 始终从 main 分支拉取最新更改。
```
git pull origin main
```
创建短生命周期的特性分支： 为了你的本地开发，创建一个新分支。这个分支应该很快合并回 main。
```
git checkout -b my-feature-branch
```
开发与测试 (TDD)： 进行小而原子性的提交。先编写测试，然后编写代码使其通过。
推送并创建拉取请求 (PR)： 推送你的分支并在 Gitea 上向 main 分支发起拉取请求。
```
git push origin my-feature-branch
```
快速审查与合并： 你的 PR 将被快速审查。一旦通过批准且 CI 通过，它将被合并到 main。
使用特性开关： 对于较大或未完成的特性，直接提交到 main，但用特性开关 (feature flags) 包裹新代码。这确保 main 始终保持可发布状态。

7. 故障排除

容器构建失败： 检查 meta-unit-core/.devcontainer/Dockerfile 和 docker-compose.yml 是否有语法错误。确保 Docker Desktop 正在运行并有足够的资源。
"No such file or directory" for Dockerfile： 仔细检查 Dockerfile、docker-compose.yml 和 devcontainer.json 是否都在 meta-unit-core/.devcontainer/ 目录下，并确保 docker-compose.yml 的 build 上下文设置正确（context: . 和 dockerfile: Dockerfile）。
容器内权限错误： 确保容器内部运行的用户（如果不是 root）对挂载的 /app 目录具有适当的权限。你可能需要调整宿主机上该目录的所有权/权限。
cargo build 慢： 确保 Docker Desktop 分配了足够的 CPU 和内存。可以考虑使用 sccache 加速构建。

4.9 KiB Raw Permalink Blame History Unescape Escape