This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
贡献指南
感谢你对 ViewDesignEngine 的关注！本文档说明如何参与 VDE 开发。
目录
1. 行为准则
- 尊重所有贡献者，建设性沟通
- 关注代码质量而非个人
- 接受建设性批评，乐于改进
- 帮助新人融入项目
2. 如何贡献
| 贡献方式 | 说明 |
|---|---|
| Bug 报告 | 通过 Issue 提交，附重现步骤 |
| 功能请求 | 先开 Issue 讨论，获得认同后再实现 |
| 代码贡献 | Fork → Branch → PR → Review → Merge |
| 文档改进 | 直接提 PR 修正文档错误 |
| 测试补充 | 新增测试用例，提高覆盖率 |
| 插件开发 | 按 插件系统设计 开发第三方插件 |
贡献流程
# 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 环境（推荐）
# 构建 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)
本地环境
# 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 |
文件组织
// 头文件示例
#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— 稳定分支，只接受 PRfeat/xxx— 功能分支fix/xxx— 修复分支docs/xxx— 文档分支release/vX.Y— 发布分支
6. Code Review 流程
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 描述模板
## 变更概述
<!-- 用一两句话描述这个 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历史整洁 - 合并条件：
- CI 全部通过（编译 + 测试 + clang-tidy + ASan）
- 至少 1 名 Reviewer 批准
- 无未解决的 Review 意见
- 分支与 main 无冲突（rebase 解决）
6.2 Code Review 流程
- 提交者: 创建 PR，填写描述，关联 Issue
- CI 检查: 自动编译 + 测试必须通过
- Reviewer: 检查代码逻辑、风格、测试覆盖
- 迭代: 根据反馈修改，
git commit --amend+ force push - 合并: Reviewer 批准后 squash merge
Review 检查项
- 代码逻辑正确，无边界 bug
- 命名清晰，符合规范
- 公开 API 有 Doxygen 文档
- 有对应的单元测试
- 无编译警告（
-Wall -Wextra） - 无内存泄漏（ASan 通过）
- 性能不退化（benchmark 对比）
7. 测试要求
| 要求 | 说明 |
|---|---|
| 新功能 | 必须包含测试 |
| Bug 修复 | 必须包含回归测试 |
| 测试框架 | Google Test |
| 覆盖率目标 | ≥ 80% 行覆盖 |
| Sanitizer | 关键路径需通过 ASan/UBSan |
测试文件位置: tests/<module>/test_<feature>.cpp
详见 测试指南。
8. 文档要求
| 变更类型 | 文档要求 |
|---|---|
| 新模块 | architecture.md 更新 + API 文档 + 教程 |
| 新公开 API | Doxygen 注释 + API-REFERENCE 更新 |
| 行为变更 | CHANGELOG 更新 |
| 构建变更 | building.md 更新 |
联系方式
- Issue Tracker: Gitea Issues
- 代码仓库:
ssh://git@localhost:22/hm/ViewDesignEngine.git