hm/ViewDesignEngine
1
0
Fork 0
Code Issues Pull Requests Actions 54 Packages Projects Releases 1 Wiki Activity
Files
5e2812a6f3346f8744a31dd1fb0cc09e9fd30c79
ViewDesignEngine/docs/dev-guide/contributing.md
T
茂之钳 5e2812a6f3
CI / Build & Test (push) Failing after 33s
Details
CI / Release Build (push) Failing after 35s
Details
Build & Test / build-and-test (push) Has been cancelled
Details
Build & Test / python-bindings (push) Has been cancelled
Details
feat(v6.2): Blender addon + .NET/C# bindings + developer docs + plugin system 
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)
2026-07-26 22:24:40 +08:00

5.9 KiB
Raw Blame History

贡献指南

感谢你对 ViewDesignEngine 的关注！本文档说明如何参与 VDE 开发。

目录

  1. 行为准则
  2. 如何贡献
  3. 开发环境搭建
  4. 代码规范
  5. 提交规范
  6. Code Review 流程
  7. 测试要求
  8. 文档要求

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 — 稳定分支，只接受 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

详见 测试指南。

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 View Git Blame Copy Permalink