gavin/note2any

Fork 0

Files

douboer 6f51916b50 update at 2025-10-09 12:39:24

2025-10-09 12:39:24 +08:00

15 KiB

Raw Blame History

创建里程碑版本完整指南

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

概述

里程碑版本是项目开发中的重要节点，用于：

标记稳定功能版本
提供回滚基准点
便于版本对比和分析
保存完整的项目状态快照

前置条件

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

详细步骤

1. 检查项目状态

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

# 检查工作目录状态
git status

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

# 添加所有更改
git add .

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

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

2. 创建Git标签

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

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

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

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

3. 创建发布分支

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

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

4. 构建项目

构建项目生成生产版本文件：

# 执行项目构建
npm run build

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

5. 创建归档目录

创建版本归档目录结构：

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

6. 复制关键文件

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

# 复制构建文件
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. 创建源码快照

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

# 创建源码快照（排除不必要的目录）
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. 检查归档内容

验证归档目录的内容：

# 列出归档文件
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. 创建版本信息文档

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

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

VERSION_INFO.md 应包含：

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

10. 切换回主分支

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

git checkout main

11. 推送到远程仓库

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

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

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

12. 验证回滚准备

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

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标签回滚

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

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

方法2: 使用发布分支

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

方法3: 使用源码快照

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

方法4: 使用构建文件

# 直接使用归档的构建文件
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提供可视化说明

注意事项

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

实际执行示例

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

执行的完整命令序列

# 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：

#!/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 ""

脚本使用方法

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

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

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

增强版本（可选功能）

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

# 添加版本号验证
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
}

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

总结

里程碑版本的价值

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

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

完整的版本管理体系

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

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

最佳实践建议

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

后续维护

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

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

15 KiB Raw Blame History Unescape Escape

创建里程碑版本完整指南

概述

前置条件

详细步骤

1. 检查项目状态

2. 创建Git标签

3. 创建发布分支

4. 构建项目

5. 创建归档目录

6. 复制关键文件

7. 创建源码快照

8. 检查归档内容

9. 创建版本信息文档

10. 切换回主分支

11. 推送到远程仓库

12. 验证回滚准备

回滚方法

方法1: 使用Git标签回滚

方法2: 使用发布分支

方法3: 使用源码快照

方法4: 使用构建文件

最佳实践

版本号管理

分支管理

归档管理

提交信息规范

文档要求

注意事项

实际执行示例

执行的完整命令序列

执行结果验证

自动化脚本

自动化脚本

完整的里程碑创建脚本

脚本使用方法

增强版本（可选功能）

总结

里程碑版本的价值

完整的版本管理体系

最佳实践建议

后续维护

15 KiB

Raw Blame History