250 lines
5.9 KiB
Markdown
250 lines
5.9 KiB
Markdown
|
# 贡献指南
|
|||
|
|
|
|||
|
|
感谢你对 ViewDesignEngine 的关注！本文档说明如何参与 VDE 开发。
|
|||
|
|
|
|||
|
|
## 目录
|
|||
|
|
|
|||
|
|
1. [行为准则](#1-行为准则)
|
|||
|
|
2. [如何贡献](#2-如何贡献)
|
|||
|
|
3. [开发环境搭建](#3-开发环境搭建)
|
|||
|
|
4. [代码规范](#4-代码规范)
|
|||
|
|
5. [提交规范](#5-提交规范)
|
|||
|
|
6. [Code Review 流程](#6-code-review-流程)
|
|||
|
|
7. [测试要求](#7-测试要求)
|
|||
|
|
8. [文档要求](#8-文档要求)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 行为准则
|
|||
|
|
|
|||
|
|
- 尊重所有贡献者，建设性沟通
|
|||
|
|
- 关注代码质量而非个人
|
|||
|
|
- 接受建设性批评，乐于改进
|
|||
|
|
- 帮助新人融入项目
|
|||
|
|
|
|||
|
|
## 2. 如何贡献
|
|||
|
|
|
|||
|
|
| 贡献方式 | 说明 |
|
|||
|
|
|---------|------|
|
|||
|
|
| Bug 报告 | 通过 Issue 提交，附重现步骤 |
|
|||
|
|
| 功能请求 | 先开 Issue 讨论，获得认同后再实现 |
|
|||
|
|
| 代码贡献 | Fork → Branch → PR → Review → Merge |
|
|||
|
|
| 文档改进 | 直接提 PR 修正文档错误 |
|
|||
|
|
| 测试补充 | 新增测试用例，提高覆盖率 |
|
|||
|
|
| 插件开发 | 按 [插件系统设计](plugin-system.md) 开发第三方插件 |
|
|||
|
|
|
|||
|
|
### 贡献流程
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. 创建分支
|
|||
|
|
git checkout -b feat/my-feature
|
|||
|
|
|
|||
|
|
# 2. 开发（遵循代码规范）
|
|||
|
|
# ... 编写代码 + 测试 ...
|
|||
|
|
|
|||
|
|
# 3. 本地验证
|
|||
|
|
cmake -B build -DBUILD_TESTS=ON
|
|||
|
|
cmake --build build -j$(nproc)
|
|||
|
|
cd build && ctest --output-on-failure
|
|||
|
|
|
|||
|
|
# 4. 提交
|
|||
|
|
git add -A
|
|||
|
|
git commit -m "feat(module): description"
|
|||
|
|
|
|||
|
|
# 5. 推送并创建 PR
|
|||
|
|
git push origin feat/my-feature
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 3. 开发环境搭建
|
|||
|
|
|
|||
|
|
### 前提条件
|
|||
|
|
|
|||
|
|
- **编译器**: GCC 11+ / Clang 16+
|
|||
|
|
- **CMake**: ≥ 3.16
|
|||
|
|
- **Eigen 3**: 自动下载（FetchContent）
|
|||
|
|
- **Google Test**: 自动下载（FetchContent）
|
|||
|
|
|
|||
|
|
### Docker 环境（推荐）
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 构建 Docker 镜像
|
|||
|
|
docker build -t vde-builder -f docker/Dockerfile.dev .
|
|||
|
|
|
|||
|
|
# 运行开发容器
|
|||
|
|
docker run -it --rm -v $PWD:/ws vde-builder bash
|
|||
|
|
cd /ws
|
|||
|
|
cmake -B build -DCMAKE_BUILD_TYPE=Debug
|
|||
|
|
cmake --build build -j$(nproc)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 本地环境
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Ubuntu/Debian
|
|||
|
|
sudo apt install build-essential cmake g++-11
|
|||
|
|
|
|||
|
|
# CentOS/RHEL
|
|||
|
|
sudo yum install gcc-toolset-11 cmake3
|
|||
|
|
|
|||
|
|
# 构建
|
|||
|
|
cmake -B build -DCMAKE_BUILD_TYPE=Debug
|
|||
|
|
cmake --build build -j$(nproc)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 代码规范
|
|||
|
|
|
|||
|
|
### 命名规范
|
|||
|
|
|
|||
|
|
| 元素 | 规范 | 示例 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| 命名空间 | 小写，`vde::` 前缀 | `vde::brep`, `vde::mesh` |
|
|||
|
|
| 类/结构体 | PascalCase | `HalfedgeMesh`, `BrepModel` |
|
|||
|
|
| 函数/方法 | snake_case | `add_vertex()`, `to_mesh()` |
|
|||
|
|
| 成员变量 | snake_case，尾部 `_` | `vertices_`, `tolerance_` |
|
|||
|
|
| 常量 | kPascalCase 或 UPPER_SNAKE | `kDefaultTolerance`, `VDE_PI` |
|
|||
|
|
| 头文件 | snake_case.h | `halfedge_mesh.h` |
|
|||
|
|
| 源文件 | snake_case.cpp | `halfedge_mesh.cpp` |
|
|||
|
|
| 模板参数 | PascalCase | `typename T`, `typename Scalar` |
|
|||
|
|
|
|||
|
|
### 文件组织
|
|||
|
|
|
|||
|
|
```cpp
|
|||
|
|
// 头文件示例
|
|||
|
|
#pragma once
|
|||
|
|
|
|||
|
|
#include <vde/foundation/point.h> // 公开依赖
|
|||
|
|
#include <vector> // 标准库
|
|||
|
|
|
|||
|
|
namespace vde::mesh {
|
|||
|
|
|
|||
|
|
/// 简要描述
|
|||
|
|
class HalfedgeMesh {
|
|||
|
|
public:
|
|||
|
|
// 构造/析构
|
|||
|
|
HalfedgeMesh();
|
|||
|
|
~HalfedgeMesh();
|
|||
|
|
|
|||
|
|
// 禁止拷贝，允许移动
|
|||
|
|
HalfedgeMesh(const HalfedgeMesh&) = delete;
|
|||
|
|
HalfedgeMesh& operator=(const HalfedgeMesh&) = delete;
|
|||
|
|
HalfedgeMesh(HalfedgeMesh&&) noexcept = default;
|
|||
|
|
HalfedgeMesh& operator=(HalfedgeMesh&&) noexcept = default;
|
|||
|
|
|
|||
|
|
// 公开接口
|
|||
|
|
int add_vertex(const Point3D& p);
|
|||
|
|
int add_face(const std::vector<int>& vertex_ids);
|
|||
|
|
|
|||
|
|
private:
|
|||
|
|
// 成员变量
|
|||
|
|
std::vector<Point3D> vertices_;
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
} // namespace vde::mesh
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 编码风格
|
|||
|
|
|
|||
|
|
- 缩进: 4 空格，不用 Tab
|
|||
|
|
- 行宽: 100 字符
|
|||
|
|
- 大括号: K&R 风格（开括号不换行）
|
|||
|
|
- 注释: Doxygen `///` 风格
|
|||
|
|
- `#include` 顺序: 本模块头 → 项目头 → 标准库
|
|||
|
|
- 避免 `using namespace` 在头文件中
|
|||
|
|
- 优先使用 `std::unique_ptr` 而非裸指针
|
|||
|
|
|
|||
|
|
### 禁止事项
|
|||
|
|
|
|||
|
|
- ❌ 全局可变状态
|
|||
|
|
- ❌ 裸 `new`/`delete`（用智能指针）
|
|||
|
|
- ❌ C 风格类型转换（用 `static_cast` 等）
|
|||
|
|
- ❌ 可变参数 `...`
|
|||
|
|
- ❌ 异常规范声明（`throw()`）
|
|||
|
|
- ❌ 头文件 `using namespace`
|
|||
|
|
|
|||
|
|
## 5. 提交规范
|
|||
|
|
|
|||
|
|
### 提交消息格式
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
<type>(<scope>): <subject>
|
|||
|
|
|
|||
|
|
<body>
|
|||
|
|
|
|||
|
|
<footer>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
| type | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `feat` | 新功能 |
|
|||
|
|
| `fix` | Bug 修复 |
|
|||
|
|
| `docs` | 文档变更 |
|
|||
|
|
| `style` | 格式调整（不影响逻辑） |
|
|||
|
|
| `refactor` | 重构 |
|
|||
|
|
| `test` | 测试相关 |
|
|||
|
|
| `perf` | 性能优化 |
|
|||
|
|
| `chore` | 构建/工具 |
|
|||
|
|
|
|||
|
|
示例：
|
|||
|
|
```
|
|||
|
|
feat(brep): add variable radius fillet support
|
|||
|
|
|
|||
|
|
Implement rolling-ball variable radius fillet along edges.
|
|||
|
|
Supports linear and cubic radius variation.
|
|||
|
|
|
|||
|
|
Closes #42
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 分支策略
|
|||
|
|
|
|||
|
|
- `main` — 稳定分支，只接受 PR
|
|||
|
|
- `feat/xxx` — 功能分支
|
|||
|
|
- `fix/xxx` — 修复分支
|
|||
|
|
- `docs/xxx` — 文档分支
|
|||
|
|
- `release/vX.Y` — 发布分支
|
|||
|
|
|
|||
|
|
## 6. Code Review 流程
|
|||
|
|
|
|||
|
|
1. **提交者**: 创建 PR，填写描述，关联 Issue
|
|||
|
|
2. **CI 检查**: 自动编译 + 测试必须通过
|
|||
|
|
3. **Reviewer**: 检查代码逻辑、风格、测试覆盖
|
|||
|
|
4. **迭代**: 根据反馈修改，`git commit --amend` + force push
|
|||
|
|
5. **合并**: Reviewer 批准后 squash merge
|
|||
|
|
|
|||
|
|
### Review 检查项
|
|||
|
|
|
|||
|
|
- [ ] 代码逻辑正确，无边界 bug
|
|||
|
|
- [ ] 命名清晰，符合规范
|
|||
|
|
- [ ] 公开 API 有 Doxygen 文档
|
|||
|
|
- [ ] 有对应的单元测试
|
|||
|
|
- [ ] 无编译警告（`-Wall -Wextra`）
|
|||
|
|
- [ ] 无内存泄漏（ASan 通过）
|
|||
|
|
- [ ] 性能不退化（benchmark 对比）
|
|||
|
|
|
|||
|
|
## 7. 测试要求
|
|||
|
|
|
|||
|
|
| 要求 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| 新功能 | 必须包含测试 |
|
|||
|
|
| Bug 修复 | 必须包含回归测试 |
|
|||
|
|
| 测试框架 | Google Test |
|
|||
|
|
| 覆盖率目标 | ≥ 80% 行覆盖 |
|
|||
|
|
| Sanitizer | 关键路径需通过 ASan/UBSan |
|
|||
|
|
|
|||
|
|
测试文件位置: `tests/<module>/test_<feature>.cpp`
|
|||
|
|
|
|||
|
|
详见 [测试指南](testing.md)。
|
|||
|
|
|
|||
|
|
## 8. 文档要求
|
|||
|
|
|
|||
|
|
| 变更类型 | 文档要求 |
|
|||
|
|
|---------|---------|
|
|||
|
|
| 新模块 | architecture.md 更新 + API 文档 + 教程 |
|
|||
|
|
| 新公开 API | Doxygen 注释 + API-REFERENCE 更新 |
|
|||
|
|
| 行为变更 | CHANGELOG 更新 |
|
|||
|
|
| 构建变更 | building.md 更新 |
|
|||
|
|
|
|||
|
|
## 联系方式
|
|||
|
|
|
|||
|
|
- Issue Tracker: Gitea Issues
|
|||
|
|
- 代码仓库: `ssh://git@localhost:22/hm/ViewDesignEngine.git`
|