hm/ViewDesignEngine

Fork 0

Files

T

茂之钳 486a0fe011

CI / Build & Test (push) Failing after 35s

Details

CI / Release Build (push) Failing after 33s

Details

Build & Test / build-and-test (push) Has been cancelled

Details

Build & Test / python-bindings (push) Has been cancelled

Details

docs: reorganize documentation — developer-friendly structure

New structure:
- docs/index.md — main navigation
- docs/getting-started.md — 5-minute quick start
- docs/guides/module-manual.md — all 11 modules with file listing
- docs/guides/api-usage.md — API reference with code examples
- docs/guides/ — architecture, building, testing, contributing
- docs/reference/ — competitive analysis, gap analysis, versioning
- docs/api/ — Doxygen generated HTML
- docs/archive/ — historical development plans

Old development plans archived. Clean 4-directory layout.

2026-07-27 13:32:20 +08:00

9.2 KiB

Raw Blame History

贡献指南

感谢你对 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 — 稳定分支，只接受 PR
feat/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

9.2 KiB Raw Blame History Unescape Escape

贡献指南

目录

1. 行为准则

2. 如何贡献

贡献流程

3. 开发环境搭建

前提条件

Docker 环境（推荐）

本地环境

4. 代码规范

命名规范

文件组织

编码风格

禁止事项

5. 提交规范

提交消息格式

分支策略

6. Code Review 流程

6.1 Pull Request 规范

PR 标题格式

PR 描述模板

PR 分支命名

PR 生命周期

PR 大小限制

合并策略

6.2 Code Review 流程

Review 检查项

7. 测试要求

8. 文档要求

联系方式

9.2 KiB

Raw Blame History