新增：文档体系重构+CHANGELOG补充+发布产物清理

2026-05-01 22:22:06 +08:00
parent 3e1a540b83
commit 6eaaa56eb6
164 changed files with 40346 additions and 64 deletions
--- a/docs/07-项目管理/版本管理/版本发布手册.md
+++ b/docs/07-项目管理/版本管理/版本发布手册.md
@@ -0,0 +1,391 @@
+# 版本发布手册
+
+> 项目：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
+```