7.3 KiB
7.3 KiB
版本发布手册
项目：u-desk 最后更新：2026-02-04
目的
规范版本发布流程，确保版本号一致性和发布质量。
发布前准备
1. 版本迭代信息核对
在更新版本号之前，先核对自上一个版本以来的所有变更。
1.1 查看现有版本标签
# 列出所有版本标签
git tag -l
# 查看最新标签
git describe --tags --abbrev=0
1.2 分析版本间差异
# 查看上一个版本到当前的所有提交
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 查看详细变更
# 查看具体文件变更
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 生成版本发布说明
根据上述分析，创建版本发布说明文档：
# 创建发布说明文档
mkdir -p docs/项目管理/版本发布
vim "docs/项目管理/版本发布/v0.2.1-发布说明.md"
发布说明模板：
# 版本发布说明 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
# 文件位置：项目根目录/wails.json
# 修改 version 字段
示例：
{
"name": "u-desk",
"version": "0.2.1", // 修改此处
...
}
1.2 更新 internal/service/version.go
# 文件位置：internal/service/version.go
# 修改 AppVersion 常量
示例：
// AppVersion 应用版本号（发布时直接修改此处）
const AppVersion = "0.2.1" // 修改此处
步骤 2：更新文档版本号
需要更新以下文档中的版本引用：
# 批量替换（使用 sed 或手动修改）
docs/功能清单.md
docs/功能清单核对报告.md
docs/时间修正记录.md
docs/项目管理/PROJECT_STATUS.md
docs/项目管理/README.md
替换内容：
v0.2.0→v0.2.1
步骤 3：代码检查
# 检查是否有未提交的更改
git status
# 确认所有文件已正确更新
git diff
步骤 4：提交版本更改
# 添加所有更改
git add -A
# 提交（使用明确的提交信息）
git commit -m "发布：版本 0.2.1"
提交信息格式：
发布：版本 x.y.z
- 主要变更点1
- 主要变更点2
- 主要变更点3
步骤 5：创建版本标签
# 创建带注释的标签
git tag -a v0.2.1 -m "版本 0.2.1
主要更新：
- 文件系统模块化架构
- Markdown Mermaid 图表支持
- 代码语法高亮
- 主题适配优化"
步骤 6：验证标签
# 查看所有标签
git tag -l
# 查看标签详情
git show v0.2.1
步骤 7：推送到远程（可选）
# 推送提交
git push origin main
# 推送标签
git push origin v0.2.1
版本发布后
1. 保存版本发布说明
将步骤 1.4 中创建的版本发布说明文档提交到仓库：
# 检查发布说明文档
git add "docs/项目管理/版本发布/v0.2.1-发布说明.md"
# 单独提交发布说明
git commit -m "文档：版本 0.2.1 发布说明"
或者在提交版本更改时一起提交（推荐）：
# 步骤 4 中一起提交
git add -A
git commit -m "发布：版本 0.2.1
- 包含版本发布说明文档
- 代码版本号已更新
- 文档版本号已更新"
2. 更新 CHANGELOG
创建或更新 CHANGELOG.md，记录本版本的变更：
## [0.2.1] - 2026-02-04
### 新增
- Markdown Mermaid 图表渲染支持
- 180+ 编程语言语法高亮
- 文件系统模块化架构
### 修复
- 编辑/预览模式切换时 Mermaid 渲染问题
- 亮色/暗色模式主题适配
### 优化
- 代码结构优化，使用 CSS 变量管理主题色
3. 构建发布版本
# Wails 构建
wails build
# 构建产物位置
# Windows: build/bin/u-desk.exe
4. 测试发布版本
- 安装测试
- 核心功能验证
- 版本号显示检查
检查清单
发布前
- 版本号已更新（代码 + 文档）
- 提交信息清晰准确
- Git 标签已创建
- 标签注释完整
发布后
- CHANGELOG 已更新
- 构建成功
- 测试通过
- 标签已推送（如需远程发布）
常见问题
Q: 忘记更新某个文件的版本号怎么办？
A: 可以修改后重新提交，然后删除旧标签并重新创建：
# 删除本地标签
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 命令：
# 查看两个标签之间的差异
git diff v0.2.0 v0.2.1
# 查看标签与当前的差异
git diff v0.2.1 HEAD
参考资源
附录：完整发布脚本示例
#!/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"
使用方法：
chmod +x scripts/release.sh
./scripts/release.sh