From f5da68e62404ba9c4a74a3c4a6e4bcd00ec95cb3 Mon Sep 17 00:00:00 2001 From: thzxx <1440196015@qq.com> Date: Mon, 17 Aug 2026 16:41:35 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=BA=94=E7=94=A8?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E4=B8=8E=E7=89=88=E6=9C=AC=E8=BF=AD=E4=BB=A3?= =?UTF-8?q?=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/应用开发与版本迭代规范.md | 174 +++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 docs/应用开发与版本迭代规范.md diff --git a/docs/应用开发与版本迭代规范.md b/docs/应用开发与版本迭代规范.md new file mode 100644 index 0000000..11136a0 --- /dev/null +++ b/docs/应用开发与版本迭代规范.md @@ -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` 为唯一来源**，其余打包产物名由它派生。 + +--- + +## 附：提交信息格式 + +采用约定式提交： + +``` +: <描述> + +feat: 新增功能 （配 y 版本） +fix: 修复问题 （配 z 版本） +docs: 文档变更 +build: 构建/依赖 +refactor: 重构（不改行为，配 z 版本） +``` + +例如： +- `feat: 新增导出差异报告` → `0.2.0` +- `fix: 修复 GBK 文件乱码` → `0.1.1` + +--- + +© 2026 MetonaTeam · thzxx · DiffLens \ No newline at end of file