docs: 新增应用开发与版本迭代规范
This commit is contained in:
@@ -0,0 +1,174 @@
|
||||
# DiffLens 应用开发与版本迭代规范
|
||||
|
||||
> 适用项目：DiffLens（MetonaTeam / thzxx）
|
||||
> 文档维护：随应用版本同步更新
|
||||
|
||||
---
|
||||
|
||||
## 1. 版本号总规范
|
||||
|
||||
版本号遵循 **语义化版本（SemVer）三段式**：`x.y.z`
|
||||
|
||||
```
|
||||
x = 主版本号（Major）
|
||||
y = 次版本号（Minor）
|
||||
z = 补丁版本号（Patch）
|
||||
```
|
||||
|
||||
**本项目最重要的约束：**
|
||||
|
||||
> **`x` 永远是 `0`，永远不要提升到 `1.0.0`。**
|
||||
> 版本迭代**只允许修改 `y` 和 `z`**，`x` 保持 `0` 不变。
|
||||
|
||||
当前基线版本：**`0.1.0`**
|
||||
|
||||
---
|
||||
|
||||
## 2. x / y / z 各自的含义与规则
|
||||
|
||||
| 段位 | 值 | 何时提升 | 举例 |
|
||||
| --- | --- | --- | --- |
|
||||
| `x` 主版本 | **恒为 `0`** | 永不提升 | 不生效 |
|
||||
| `y` 次版本 | `0, 1, 2, 3 …` | 新增功能 / 界面较大调整 / 构建方式变更 | `0.1.0 → 0.2.0` |
|
||||
| `z` 补丁 | `0, 1, 2, 3 …` | Bug 修复 / 样式微调 / 文档 / 依赖小升级 | `0.1.0 → 0.1.1` |
|
||||
|
||||
### 何时走 `y`（次版本升级 `0.x.z → 0.(x+1).0`）
|
||||
- 新增用户可见的功能特性
|
||||
- UI / 交互有较大调整
|
||||
- 引入新的差异能力（如导出报告、文件夹对比）
|
||||
- 内部引擎算法 / 数据结构的兼容性变更
|
||||
|
||||
### 何时走 `z`（补丁升级 `0.x.z → 0.x.(z+1)`）
|
||||
- 修复 Bug、崩溃、显示异常
|
||||
- 细微的样式 / 文案优化
|
||||
- 文档补充、依赖补丁级升级
|
||||
- 非功能性重构（不改变用户可见行为）
|
||||
|
||||
### 反例（禁止）
|
||||
- ❌ 直接跳到 `1.0.0` 或更高
|
||||
- ❌ 只升 `x` 不升 `y/z`
|
||||
- ❌ 同时改 `y` 与 `z`（一次发布只应改动一段）
|
||||
|
||||
---
|
||||
|
||||
## 3. 版本演进示意
|
||||
|
||||
```
|
||||
0.1.0 ← 初始版本（当前）
|
||||
0.1.1 ← 修复 Bug
|
||||
0.2.0 ← 新增功能
|
||||
0.2.1 ← 修复该版本 Bug
|
||||
0.3.0 ← 新增功能
|
||||
...
|
||||
0.y.z ← 长期停留，永不进入 1.x
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 应用命名约束（三重一致）
|
||||
|
||||
交付给用户的所有可见名称必须统一为 **DiffLens**：
|
||||
|
||||
| 环节 | 名称 |
|
||||
| --- | --- |
|
||||
| 安装包文件名 | `DiffLens-{version}-setup.exe` |
|
||||
| 安装后主程序 | `DiffLens.exe` |
|
||||
| 开始菜单 / 桌面快捷方式 | `DiffLens` |
|
||||
| 窗口标题 | `DiffLens` |
|
||||
| 工程内部 name / productName | `DiffLens` |
|
||||
|
||||
> 注：`appId` 为内部安装标识（如 `com.metonateam.difflens`），不展示给用户，不受此约束。
|
||||
|
||||
---
|
||||
|
||||
## 5. 开发流程
|
||||
|
||||
```
|
||||
需求确认 → 方案权衡 → 开发实现 → 本地自测 → 类型检查 → 生产构建 → 代码评审 → 合并 → 发布
|
||||
```
|
||||
|
||||
1. **需求确认**：明确目标，先梳理全貌，避免返工
|
||||
2. **方案权衡**：涉及取舍时列出利弊，由负责拍板
|
||||
3. **开发实现**：聚焦需求本身，不过度设计
|
||||
4. **本地自测**：`npm run dev` 运行验证
|
||||
5. **质量门禁**：见第 7 节
|
||||
6. **发布**：见第 8 节
|
||||
|
||||
---
|
||||
|
||||
## 6. 分支与合并规范
|
||||
|
||||
- `main`：唯一稳定主干，始终可运行、可发布
|
||||
- 功能分支：`feature/<功能名>`
|
||||
- 修复分支：`fix/<问题描述>`
|
||||
|
||||
```
|
||||
main
|
||||
└─ feature/xxx → （评审后合并回 main）
|
||||
```
|
||||
|
||||
合并且无二次改动时，才允许 rebase 保持历史整洁；否则用普通合并提交。
|
||||
|
||||
---
|
||||
|
||||
## 7. 质量门禁（提交/推送前必须通过）
|
||||
|
||||
每次提交与推送前执行：
|
||||
|
||||
```bash
|
||||
npm run typecheck # 类型检查（node + web 双端）
|
||||
npm run build # 生产构建（main/preload/renderer 三端）
|
||||
```
|
||||
|
||||
> 任一命令失败则禁止提交；修复通过后再提交。
|
||||
|
||||
---
|
||||
|
||||
## 8. 发布流程
|
||||
|
||||
```bash
|
||||
npm run build:win # Windows NSIS 安装包（在 Windows 上）
|
||||
```
|
||||
|
||||
发布前 checklist：
|
||||
1. 更新 `package.json` 的 `version` 到新的 `0.y.z`
|
||||
2. 更新本文件第 3 节演进记录
|
||||
3. 通过质量门禁（typecheck + build）
|
||||
4. 打标签并推送到远程 `git.metona.cn/MetonaTeam/DiffLens`
|
||||
5. 如需发布安装包，生成对应平台产物与 Release 说明
|
||||
|
||||
---
|
||||
|
||||
## 9. 元信息维护表
|
||||
|
||||
| 文件 | 维护内容 |
|
||||
| --- | --- |
|
||||
| `package.json` | `version`（唯一版本来源）、`name`、`productName` 保持 DiffLens |
|
||||
| `electron-builder.yml` | `productName` / `executableName` / `artifactName` 保持 DiffLens |
|
||||
| 本文件 | 第 3 节演进记录同步补写 |
|
||||
|
||||
> 版本号**只以 `package.json` 的 `version` 为唯一来源**，其余打包产物名由它派生。
|
||||
|
||||
---
|
||||
|
||||
## 附：提交信息格式
|
||||
|
||||
采用约定式提交：
|
||||
|
||||
```
|
||||
<type>: <描述>
|
||||
|
||||
feat: 新增功能 （配 y 版本）
|
||||
fix: 修复问题 （配 z 版本）
|
||||
docs: 文档变更
|
||||
build: 构建/依赖
|
||||
refactor: 重构（不改行为，配 z 版本）
|
||||
```
|
||||
|
||||
例如：
|
||||
- `feat: 新增导出差异报告` → `0.2.0`
|
||||
- `fix: 修复 GBK 文件乱码` → `0.1.1`
|
||||
|
||||
---
|
||||
|
||||
© 2026 MetonaTeam · thzxx · DiffLens
|
||||
Reference in New Issue
Block a user