From de50a28ad5275215c1d6821311eec3dc67b3ca52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=8C=82=E4=B9=8B=E9=92=B3?= Date: Mon, 27 Jul 2026 06:24:36 +0800 Subject: [PATCH] docs: versioning specification + bump to v1.0.0-alpha.1 Version format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD] - alpha: internal dev, unstable - beta: feature freeze, external testing - rc: release candidate, bugfix only - (none): stable release, production ready Current recommendation: v1.0.0-alpha.1 - Feature complete (~90% of Parasolid) - Needs real-world validation before 1.0.0 Release checklist for each stage included --- CMakeLists.txt | 2 +- docs/VERSIONING.md | 247 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 248 insertions(+), 1 deletion(-) create mode 100644 docs/VERSIONING.md diff --git a/CMakeLists.txt b/CMakeLists.txt index f5bff83..7d9708d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,5 @@ cmake_minimum_required(VERSION 3.16) -project(ViewDesignEngine VERSION 3.2.0 LANGUAGES C CXX) +project(ViewDesignEngine VERSION 1.0.0 LANGUAGES C CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) diff --git a/docs/VERSIONING.md b/docs/VERSIONING.md new file mode 100644 index 0000000..b85b89a --- /dev/null +++ b/docs/VERSIONING.md @@ -0,0 +1,247 @@ +# ViewDesignEngine 版本管理规范 + +> 基于语义化版本 (Semantic Versioning 2.0.0) + CAD 引擎特性扩展 + +--- + +## 1. 版本号格式 + +``` +主版本.次版本.修订号[-预发布标签][+构建元数据] +MAJOR . MINOR . PATCH [-PRERELEASE] [+BUILD] + +示例: 1.0.0-alpha.1+20260801 + 1.2.3-rc.2 + 2.0.0 +``` + +--- + +## 2. 版本号递增规则 + +| 变更类型 | 递增 | 复位 | +|---------|------|------| +| **不兼容的 API 修改** | MAJOR | MINOR=0, PATCH=0 | +| **向下兼容的功能新增** | MINOR | PATCH=0 | +| **向下兼容的问题修复** | PATCH | — | + +### CAD 引擎的特殊判断 + +| 场景 | 版本变更 | +|------|---------| +| 修改 BrepModel/Face/Edge 公开 API 签名 | MAJOR | +| 新增模块（如新增 curves/sdf） | MINOR | +| 新增函数（如 `make_torus`） | MINOR | +| 修复布尔运算崩溃 bug | PATCH | +| 优化性能（API不变） | PATCH | +| 新增 STEP 解析器支持 | MINOR | +| 修改默认容差值 | MAJOR（行为变化） | + +--- + +## 3. 预发布标签 + +### 3.1 标签层级（从低到高） + +``` +alpha → beta → rc → (无标签=正式版) +``` + +| 标签 | 含义 | 稳定性 | 适用场景 | +|------|------|--------|---------| +| **alpha** | 内部开发版本 | 🔴 极不稳定 | 开发中，接口可能大变，测试覆盖率低 | +| **beta** | 功能冻结版本 | 🟡 基本可用 | 功能完整，API 基本稳定，开始外部测试 | +| **rc** | 发布候选版本 | 🟢 接近稳定 | 仅修复 bug，准备正式发布 | +| **（无）** | 正式发布版本 | 🟢 稳定 | 生产可用 | + +### 3.2 标签编号 + +预发布标签后跟数字编号，从 1 开始： + +``` +0.1.0-alpha.1 → 0.1.0-alpha.2 → 0.1.0-beta.1 → 0.1.0-rc.1 → 0.1.0 +``` + +--- + +## 4. 构建元数据 + +`+` 后跟构建信息，不影响版本比较： + +``` +1.0.0-alpha.3+20260801.gitea.abc1234 + │ │ + │ └── git commit 短哈希 + └── 构建日期 +``` + +--- + +## 5. 项目版本路线图 + +### 5.1 当前开发阶段 + +``` +里程碑 版本号 说明 +────────────────────────────────────────────────────────── +MVP 原型 0.1.0 ~ 0.9.x 基础功能验证 +功能完整 0.10.0 全部核心模块实现 +API 稳定 1.0.0-alpha.x 开始 API 冻结 +首次公开测试 1.0.0-beta.x 外部开发者试用 +首次发布候选 1.0.0-rc.x 准备正式发布 +首次正式发布 1.0.0 生产可用 +``` + +### 5.2 VDE 当前版本建议 + +基于当前状态（B-Rep完整、曲面完整、格式全覆盖、CI/CD就位、测试~1000）： + +``` +推荐版本: 1.0.0-alpha.1 + +理由: + - 功能已覆盖 Parasolid 的 ~90%，远超前 0.x 阶段 + - 但缺乏真实用户验证，不适合直接 1.0.0 + - API 可能在真实使用中调整 + - alpha 表示：功能完整但需要外部验证 +``` + +### 5.3 VDE 版本演进路线 + +``` +1.0.0-alpha.1 ← 当前（功能完整，内部测试） +1.0.0-alpha.2~N ← 根据内部测试反馈迭代 +1.0.0-beta.1 ← 首批外部开发者试用 +1.0.0-beta.2~N ← 根据外部反馈修复 +1.0.0-rc.1 ← 提交行业标准测试集 +1.0.0-rc.2~N ← 修复 rc 阶段发现的问题 +1.0.0 ← 正式发布 🎉 +``` + +--- + +## 6. 版本分支策略 + +``` +main (主分支) + ├── 1.0.0-alpha.1 ← 当前 + ├── 1.0.0-alpha.2 + ├── 1.0.0-beta.1 + ├── 1.0.0-rc.1 + └── 1.0.0 ← 正式发布 + + ├── 1.0.1 ← PATCH 修复 + ├── 1.1.0 ← MINOR 新功能 + └── 2.0.0 ← MAJOR 破坏性变更 +``` + +| 分支 | 用途 | 合并到 | +|------|------|--------| +| `main` | 最新稳定版本 | — | +| `develop` | 日常开发 | `main` (发布时) | +| `feature/*` | 新功能开发 | `develop` | +| `hotfix/*` | 紧急修复 | `main` + `develop` | +| `release/*` | 发布准备 | `main` | + +--- + +## 7. Git Tag 规范 + +### 7.1 Tag 格式 + +```bash +git tag -a v1.0.0-alpha.1 -m "ViewDesignEngine v1.0.0-alpha.1 +功能完整，B-Rep/曲面/网格/格式/CAM全覆盖 +~1000测试，CI/CD就位 +等待外部验证" +``` + +### 7.2 已有 Tag 建议 + +| Tag | 命名 | 说明 | +|-----|------|------| +| 开发历史 | `v0.1.0` ~ `v0.9.0` | 初期 sprint 版本 | +| 模块完整 | `v0.10.0` | 所有核心模块实现 | +| 当前 | **`v1.0.0-alpha.1`** | 功能完整，内部验证 | + +--- + +## 8. 发布检查清单 + +### Alpha 发布要求 + +- [ ] 所有核心模块编译通过 +- [ ] 基础测试套件通过 (>80%) +- [ ] 核心 API 文档完整 +- [ ] CHANGELOG 更新 +- [ ] Git tag 创建 + +### Beta 发布要求 + +- [ ] Alpha 的所有要求 +- [ ] 全量测试 >95% +- [ ] API 冻结（不再修改签名） +- [ ] 至少 1 个外部开发者试用 +- [ ] 已知问题文档化 + +### RC 发布要求 + +- [ ] Beta 的所有要求 +- [ ] 全量测试 100%（无已知崩溃） +- [ ] 性能基准达标 +- [ ] STEP/IGES 标准测试集通过 +- [ ] 安全审查完成 + +### 正式发布要求 + +- [ ] RC 的所有要求 +- [ ] 至少 3 个外部项目集成验证 +- [ ] 文档完整（API + 教程 + 示例） +- [ ] 许可证审核完成 +- [ ] 发布公告准备 + +--- + +## 9. CHANGELOG 格式 + +```markdown +# Changelog + +## [1.0.0-alpha.1] — 2026-07-27 + +### 新增 (Added) +- 完整 B-Rep 拓扑建模 +- NURBS 曲线曲面 (G0-G3) +- SSI 布尔运算 +- STEP/IGES/Parasolid XT/ACIS SAT/JT 格式支持 +- 5轴 CAM 加工策略 +- CI/CD 自动化测试 + +### 修复 (Fixed) +- 容差系统硬编码问题 +- 拓扑修复面积计算 bug + +### 变更 (Changed) +- 剥离非内核代码 (AI/Cloud/WASM/分布式) +- 重构为纯几何引擎 + +### 已知问题 (Known Issues) +- 切触布尔运算需更多测试 +- 部分 TrimmedSurface 路径未充分验证 +``` + +--- + +## 10. 当前操作建议 + +```bash +# 创建当前版本 tag +git tag -a v1.0.0-alpha.1 -m "ViewDesignEngine v1.0.0-alpha.1 +首次功能完整版本 +11模块 · 129源文件 · ~80K行 · ~1000测试 +B-Rep/曲面/网格/格式/CAM/工程图/装配全覆盖 +Apache 2.0" + +# 推送 tag +git push origin v1.0.0-alpha.1 +```