茂之钳
5e2812a6f3
v6.2.1 — Blender Integration Addon: - 5 files, 1,732 lines: __init__, operators (9 ops), panels (4 panels) - preferences, vde_bridge (subprocess CLI bridge) - Import/Export STEP, primitives, boolean, SDF→Mesh v6.2.2 — .NET/C# Bindings (VdeSharp): - 8 files: NativeMethods (50+ P/Invoke), BrepModel, MeshData, SdfEngine, Assembly - C API extended with 20 new functions (STEP I/O, Boolean, SDF, Assembly) - vde_capi rebuilt as SHARED library - Example: import STEP → boolean → export v6.2.3 — Developer Docs + Plugin System: - 7 docs: architecture, contributing, API overview, building, testing, plugin-system - plugin_system.h/.cpp: PluginInterface, PluginManager, dlopen/LoadLibrary - README.md updated with v6 features - Syntax-check passed (GCC 10.2.1, -Wall -Wextra -Wpedantic)
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`
|