# 创建里程碑版本完整指南

本文档详细记录了如何为项目创建里程碑版本，包括版本固化、归档备份和回滚准备的完整流程。

## 概述

里程碑版本是项目开发中的重要节点，用于：
- 标记稳定功能版本
- 提供回滚基准点  
- 便于版本对比和分析
- 保存完整的项目状态快照

## 前置条件

- 项目代码已提交且功能稳定
- 确定版本号（如 v1.3.0）
- 有Git仓库管理
- 确保当前工作目录干净

## 详细步骤

### 1. 检查项目状态

首先检查当前Git状态，确保所有更改都已处理：

```bash
# 检查工作目录状态
git status
```

如果有未提交的更改，需要先添加并提交：

```bash
# 添加所有更改
git add .

# 提交更改（使用详细的提交信息）
git commit -m "feat: 完成批量发布系统和详细文档
- 实现批量发布模态框，支持数据库式文章筛选
- 添加鼠标拖拽多选功能，支持Ctrl键修饰符  
- 增加文章过滤器，支持标签、文件名、文件夹筛选
- 完善图库短码mppickall参数支持
- 优化EXIF图片方向处理
- 添加全面的中文代码注释
- 更新详细设计文档和架构图表
- 完善变更日志和README文档

版本: v1.3.0 (里程碑版本)"
```

### 2. 创建Git标签

创建带详细注释的Git标签：

```bash
git tag -a v1.3.0 -m "里程碑版本 v1.3.0

主要功能:
- 批量发布系统: 完整的数据库式文章筛选和批量发布功能
- 高级UI交互: 鼠标拖拽多选，Ctrl键支持，滚动容器处理
- 图库增强: mppickall参数支持，EXIF图片方向处理
- 完整文档: 详细设计文档，架构图表，中文注释

此版本为稳定的里程碑版本，用于后续大规模修改前的对比和回滚基准。"
```

### 3. 创建发布分支

创建专门的发布分支保存当前状态：

```bash
# 创建并切换到发布分支
git checkout -b release/v1.3.0
```

### 4. 构建项目

构建项目生成发布所需的产物：

```bash
# 执行未混淆构建（推荐用于验证与调试）
npm run build

# 检查构建输出
ls -la main.js manifest.json

# 如需生成混淆后的发布包，可执行：
npm run build:obf
```

### 5. 创建归档目录

创建版本归档目录结构：

```bash
# 创建归档目录
mkdir -p archives/v1.3.0
```

### 6. 复制关键文件

将构建文件和重要文档复制到归档目录：

```bash
# 复制构建文件
cp main.js manifest.json styles.css package.json archives/v1.3.0/

# 复制文档文件
cp README.md CHANGELOG.md detaildesign.md diagrams.md archives/v1.3.0/
```

### 7. 创建源码快照

创建完整的源代码压缩包：

```bash
# 创建源码快照（排除不必要的目录）
cd .. && tar -czf note2mp/archives/v1.3.0/source-snapshot-v1.3.0.tar.gz \
  --exclude='node_modules' \
  --exclude='.git' \
  --exclude='archives' \
  note2mp/

# 回到项目目录
cd note2mp
```

### 8. 检查归档内容

验证归档目录的内容：

```bash
# 列出归档文件
ls -la archives/v1.3.0/
```

应该包含：
- `main.js` - 构建后的主文件
- `manifest.json` - 插件清单
- `styles.css` - 样式文件  
- `package.json` - 依赖信息
- `README.md` - 项目说明
- `CHANGELOG.md` - 变更日志
- `detaildesign.md` - 设计文档
- `diagrams.md` - 架构图表
- `source-snapshot-v1.3.0.tar.gz` - 完整源码

### 9. 创建版本信息文档

创建详细的版本信息文档：

```bash
# 版本信息文档内容见 VERSION_INFO.md 模板
```

VERSION_INFO.md 应包含：
- 版本基本信息（版本号、日期、Git信息）
- 主要功能特性列表
- 归档内容说明
- 详细的回滚操作指南
- 版本对比用途说明

### 10. 切换回主分支

完成归档后切换回主分支：

```bash
git checkout main
```

### 11. 推送到远程仓库

将所有版本信息推送到远程备份：

```bash
# 推送主分支和标签
git push origin main --tags

# 推送发布分支
git push origin release/v1.3.0
```

