茂之钳
486a0fe011
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.
352 lines
9.2 KiB
Markdown
352 lines
9.2 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 流程
|
||
|
||
### 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 流程
|
||
|
||
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`
|