00e8d4811c
- 新增贡献指南、开发指南和README的中文版本 - 创建Dev Container配置文件，包括Dockerfile、docker-compose.yml和devcontainer.json - 初始化项目结构，创建必要的目录和文件 - 设置Rust开发环境，包括依赖和工具链
123 lines
4.9 KiB
Markdown
123 lines
4.9 KiB
Markdown
# meta-unit-core 开发指南
|
||
|
||
[English](GUIDE.md)
|
||
|
||
本指南将引导你设置 `meta-unit-core` 的开发环境，我们推荐使用 Dev Containers 以确保环境的一致性，并涵盖必要的 Rust 工具链。
|
||
|
||
---
|
||
|
||
## 1. 前提条件
|
||
|
||
在开始之前，请确保你的系统已安装以下软件：
|
||
|
||
* **Docker Desktop (或 Docker Engine)：** 运行 Dev Containers 所必需。
|
||
* [下载 Docker Desktop](https://www.docker.com/products/docker-desktop)
|
||
* **JetBrains Gateway (用于 RustRover)：** 推荐用于远程开发的 IDE。
|
||
* [下载 JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/)
|
||
* 或者，你也可以使用安装了 Dev Containers 扩展的 VS Code。
|
||
|
||
---
|
||
|
||
## 2. 设置开发环境（推荐：Dev Containers）
|
||
|
||
我们使用 Dev Containers 为所有贡献者提供一致且隔离的开发环境。
|
||
|
||
1. **克隆仓库：**
|
||
```bash
|
||
git clone https://nest.doylee.cn/dao-os/meta-unit-core.git
|
||
cd meta-unit-core
|
||
```
|
||
|
||
2. **使用 JetBrains Gateway 打开：**
|
||
* 启动 **JetBrains Gateway**。
|
||
* 选择 **"Dev Containers"** 选项卡。
|
||
* 点击 **"Connect to Dev Container"** 或类似选项。
|
||
* 导航并选择 `meta-unit-core` 项目目录（你克隆仓库的位置）。JetBrains Gateway 将自动检测到 `.devcontainer/devcontainer.json` 文件。
|
||
* 按照提示连接。Gateway 将构建容器（如果是首次连接），并打开连接到远程环境的 RustRover。
|
||
|
||
3. **容器内的初始设置：**
|
||
首次连接时，`.devcontainer/devcontainer.json` 中定义的 `postCreateCommand` (`cargo update && cargo check`) 将自动运行。这将获取所有 Rust 依赖项并执行初步的健全性检查。
|
||
|
||
如果你不使用 Dev Containers，你需要手动确保以下工具已安装：
|
||
* **Rust 工具链：** 从 [rustup.rs](https://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 后，你可以构建项目：
|
||
|
||
```bash
|
||
cargo build
|
||
```
|
||
|
||
以发布模式（优化性能）构建：
|
||
|
||
```bash
|
||
cargo build --release
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 运行测试
|
||
|
||
我们优先采用测试驱动开发 (TDD)。运行所有测试：
|
||
|
||
```bash
|
||
cargo test
|
||
```
|
||
|
||
运行特定测试：
|
||
|
||
```bash
|
||
cargo test <测试名称或正则表达式>
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 格式化和代码检查
|
||
|
||
在提交代码之前，请确保它符合我们的代码风格并通过了代码检查：
|
||
|
||
```bash
|
||
cargo fmt --all -- --check # 检查格式而不应用更改
|
||
cargo fmt --all # 应用格式更改
|
||
|
||
cargo clippy --all-targets --all-features -- -D warnings # 运行 linter，将所有警告视为错误
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 贡献工作流（基于主干开发）
|
||
|
||
我们遵循**基于主干开发 (Trunk-Based Development - TBD)** 的工作流：
|
||
|
||
1. **拉取最新主干代码：** 始终从 `main` 分支拉取最新更改。
|
||
```bash
|
||
git pull origin main
|
||
```
|
||
2. **创建短生命周期的特性分支：** 为了你的本地开发，创建一个新分支。这个分支应该很快合并回 `main`。
|
||
```bash
|
||
git checkout -b my-feature-branch
|
||
```
|
||
3. **开发与测试 (TDD)：** 进行小而原子性的提交。先编写测试，然后编写代码使其通过。
|
||
4. **推送并创建拉取请求 (PR)：** 推送你的分支并在 Gitea 上向 `main` 分支发起拉取请求。
|
||
```bash
|
||
git push origin my-feature-branch
|
||
```
|
||
5. **快速审查与合并：** 你的 PR 将被快速审查。一旦通过批准且 CI 通过，它将被合并到 `main`。
|
||
6. **使用特性开关：** 对于较大或未完成的特性，直接提交到 `main`，但用 [特性开关 (feature flags)](https://docs.rs/feature-flags/latest/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` 加速构建。
|
||
|
||
--- |