MetonaTeam/DiffLens

Fork 0

Files

T

thzxx f5aefbbe00 feat: v0.2.2 体验打磨 - 拖拽处处可用、手动粘贴对比、仅限文本文件、报告与可读性增强

2026-08-17 18:38:37 +08:00

4.9 KiB

Raw Blame History

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   ← 体验打磨补丁（已发布）：拖拽编码识别 · 行级右键菜单 · 尾部换行显示修正
0.2.0   ← 导出差异报告（已发布）：HTML / 纯文本 / Markdown 三种格式
0.2.1   ← 建立测试体系（已发布）：Vitest 单元+组件测试 · 测试策略文档
0.2.2   ← 体验打磨（当前）：拖拽处处可用 · 手动粘贴对比 · 导出后一键定位 · 报告/可读性增强 · 仅限文本文件
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. 开发流程

需求确认 → 方案权衡 → 开发实现 → 本地自测 → 类型检查 → 生产构建 → 代码评审 → 合并 → 发布

需求确认：明确目标，先梳理全貌，避免返工
方案权衡：涉及取舍时列出利弊，由负责拍板
开发实现：聚焦需求本身，不过度设计
本地自测：npm run dev 运行验证
质量门禁：见第 7 节
发布：见第 8 节

6. 分支与合并规范

main：唯一稳定主干，始终可运行、可发布
功能分支：feature/<功能名>
修复分支：fix/<问题描述>

main
 └─ feature/xxx  → （评审后合并回 main）

合并且无二次改动时，才允许 rebase 保持历史整洁；否则用普通合并提交。

7. 质量门禁（提交/推送前必须通过）

每次提交与推送前执行：

npm run typecheck   # 类型检查（node + web 双端）
npm run build       # 生产构建（main/preload/renderer 三端）

任一命令失败则禁止提交；修复通过后再提交。

8. 发布流程

npm run build:win   # Windows NSIS 安装包（在 Windows 上）

发布前 checklist：

更新 package.json 的 version 到新的 0.y.z
更新本文件第 3 节演进记录
通过质量门禁（typecheck + build）
打标签并推送到远程 git.metona.cn/MetonaTeam/DiffLens
如需发布安装包，生成对应平台产物与 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

4.9 KiB Raw Blame History Unescape Escape