ViewDesignEngine/docs/VERSIONING.md

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 格式

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 格式

# 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. 当前操作建议

# 创建当前版本 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