594 lines
15 KiB
Markdown
594 lines
15 KiB
Markdown
# 创建里程碑版本完整指南
|
||
|
||
本文档详细记录了如何为项目创建里程碑版本，包括版本固化、归档备份和回滚准备的完整流程。
|
||
|
||
## 概述
|
||
|
||
里程碑版本是项目开发中的重要节点，用于：
|
||
- 标记稳定功能版本
|
||
- 提供回滚基准点
|
||
- 便于版本对比和分析
|
||
- 保存完整的项目状态快照
|
||
|
||
## 前置条件
|
||
|
||
- 项目代码已提交且功能稳定
|
||
- 确定版本号（如 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. **定期清理**：适时清理过旧的归档文件释放空间
|
||
|
||
### 后续维护
|
||
|
||
- **定期检查**：验证历史版本的可用性
|
||
- **归档管理**：根据项目需要调整保留策略
|
||
- **脚本优化**：根据使用情况改进自动化工具
|
||
- **文档更新**：保持版本管理文档的时效性
|
||
|
||
通过遵循这个完整的流程和使用提供的自动化工具，可以建立起稳健的版本管理体系，为项目的长期发展和维护提供强有力的支撑。
|