茂之钳
de50a28ad5
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
248 lines
6.2 KiB
Markdown
248 lines
6.2 KiB
Markdown
# 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
|
||
```
|