u-desk/docs/07-项目管理/版本管理/版本发布手册.md

# 版本发布手册

> 项目：u-desk
> 最后更新：2026-02-04

## 目的

规范版本发布流程，确保版本号一致性和发布质量。

## 发布前准备

### 1. 版本迭代信息核对

在更新版本号之前，先核对自上一个版本以来的所有变更。

#### 1.1 查看现有版本标签

```bash
# 列出所有版本标签
git tag -l

# 查看最新标签
git describe --tags --abbrev=0
```

#### 1.2 分析版本间差异

```bash
# 查看上一个版本到当前的所有提交
git log v0.2.0..HEAD --oneline

# 查看提交标题（用于生成发布说明）
git log v0.2.0..HEAD --pretty=format:"%s" --no-merges

# 查看变更统计
git diff v0.2.0..HEAD --stat

# 查看总体变更行数
git diff v0.2.0..HEAD --stat | tail -1
```

**输出示例**：
```
a5d3068 重构：文件系统模块化架构，增强 Markdown 渲染
eb2cbad 优化：代码质量提升，修复重复逻辑和语法高亮支持

130 files changed, 11636 insertions(+), 12233 deletions(-)
```

#### 1.3 查看详细变更

```bash
# 查看具体文件变更
git diff v0.2.0..HEAD --name-only

# 查看新增文件
git diff v0.2.0..HEAD --name-only --diff-filter=A

# 查看删除文件
git diff v0.2.0..HEAD --name-only --diff-filter=D

# 查看修改文件
git diff v0.2.0..HEAD --name-only --diff-filter=M
```

#### 1.4 生成版本发布说明

根据上述分析，创建版本发布说明文档：

```bash
# 创建发布说明文档
mkdir -p docs/项目管理/版本发布
vim "docs/项目管理/版本发布/v0.2.1-发布说明.md"
```

**发布说明模板**：

```markdown
# 版本发布说明 v0.2.1

**发布日期**：YYYY-MM-DD
**Git 标签**：v0.2.1
**上一个版本**：v0.2.0

## 变更统计

- **文件变更**：X 个文件
- **代码行数**：+X / -X
- **提交次数**：X 次

## 主要更新

### 🎯 核心功能
- 功能点1
- 功能点2

### 🔧 技术改进
- 改进点1
- 改进点2

### 🐛 问题修复
- 修复1
- 修复2

## 升级指南
...（略）

## 已知问题
...（略）
```

### 2. 功能检查清单

- [ ] 所有计划功能已实现
- [ ] 核心功能测试通过
- [ ] 关键 bug 已修复
- [ ] 代码已通过 review

### 3. 版本号确定

版本号遵循语义化版本规范（Semantic Versioning）：`主版本.次版本.修订号`

- **主版本**：不兼容的 API 修改
- **次版本**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

## 发布流程

### 步骤 1：更新代码版本号

#### 1.1 更新 `wails.json`

```bash
# 文件位置：项目根目录/wails.json
# 修改 version 字段
```

**示例**：
```json
{
  "name": "u-desk",
  "version": "0.2.1",  // 修改此处
  ...
}
```

#### 1.2 更新 `internal/service/version.go`

```bash
# 文件位置：internal/service/version.go
# 修改 AppVersion 常量
```

**示例**：
```go
// AppVersion 应用版本号（发布时直接修改此处）
const AppVersion = "0.2.1"  // 修改此处
```

### 步骤 2：更新文档版本号

需要更新以下文档中的版本引用：

```bash
# 批量替换（使用 sed 或手动修改）
docs/功能清单.md
docs/功能清单核对报告.md
docs/时间修正记录.md
docs/项目管理/PROJECT_STATUS.md
docs/项目管理/README.md
```

**替换内容**：
- `v0.2.0` → `v0.2.1`

### 步骤 3：代码检查

```bash
# 检查是否有未提交的更改
git status

# 确认所有文件已正确更新
git diff
```

### 步骤 4：提交版本更改

```bash
# 添加所有更改
git add -A

# 提交（使用明确的提交信息）
git commit -m "发布：版本 0.2.1"
```

**提交信息格式**：
```
发布：版本 x.y.z

- 主要变更点1
- 主要变更点2
- 主要变更点3
```

### 步骤 5：创建版本标签

