SAGE 版本管理策略

Date: 2025-11-10\ Author: GitHub Copilot & ShuhaoZhangTony\ Summary: 新的版本管理策略 - 禁用 main-dev 自动 version bump 以减少 feature 分支 rebase 冲突

📋 概述

为了减少 feature 分支 rebase 时的版本冲突，我们采用以下版本管理策略：

🎯 版本号格式

major.minor.micro.patch (例如: 0.1.9.2)

🔄 自动版本 Bump 规则

✅ 启用自动 bump

• main 分支：每次 push 或 PR merge 自动 bump patch 版本
• 发布到：PyPI (生产环境)

❌ 禁用自动 bump

• main-dev 分支：不再自动 bump 版本
• 原因：避免频繁 version bump 导致所有 feature 分支 rebase 时产生冲突

🛠️ 手动版本管理

main-dev 测试发布

如需在 main-dev 分支测试 PyPI 发布，使用手动触发：

1. 进入 GitHub Actions
2. 选择 "Publish to PyPI" workflow
3. 点击 "Run workflow"
4. 配置：
5. repository: testpypi
6. version_bump: none (保持当前版本)

主动升级版本

需要升级版本时，可选择：

• patch: 0.1.6.2 → 0.1.6.3 (bug 修复)
• micro: 0.1.6.2 → 0.1.7.0 (小功能)
• minor: 0.1.6.2 → 0.2.0.0 (大功能)
• major: 0.1.6.2 → 1.0.0.0 (破坏性更改)

📝 版本冲突处理

Feature 分支 Rebase

现在 feature 分支 rebase 到 main-dev 时：

✅ 不会再有版本文件冲突（main-dev 不再自动 bump）

如仍遇到版本冲突（罕见情况），使用自动化脚本：

# 在 feature 分支上运行
./tools/rebase-to-main-dev.sh

脚本会自动：

1. 更新 main-dev
2. 执行 rebase
3. 自动解决所有 _version.py 冲突
4. 提示手动解决其他冲突（如有）

🎉 优势

1. ✅ 减少摩擦：feature 分支开发和 rebase 更顺畅
2. ✅ 语义化版本：main 分支的版本号更有意义
3. ✅ 灵活控制：需要时可手动触发 main-dev 测试发布
4. ✅ 避免冲突：消除了最常见的 rebase 冲突源

📌 注意事项

• main-dev 的版本号会与 main 分支保持一致，直到下次 main 分支 bump
• 这是正常的，因为 main-dev 是开发分支，不需要频繁变更版本号
• 只有合并到 main 时才需要正式发布新版本