# 贡献指南感谢你对 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 // 公开依赖 #include // 标准库 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& vertex_ids); private: // 成员变量 std::vector 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. 提交规范 ### 提交消息格式 ``` ():