### 12. 验证回滚准备

最后验证所有回滚机制都已就绪：

```bash
echo "=== 验证回滚机制 ==="
echo "1. Git标签:"
git tag | grep v1.3.0
echo -e "\n2. 发布分支:"
git branch -a | grep release
echo -e "\n3. 归档目录:"
ls -la archives/v1.3.0/ | head -5
echo -e "\n4. 远程备份:"
git ls-remote --tags origin | grep v1.3.0
```

## 回滚方法

### 方法1: 使用Git标签回滚

```bash
# 直接切换到标签
git checkout v1.3.0

# 或者基于标签创建新分支
git checkout v1.3.0
git checkout -b rollback-to-v1.3.0
```

### 方法2: 使用发布分支

```bash
# 切换到发布分支
git checkout release/v1.3.0
```

### 方法3: 使用源码快照

```bash
# 解压源码快照
tar -xzf archives/v1.3.0/source-snapshot-v1.3.0.tar.gz
```

### 方法4: 使用构建文件

```bash
# 直接使用归档的构建文件
cp archives/v1.3.0/main.js ./
cp archives/v1.3.0/manifest.json ./
cp archives/v1.3.0/styles.css ./
```

## 最佳实践

### 版本号管理
- 使用语义化版本号（如 v1.3.0）
- 主版本号.次版本号.修订号
- 里程碑版本建议使用次版本号升级

### 分支管理
- `main` - 主开发分支
- `release/vX.X.X` - 发布分支，只用于版本固化
- 避免在发布分支上继续开发

### 归档管理
- 归档目录结构：`archives/vX.X.X/`
- 包含构建文件、文档、源码快照
- 每个版本都应有VERSION_INFO.md说明文档

### 提交信息规范
- 使用约定式提交（Conventional Commits）
- 包含版本信息和功能摘要
- 标明里程碑版本性质

### 文档要求
- **更新CHANGELOG.md**：详细记录所有功能变更、修复和改进
- **更新README.md**：
  - 在顶部添加版本更新说明和重要提醒
  - 反映最新功能特性和使用方法
  - 包含新功能的技术说明（如EXIF处理）
  - 添加调试信息和用户指南
- **维护详细的设计文档**：detaildesign.md应包含架构和实现细节
- **包含架构图表和技术规格**：diagrams.md提供可视化说明

## 注意事项

1. **确保代码稳定**：只有经过充分测试的稳定代码才应该创建里程碑
2. **完整的文档**：确保所有文档都是最新的并反映当前功能
3. **构建验证**：确保构建过程无错误且生成正确的文件
4. **远程备份**：始终将重要版本信息推送到远程仓库
5. **版本信息**：创建详细的版本说明文档便于后续参考

## 实际执行示例

以下是创建 v1.3.0 里程碑版本的完整执行记录：

### 执行的完整命令序列

```bash
# 1. 检查项目状态
git status

# 2. 添加并提交所有更改
git add .
git commit -m "feat: 完成批量发布系统和详细文档
- 实现批量发布模态框，支持数据库式文章筛选
- 添加鼠标拖拽多选功能，支持Ctrl键修饰符
- 增加文章过滤器，支持标签、文件名、文件夹筛选
- 完善图库短码mppickall参数支持
- 优化EXIF图片方向处理
- 添加全面的中文代码注释
- 更新详细设计文档和架构图表
- 完善变更日志和README文档

版本: v1.3.0 (里程碑版本)"

# 3. 创建Git标签
git tag -a v1.3.0 -m "里程碑版本 v1.3.0

主要功能:
- 批量发布系统: 完整的数据库式文章筛选和批量发布功能
- 高级UI交互: 鼠标拖拽多选，Ctrl键支持，滚动容器处理
- 图库增强: mppickall参数支持，EXIF图片方向处理
- 完整文档: 详细设计文档，架构图表，中文注释

此版本为稳定的里程碑版本，用于后续大规模修改前的对比和回滚基准。"

# 4. 创建发布分支
git checkout -b release/v1.3.0

# 5. 构建项目
npm run build
ls -la main.js manifest.json

# 6. 创建归档目录
mkdir -p archives/v1.3.0

# 7. 复制关键文件
cp main.js manifest.json styles.css package.json archives/v1.3.0/
cp README.md CHANGELOG.md detaildesign.md diagrams.md archives/v1.3.0/

# 8. 创建源码快照
cd .. && tar -czf note2mp/archives/v1.3.0/source-snapshot-v1.3.0.tar.gz \
  --exclude='node_modules' \
  --exclude='.git' \
  --exclude='archives' \
  note2mp/
cd note2mp

# 9. 检查归档内容
ls -la archives/v1.3.0/

# 10. 创建版本信息文档 (VERSION_INFO.md)
# [在此创建详细的版本信息文档]

# 11. 切换回主分支
git checkout main

# 12. 推送到远程
git push origin main --tags
git push origin release/v1.3.0

# 13. 验证回滚准备
echo "=== 验证回滚机制 ==="
echo "1. Git标签:"
git tag | grep v1.3.0
echo -e "\n2. 发布分支:"
git branch -a | grep release
echo -e "\n3. 归档目录:"
ls -la archives/v1.3.0/ | head -5
echo -e "\n4. 远程备份:"
git ls-remote --tags origin | grep v1.3.0
```