```bash
# 创建带注释的标签
git tag -a v0.2.1 -m "版本 0.2.1

主要更新：
- 文件系统模块化架构
- Markdown Mermaid 图表支持
- 代码语法高亮
- 主题适配优化"
```

### 步骤 6：验证标签

```bash
# 查看所有标签
git tag -l

# 查看标签详情
git show v0.2.1
```

### 步骤 7：推送到远程（可选）

```bash
# 推送提交
git push origin main

# 推送标签
git push origin v0.2.1
```

## 版本发布后

### 1. 保存版本发布说明

将步骤 1.4 中创建的版本发布说明文档提交到仓库：

```bash
# 检查发布说明文档
git add "docs/项目管理/版本发布/v0.2.1-发布说明.md"

# 单独提交发布说明
git commit -m "文档：版本 0.2.1 发布说明"
```

或者在提交版本更改时一起提交（推荐）：

```bash
# 步骤 4 中一起提交
git add -A
git commit -m "发布：版本 0.2.1

- 包含版本发布说明文档
- 代码版本号已更新
- 文档版本号已更新"
```

### 2. 更新 CHANGELOG

创建或更新 `CHANGELOG.md`，记录本版本的变更：

```markdown
## [0.2.1] - 2026-02-04

### 新增
- Markdown Mermaid 图表渲染支持
- 180+ 编程语言语法高亮
- 文件系统模块化架构

### 修复
- 编辑/预览模式切换时 Mermaid 渲染问题
- 亮色/暗色模式主题适配

### 优化
- 代码结构优化，使用 CSS 变量管理主题色
```

### 3. 构建发布版本

```bash
# Wails 构建
wails build

# 构建产物位置
# Windows: build/bin/u-desk.exe
```

### 4. 测试发布版本

- [ ] 安装测试
- [ ] 核心功能验证
- [ ] 版本号显示检查

## 检查清单

### 发布前
- [ ] 版本号已更新（代码 + 文档）
- [ ] 提交信息清晰准确
- [ ] Git 标签已创建
- [ ] 标签注释完整

### 发布后
- [ ] CHANGELOG 已更新
- [ ] 构建成功
- [ ] 测试通过
- [ ] 标签已推送（如需远程发布）

## 常见问题

### Q: 忘记更新某个文件的版本号怎么办？

**A**: 可以修改后重新提交，然后删除旧标签并重新创建：

```bash
# 删除本地标签
git tag -d v0.2.1

# 删除远程标签（如已推送）
git push origin :refs/tags/v0.2.1

# 重新创建标签
git tag -a v0.2.1 -m "版本 0.2.1"

# 推送新标签
git push origin v0.2.1
```

### Q: 如何查看某个版本的差异？

**A**: 使用 git diff 命令：

```bash
# 查看两个标签之间的差异
git diff v0.2.0 v0.2.1

# 查看标签与当前的差异
git diff v0.2.1 HEAD
```

## 参考资源

- [语义化版本规范](https://semver.org/lang/zh-CN/)
- [Git 标签管理](https://git-scm.com/book/zh/v2/Git-%E5%9F%BA%E7%A1%80-%E6%89%93%E6%A0%87%E7%AD%BE)

## 附录：完整发布脚本示例

```bash
#!/bin/bash
# 版本发布脚本

VERSION="0.2.1"

echo "开始准备发布版本 $VERSION"

# 1. 更新 wails.json
sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/g" wails.json

# 2. 更新 version.go
sed -i "s/const AppVersion = \".*\"/const AppVersion = \"$VERSION\"/g" internal/service/version.go

# 3. 更新文档
sed -i "s/v0\.2\.0/v$VERSION/g" docs/功能清单.md
sed -i "s/v0\.2\.0/v$VERSION/g" docs/功能清单核对报告.md
sed -i "s/v0\.2\.0/v$VERSION/g" docs/时间修正记录.md
sed -i "s/v0\.2\.0/v$VERSION/g" docs/项目管理/PROJECT_STATUS.md
sed -i "s/v0\.2\.0/v$VERSION/g" docs/项目管理/README.md

# 4. 提交更改
git add -A
git commit -m "发布：版本 $VERSION"

# 5. 创建标签
git tag -a "v$VERSION" -m "版本 $VERSION"

echo "版本 $VERSION 准备完成！"
echo "请检查更改并推送："
echo "  git push origin main"
echo "  git push origin v$VERSION"
```

使用方法：
```bash
chmod +x scripts/release.sh
./scripts/release.sh
```