Asterinas项目版本发布流程优化方案

背景介绍

在Asterinas项目中，版本管理一直是一个痛点问题。项目采用单一VERSION文件来管理全局版本号，所有发布的crate和配套Docker镜像都共享这个版本号。这种设计虽然简化了版本匹配，但在实际发布过程中却带来了诸多不便。

现有问题分析

当前版本发布流程存在三个主要问题：

1. CI测试阻塞：当新版本发布时，由于需要同时生成Docker镜像和发布crate，CI测试会首先失败，导致主分支和所有待合并PR的CI状态显示为"失败"，这种状态会持续较长时间。

2. 未充分测试的版本发布：在Docker镜像生成完成后重新运行CI测试时，经常发现与新版本相关的代码变更存在问题，这降低了版本发布的信心。

3. 不必要的crate发布：有时我们只需要生成新的Docker镜像（如添加新工具或测试套件），却不得不发布新的crate版本。

核心解决方案

为了解决这些问题，我们提出将当前的原子性版本发布PR拆分为三个独立的PR：

1. Docker镜像版本更新PR：仅触发新Docker镜像的生成，不影响现有代码。
2. 切换至最新Docker镜像PR：在所有代码位置更新Docker镜像引用。
3. 项目版本更新PR：触发新版本crate的发布。

详细设计方案

引入DOCKER_IMAGE_VERSION文件

我们新增一个DOCKER_IMAGE_VERSION文件，其版本号格式为MAJOR.MINOR.PATCH+DATE，其中：

• MAJOR.MINOR.PATCH部分与对应crate版本一致
• +DATE部分表示Docker镜像生成日期（构建元数据）

这种设计既保持了crate与Docker镜像版本的直观对应关系，又允许在不改变crate版本的情况下生成新的Docker镜像。

版本文件关系

我们维护以下不变式：DOCKER_IMAGE_VERSION >= VERSION（比较时忽略DATE部分）。大多数情况下，两个版本号保持相同。

CI触发机制调整

• Docker镜像生成由DOCKER_IMAGE_VERSION变更触发
• Crate发布仍由VERSION变更触发

bump_version.sh工具改造

该工具将提供三个子命令：

1. --docker_version_file：仅更新DOCKER_IMAGE_VERSION文件
2. --docker_version_refs：更新所有Docker镜像版本引用
3. --version_file：更新VERSION文件以匹配DOCKER_IMAGE_VERSION

工具会确保不破坏两个版本文件间的不变式关系。

典型使用场景

场景1：对Docker镜像进行非破坏性变更

1. PR1：更新DOCKER_IMAGE_VERSION（如0.13.1+20250318）
2. PR2：更新所有Docker镜像引用
3. 跳过PR3

场景2：对Docker镜像进行破坏性变更

1. PR1：更新DOCKER_IMAGE_VERSION（如0.14.0+20250318）
2. PR2：更新引用并修改不兼容代码
3. PR3：更新VERSION以发布新crate版本

场景3：对已发布crate的API进行破坏性变更

1. PR1：更新DOCKER_IMAGE_VERSION
2. PR2：更新所有引用
3. PR3：更新VERSION并可能合并其他功能/修复

方案优势

1. 解耦发布流程：将Docker镜像生成和crate发布分离，避免相互阻塞。
2. 提高发布质量：确保新版本经过充分测试后才发布。
3. 灵活选择：可根据需要仅生成Docker镜像或同时发布crate。
4. 保持版本对应：通过版本号设计保持crate与Docker镜像的直观对应关系。

这个优化方案显著改善了Asterinas项目的版本发布体验，使发布过程更加可靠和高效。