# 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
```