### 执行结果验证

执行完成后应该看到：
- Git标签：`v1.3.0`
- 分支：`release/v1.3.0` 和 `remotes/origin/release/v1.3.0`
- 归档文件：11个文件包括构建产物、文档和源码快照
- 远程备份：标签已推送到远程仓库

## 自动化脚本

## 自动化脚本

可以创建自动化脚本简化里程碑创建过程：

### 完整的里程碑创建脚本

创建 `scripts/create_milestone.sh`：

```bash
#!/bin/bash
# create_milestone.sh - 自动创建项目里程碑版本
# 使用方法: ./create_milestone.sh v1.3.0 "里程碑版本描述"

set -e  # 遇到错误立即退出

VERSION=$1
DESCRIPTION=${2:-"里程碑版本"}

if [ -z "$VERSION" ]; then
    echo "❌ 错误: 请提供版本号"
    echo "使用方法: $0 <version> [description]"
    echo "示例: $0 v1.3.0 '批量发布系统完成'"
    exit 1
fi

echo "🚀 开始创建里程碑版本: $VERSION"

# 1. 检查工作目录状态
echo "📋 检查Git状态..."
if ! git diff-index --quiet HEAD --; then
    echo "⚠️  发现未提交的更改，正在自动提交..."
    git add .
    git commit -m "feat: $DESCRIPTION

版本: $VERSION (里程碑版本)"
fi

# 2. 创建Git标签
echo "🏷️  创建Git标签..."
git tag -a "$VERSION" -m "$DESCRIPTION

此版本为稳定的里程碑版本，用于后续大规模修改前的对比和回滚基准。"

# 3. 创建发布分支
echo "🌿 创建发布分支..."
git checkout -b "release/$VERSION"

# 4. 构建项目
echo "🔨 构建项目..."
npm run build

# 5. 创建归档目录
echo "📁 创建归档目录..."
mkdir -p "archives/$VERSION"

# 6. 复制关键文件
echo "📋 复制构建文件..."
cp main.js manifest.json styles.css package.json "archives/$VERSION/"

echo "📄 复制文档文件..."
cp README.md CHANGELOG.md "archives/$VERSION/" 2>/dev/null || echo "⚠️  某些文档文件不存在，跳过"
cp detaildesign.md diagrams.md "archives/$VERSION/" 2>/dev/null || echo "⚠️  设计文档不存在，跳过"

# 7. 创建源码快照
echo "📦 创建源码快照..."
cd .. && tar -czf "$(basename "$PWD")/archives/$VERSION/source-snapshot-$VERSION.tar.gz" \
  --exclude='node_modules' \
  --exclude='.git' \
  --exclude='archives' \
  "$(basename "$PWD")/"
cd "$(basename "$PWD")"

# 8. 创建版本信息文档
echo "📋 创建版本信息文档..."
cat > "archives/$VERSION/VERSION_INFO.md" << EOF
# 里程碑版本 $VERSION

## 版本信息
- **版本号**: $VERSION
- **发布日期**: $(date +%Y年%m月%d日)
- **Git Tag**: $VERSION
- **Git Branch**: release/$VERSION
- **Git Commit**: $(git rev-parse HEAD)
- **描述**: $DESCRIPTION

## 回滚说明
如需回滚到此版本：

1. **使用Git Tag回滚**:
   \`\`\`bash
   git checkout $VERSION
   git checkout -b rollback-to-$VERSION
   \`\`\`

2. **使用发布分支**:
   \`\`\`bash
   git checkout release/$VERSION
   \`\`\`

3. **使用源代码快照**:
   \`\`\`bash
   tar -xzf archives/$VERSION/source-snapshot-$VERSION.tar.gz
   \`\`\`

---
*此版本为稳定的里程碑版本，建议在进行大规模代码修改前保存此状态。*
EOF

# 9. 切换回主分支
echo "🔄 切换回主分支..."
git checkout main

# 10. 推送到远程
echo "☁️  推送到远程仓库..."
if git remote | grep -q origin; then
    git push origin main --tags
    git push origin "release/$VERSION"
    echo "✅ 已推送到远程仓库"
else
    echo "⚠️  无远程仓库，跳过推送"
fi

# 11. 验证创建结果
echo "🔍 验证里程碑创建结果..."
echo "📁 归档目录内容:"
ls -la "archives/$VERSION/"

echo ""
echo "🎯 里程碑版本 $VERSION 创建完成！"
echo ""
echo "📋 创建内容:"
echo "  - Git标签: $VERSION"
echo "  - 发布分支: release/$VERSION" 
echo "  - 归档目录: archives/$VERSION/"
echo "  - 源码快照: source-snapshot-$VERSION.tar.gz"
echo ""
echo "🔄 回滚方法:"
echo "  git checkout $VERSION  # 使用标签"
echo "  git checkout release/$VERSION  # 使用分支"
echo ""
```

