hm/ViewDesignEngine
1
0
Fork 0
Code Issues Pull Requests Actions 58 Packages Projects Releases 1 Wiki Activity
Files
c021855597055f49265d8dbefc4bf1e06f07f502
ViewDesignEngine/docs/guides/contributing.md
T

352 lines
9.2 KiB
Markdown
Raw Normal View History

feat(v6.2): Blender addon + .NET/C# bindings + developer docs + plugin system
2026-07-26 22:24:40 +08:00
# 贡献指南
感谢你对 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 流程
feat(v11): CI/CD + regression tests + fuzzing + benchmarks + code quality
2026-07-27 01:10:58 +08:00
### 6.1 Pull Request 规范
所有代码变更必须通过 PR (Pull Request) 提交至 `main` 分支。PR 审核通过后方可合并。
#### PR 标题格式
```
<type>(<scope>): <简短描述>
# 示例
feat(brep): 添加变径圆角支持
fix(mesh): 修复 Delaunay 3D 退化四面体崩溃
docs(api): 更新 B-Rep 模块 API 文档
refactor(core): 将 Polygon2D 迁移到 SoA 布局
test(sdf): 增加 SDF 梯度计算精度测试
perf(spatial): BVH SAH 构建改用 OpenMP 并行化
```
#### PR 描述模板
```markdown
## 变更概述
<!-- 用一两句话描述这个 PR 做了什么 -->
## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 重构
- [ ] 性能优化
- [ ] 文档
- [ ] 测试
- [ ] CI/构建
## 关联 Issue
Closes #
## 测试计划
- [ ] 新增测试用例 N 个
- [ ] 已有测试全部通过
- [ ] ASan/UBSan 通过
- [ ] 性能基准无退化
## 影响范围
<!-- 变更影响了哪些模块/API -->
## 截图/日志（如适用）
## Checklist
- [ ] 代码符合 [代码规范](contributing.md#4-代码规范)
- [ ] 通过了 `cmake --build build -j$(nproc)` 零错误零警告
- [ ] 新公开 API 有 Doxygen 注释
- [ ] CHANGELOG 已更新
- [ ] 文档已更新（如有必要）
```
#### PR 分支命名
| 前缀 | 用途 | 示例 |
|------|------|------|
| `feat/` | 新功能 | `feat/variable-radius-fillet` |
| `fix/` | Bug 修复 | `fix/delaunay-degenerate-tet` |
| `refactor/` | 重构 | `refactor/polygon-soa-layout` |
| `perf/` | 性能优化 | `perf/bvh-sah-openmp` |
| `docs/` | 文档 | `docs/api-reference-update` |
| `test/` | 测试补充 | `test/sdf-gradient-precision` |
| `ci/` | CI/构建 | `ci/add-clang-tidy-check` |
| `release/` | 发布准备 | `release/v5.5.0` |
#### PR 生命周期
```
创建 PR → CI 自动检查 → Reviewer 审核 → 修改迭代 → 批准 → Squash Merge
│ │ │ │ │ │
│ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │ ┌────┴────┐
│ │编译测试 │ │代码逻辑 │ │force push│ │ │单 commit│
│ │clang-tidy│ │风格规范 │ │amend │ │ │合入 main│
│ │ASan/UBSan│ │测试覆盖 │ │rebase │ │ │删除分支 │
│ └─────────┘ └─────────┘ └─────────┘ │ └─────────┘
└── 每个 PR 一个分支，从 main 最新 commit 分出
```
#### PR 大小限制
| 类型 | 建议行数 | 审核时间 |
|------|:------:|:------:|
| 小型 PR | < 200 行 | 1 天内 |
| 中型 PR | 200–800 行 | 1–3 天 |
| 大型 PR | > 800 行 | 需拆分提交 |
> 大型功能应拆分为多个小型 PR，每个 PR 独立可测试、可合并。禁止一次提交多个不相关功能。
#### 合并策略
- **Squash Merge**：所有 commit 合并为一个，保持 `main` 历史整洁
- **合并条件**：
- [x] CI 全部通过（编译 + 测试 + clang-tidy + ASan）
- [x] 至少 1 名 Reviewer 批准
- [x] 无未解决的 Review 意见
- [x] 分支与 main 无冲突（rebase 解决）
### 6.2 Code Review 流程
feat(v6.2): Blender addon + .NET/C# bindings + developer docs + plugin system
2026-07-26 22:24:40 +08:00
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`
Reference in New Issue Copy Permalink