MetonaTeam/DiffLens
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
6f7df57fba62d6512e368f0c927d2dc7243f896a
DiffLens/docs/应用开发与版本迭代规范.md
T

9.2 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.5.2

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.2.3   ← 安装器优化（已发布）：NSIS 向导式安装，支持手动选择安装目录
0.2.4   ← 健壮性与体验打磨（已发布）：读取容错与 10MB 大文件防护 · 横向滚动同步 · 下拉点击外部/Esc 关闭 · 二进制误判预警
0.2.5   ← 一致性与边角修复（已发布）：右键菜单边缘防溢出 · 粘贴入口 10MB 防护 · 拖拽读取失败提示 · 多文件拖拽提示 · 剪贴板统一走主进程 · 主进程异步读取
0.2.6   ← 主进程异步收尾与边角防护（已发布）：保存报告异步写盘 · 拖拽解码 handler 异步化 · 空白粘贴拦截 · 超多行卡顿预警 · 清理 mac 无效签名配置 · 文档与测试同步
0.3.0   ← 大文件性能与差异导航增强（已发布）：自研虚拟滚动 · 仅看差异过滤（折叠提示行） · F7/Shift+F7 导航快捷键 · 交换左右侧 · 忽略空行
0.3.1   ← 稳健性与测试补强（已发布）：超长单行词级 diff 防护 · 打开对话框补“所有文件”筛选 · 虚拟滚动 minWidth 测试覆盖 · 滚动同步去锁化重构
0.3.2   ← 报告对齐与性能收尾（已发布）：纯文本报告行号右对齐 · 超长行列宽封顶防卡顿 · 对话框与拖拽扩展名清单对齐 · 右键菜单打开时导航快捷键守卫 · 清理导出死属性
0.4.0   ← 差异计算 worker 化（已发布）：大文件 diff 移入 Worker 后台计算不阻塞界面 · 输入去抖与过期任务丢弃（终止重建实现取消） · 小输入同步快路径 · 无 Worker 环境回退 · 计算中遮罩与导出禁用
0.4.1   ← worker 创建开销优化与文档对齐（已发布）：worker 延迟至去抖到期才创建（去抖期内取消零创建开销，无 Worker 回退同样走去抖） · 质量门禁文档补 npm test · README 架构树补 hooks · Markdown 报告标题移出引用块 · 安装包排除开发期文件
0.4.2   ← 导出菜单溢出修复与报告可读性重设计（已发布）：底部工具栏导出菜单改向上弹出（修复超出窗口底边选不到） · HTML 报告全新设计（Hero 概览/人话结论/文件卡片/统计卡/图例/差异分块目录/相同段折叠可展开/打印亮色/窄屏适配，零 JS） · TXT 与 Markdown 报告头部补人话结论
0.4.3   ← 忽略所有空白比较选项与报告选项说明（已发布）：新增“忽略所有空白”开关（行内空格/制表符/全角空格不参与判等，展示仍为原文，换行结构仍参与对比） · 三种报告头部新增“比较选项”说明行（HTML 为 Hero 区徽标）
0.5.0   ← 字符级对比模式（已发布）：新增“字符级对比”开关（空白与换行结构全部不参与判等，两侧归一化为字符流 diff，跨行重组也能判等） · 字符差异回映射到行（跨界行配对、单侧行回拉、锚行 zip 配对，输出仍为 DiffRow，视图/报告/导航零改动） · 归一化流超 20 万字符自动降级行级对比并提示（报告头部按实际语义描述） · 字符级开启时三个空白选项置灰（语义已包含）
0.5.1   ← 字符级同行多块变更重复输出修复（已发布）：字符换位专项测试暴露并修复两处回映射缺陷——同行内多处变更（ne-eq-ne 同行，如换位、同行两处替换）不再重复输出多个 modified · 回拉跨界判定与对齐行判定锚定同一 eq 块，多行换位不再把全 common 行误判为 added · 新增字符换位专项测试组（对齐任意性下的不变量固化）
0.5.2   ← 稳健性收尾与偏好记忆（当前）：diff worker 运行崩溃 onerror 兜底（终止实例回退主线程同步计算，effect 取消/jobId 已推进的迟到错误不回填） · 主进程 will-navigate 导航白名单加固（仅放行回到应用首页） · nativeTheme 暗色主题（Windows 标题栏等系统控件跟随应用风格） · 比较选项与仅看差异开关持久化（localStorage 记忆用户偏好，损坏数据防御性回退默认） · 字符级降级报告选项构造与引擎降级分支对齐（补 trimWhitespace 置否）
0.6.0   ← 新增功能（候选：主进程解码 worker 化 · Playwright E2E · 文件夹对比）
...
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. 质量门禁（提交/推送前必须通过）

每次提交与推送前执行：

npm run typecheck   # 类型检查（node + web 双端）
npm test            # Vitest 单元 + 组件测试（覆盖率 80% 硬门禁）
npm run build       # 生产构建（main/preload/renderer 三端）

任一命令失败则禁止提交；修复通过后再提交。与《测试策略与方案》第 7 节保持一致。

8. 发布流程

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
README.md 特性描述与发布版本号随版本同步
本文件 第 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 View Git Blame Copy Permalink