### 脚本使用方法

```bash
# 赋予执行权限
chmod +x scripts/create_milestone.sh

# 创建里程碑版本
./scripts/create_milestone.sh v1.3.0 "批量发布系统和文档完善"

# 或使用默认描述
./scripts/create_milestone.sh v1.4.0
```

### 增强版本（可选功能）

可以进一步增强脚本功能：

```bash
# 添加版本号验证
validate_version() {
    if [[ ! $VERSION =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
        echo "❌ 版本号格式错误，应为 vX.X.X 格式"
        exit 1
    fi
}

# 检查版本是否已存在
check_version_exists() {
    if git tag | grep -q "^$VERSION$"; then
        echo "❌ 版本 $VERSION 已存在"
        exit 1
    fi
}

# 自动更新package.json版本号
update_package_version() {
    if [ -f package.json ]; then
        npm version "${VERSION#v}" --no-git-tag-version
        git add package.json
    fi
}
```

通过使用自动化脚本，可以显著简化里程碑版本的创建过程，减少人为错误，确保每次都按照标准流程执行。

## 总结

### 里程碑版本的价值

创建里程碑版本是软件开发中的重要实践，它提供了：

1. **稳定性保障**：为项目提供已知稳定状态的基准点
2. **风险控制**：在进行大规模修改前提供安全的回退选项  
3. **版本对比**：便于分析功能演进和性能变化
4. **团队协作**：为团队成员提供统一的版本参考点
5. **部署管理**：支持生产环境的版本回滚和问题排查

### 完整的版本管理体系

通过本指南建立的版本管理包含：

- **Git标签系统**：语义化版本标记和详细注释
- **分支管理**：专门的发布分支保护稳定版本
- **文件归档**：构建产物和文档的完整备份
- **源码快照**：完整项目状态的压缩包存档
- **自动化工具**：标准化的脚本减少操作错误
- **详细文档**：每个版本的特性说明和回滚指南

### 最佳实践建议

1. **定期创建**：在重要功能完成后及时创建里程碑
2. **标准命名**：使用语义化版本号和清晰的描述
3. **完整测试**：确保里程碑版本经过充分验证
4. **文档同步**：保持代码和文档的一致性
5. **远程备份**：始终将重要版本推送到远程仓库
6. **定期清理**：适时清理过旧的归档文件释放空间

### 后续维护

- **定期检查**：验证历史版本的可用性
- **归档管理**：根据项目需要调整保留策略
- **脚本优化**：根据使用情况改进自动化工具
- **文档更新**：保持版本管理文档的时效性

通过遵循这个完整的流程和使用提供的自动化工具，可以建立起稳健的版本管理体系，为项目的长期发展和维护提供强有力的支撑。