BharatMLStack项目手动发布指南：从分支管理到版本控制全解析

前言

在机器学习平台开发中，高效的发布流程是保证团队协作和产品质量的关键环节。BharatMLStack项目采用了一套精心设计的手动发布系统，通过分支策略与版本控制的完美结合，为开发者提供了灵活而可靠的发布管理方案。本文将深入解析这套系统的设计理念、使用方法和最佳实践。

核心设计理念

BharatMLStack的发布系统建立在三个核心原则之上：

1. 环境隔离：通过分支名称严格区分开发(alpha)、测试(beta)和生产环境
2. 版本自动化：智能生成符合语义化版本规范的版本号
3. 模块化发布：支持选择性发布特定组件而非全量发布

环境准备

在开始发布流程前，需要确保以下工具已正确安装和配置：

1. Git环境：确保本地已克隆项目仓库并配置好SSH密钥
2. GitHub CLI工具（推荐）：

   # macOS系统安装
   brew install gh
   
   # 认证配置
   gh auth login
   

发布类型详解

1. Alpha发布（开发阶段）

适用分支：

• feat/*（功能开发分支）
• fix/*（问题修复分支）
• feat-nbc/*（非破坏性变更分支）

版本格式：

v1.2.3-alpha-<commit-sha前6位>

特点：

• VERSION文件保持不变
• 发布到测试环境（TestPyPI、无latest标签的Docker镜像）
• 适合内部开发和早期验证

2. Beta发布（测试阶段）

适用分支：develop分支

版本格式：

v1.2.3-beta-<commit-sha前6位>

特点：

• VERSION文件保持不变
• 发布到准生产环境
• 适合集成测试和用户验收测试

3. Standard发布（生产阶段）

适用分支：

• main/master
• release/*

版本格式：

v1.2.3

特点：

• 直接使用VERSION文件中的版本号
• 发布到生产环境（PyPI、带latest标签的Docker镜像）
• 需要手动更新VERSION文件

组件发布详解

BharatMLStack采用微服务架构，支持按需发布以下组件：

1. 容器化服务

组件名称	功能描述	特殊说明
horizon	容器编排服务	基础平台服务
trufflebox-ui	用户界面	前端展示层
online-feature-store	特征存储服务	包含API服务和消费者两个镜像

2. SDK工具包

组件名称	语言	包含模块
go-sdk	Go语言	完整Go SDK
py-sdk	Python	bharatml_commons, grpc_feature_client, spark_feature_push_client

实战操作指南

基础发布流程

1. 切换到目标分支：

   git checkout <branch-name>
   

2. 执行发布脚本：

   ./manual-release.sh
   

3. 交互式选择：

   • 选择发布类型（alpha/beta/standard）
   • 选择要发布的组件
   • 确认发布计划

典型场景示例

场景一：从功能分支发布alpha版本

git checkout feat/user-authentication
./manual-release.sh
# 选择Alpha发布
# 选择需要发布的模块

场景二：从develop分支发布beta版本

git checkout develop
./manual-release.sh
# 选择Beta发布
# 选择全部模块进行集成测试

场景三：生产环境发布

git checkout main
# 首先手动更新各模块VERSION文件
vim horizon/VERSION  # 修改为v1.2.3
./manual-release.sh
# 选择Standard发布
# 选择所有模块

版本管理策略

版本文件规范

每个模块根目录下的VERSION文件遵循简单格式：

v<主版本号>.<次版本号>.<修订号>

示例：

v0.1.20

自动版本生成逻辑

对于alpha/beta发布：

1. 读取VERSION文件中的基础版本（如v0.1.20）
2. 追加发布类型和提交哈希（如-alpha-abc123）
3. 生成最终发布版本（v0.1.20-alpha-abc123）
4. 不修改原始VERSION文件

工作流触发机制

发布脚本会自动触发对应的GitHub工作流：

组件类型	工作流功能
Python包	构建并发布到PyPI/TestPyPI
Docker服务	构建镜像并推送到容器仓库
Go SDK	创建Git标签和GitHub发布

最佳实践建议

1. 分支管理：

   • 功能开发使用feat/前缀分支
   • 问题修复使用fix/前缀分支
   • 长期开发分支定期合并到develop

2. 版本迭代：

   • 小版本迭代直接修改VERSION文件
   • 大版本更新时创建release分支

3. 发布策略：

   • 每日构建可使用alpha版本
   • 每周集成使用beta版本
   • 生产发布前确保通过所有测试

常见问题排查

问题一：发布类型不可选

• 检查当前分支是否符合命名规范
• 确保位于正确的git仓库中

问题二：工作流未触发

• 检查GitHub CLI认证状态
• 确认.github/workflows/目录存在对应工作流文件

问题三：版本号不符合预期

• 检查VERSION文件是否存在且格式正确
• 确认没有未提交的更改影响版本计算

结语

BharatMLStack的手动发布系统通过精细的分支策略和智能的版本管理，为机器学习平台的持续交付提供了可靠保障。掌握这套系统不仅能提高发布效率，更能确保软件交付的质量和可追溯性。建议团队新成员通过本文的实践示例快速上手，并在实际项目中不断积累经验。