版本管理策略

版本管理策略#

从 vLLM 0.7.x 开始，vLLM Ascend 插件（vllm-project/vllm-ascend）项目遵循 PEP 440 ，以与 vLLM（vllm-project/vllm）版本匹配发布。

每个 vLLM Ascend 版本将采用以下版本格式：v[major].[minor].[micro][rcN][.postN]（例如 v0.7.3rc1、v0.7.3、v0.7.3.post1）

正式版本：通常每3个月发布一次，将综合考虑 vLLM 上游发行计划和昇腾软件产品发行计划。
预发布版本：通常会按需发布，以 rcN 结尾，表示第N个候选发布版本，旨在支持用户在正式发布前进行早期测试。
后续版本：通常会根据需要发布，以支持解决正式发布中的小错误。这与 PEP-440 的后续版本说明建议不同，它将包含实际的 bug 修复，因为最终发布版本应严格与 vLLM 的最终发布版本（v[major].[minor].[micro]）匹配。后续版本必须以正式发布的补丁版本形式发布。

例如：

以下是 vLLM Ascend 插件的版本兼容性矩阵：

vLLM Ascend	vLLM	Python	Stable CANN	PyTorch/torch_npu	MindIE Turbo
v0.9.2rc1	v0.9.2	>= 3.9, < 3.12	8.1.RC1	2.5.1 / 2.5.1.post1.dev20250619
v0.9.1rc1	v0.9.1	>= 3.9, < 3.12	8.1.RC1	2.5.1 / 2.5.1.post1.dev20250528
v0.9.0rc2	v0.9.0	>= 3.9, < 3.12	8.1.RC1	2.5.1 / 2.5.1
v0.9.0rc1	v0.9.0	>= 3.9, < 3.12	8.1.RC1	2.5.1 / 2.5.1
v0.8.5rc1	v0.8.5.post1	>= 3.9, < 3.12	8.1.RC1	2.5.1 / 2.5.1
v0.8.4rc2	v0.8.4	>= 3.9, < 3.12	8.0.0	2.5.1 / 2.5.1
v0.7.3.post1	v0.7.3	>= 3.9, < 3.12	8.1.RC1	2.5.1 / 2.5.1	2.0候选版本1
v0.7.3	v0.7.3	>= 3.9, < 3.12	8.1.RC1	2.5.1 / 2.5.1	2.0候选版本1

vLLM Ascend 有主分支和开发分支。

main：main 分支，对应 vLLM 的主分支和最新的 1 或 2 个发布版本。该分支通过 Ascend CI 持续监控质量。
vX.Y.Z-dev：开发分支，是随着 vLLM 新版本的一部分一起创建的。例如，v0.7.3-dev 是 vLLM v0.7.3 版本的开发分支。

通常，提交应该只先合并到主分支，然后再回溯合并到开发分支，以尽可能降低维护成本。

分支状态将处于以下几种状态之一：

分支	时间范围	摘要
维护中	大约 2-3 个小版本	所有的错误修复都是合适的。正常发布版本，持续集成承诺。
无人维护	社区兴趣驱动	所有的 bug 修复都是合适的。没有发布版本，不承诺持续集成（CI）。
生命周期结束（EOL）	不适用	该分支不再接受更改

请注意，vLLM Ascend 只会针对某些 vLLM 发布版本发布，而不是所有版本。因此，您可能会看到只有部分版本拥有开发分支（例如只有 0.7.1-dev / 0.7.3-dev，而没有 0.7.2-dev），这是正常现象。

通常，vLLM 的每一个小版本（例如 0.7）都会对应一个 vLLM Ascend 版本分支，并支持其最新版本（例如，我们计划支持 0.7.3 版），如下所示：

对于主分支，vLLM Ascend 应该与 vLLM 主分支以及最新的 1 或 2 个发布版本兼容。因此，为了确保向后兼容性，我们将执行以下操作：

主分支和目标 vLLM 发行版都经过了 Ascend E2E CI 的测试。例如，目前正在测试 vLLM 主分支和 vLLM 0.8.4。
对于代码更改，我们也会确保这些更改与最新的 1 或 2 个 vLLM 发行版本兼容。在这种情况下，vLLM Ascend 在代码中引入了版本检查机制。它会先检查已安装的 vLLM 包的版本，然后决定使用哪段代码逻辑。如果用户遇到 InvalidVersion 错误，这有时意味着他们安装了 dev/可编辑版本的 vLLM 包。此时，我们提供了环境变量 VLLM_VERSION，让用户可以指定要使用的 vLLM 包版本。
对于文档更改，我们会确保这些更改也兼容于最新的1个或2个 vLLM 发布版本。如果有任何重大变更，应添加说明。

为了减少维护成本，所有分支的文档内容应保持一致，版本差异可以通过 docs/source/conf.py 中的变量进行控制。虽然这并非易事，但这是我们应当努力遵循的原则。

版本	用途	代码分支
最新	最新开发分支的文档	vX.Y.Z-dev（在第一个正式版本发布后将成为 `main`）
版本	历史版本文档	Git 标签，如 vX.Y.Z[rcN]
稳定版（尚未发布）	最新正式发布分支的文档	首个正式发布后将会是 `vX.Y.Z-dev`

如上所示：

latest 文档：匹配当前维护分支 vX.Y.Z-dev（在首次正式发布后将为 main）。持续更新，以确保适用于最新发布版本。
version 文档：对应特定的已发布版本（例如，v0.7.3、v0.7.3rc1）。发布后不再进行更新。
stable 文档（尚未发布）：官方发布版文档。发布后允许实时更新，通常基于 vX.Y.Z-dev。一旦稳定版文档可用，非稳定版本应显示一个顶部警告：您正在查看最新的开发预览文档。点击此处查看最新稳定版本文档。

torch-npu：Ascend Extension for PyTorch（torch-npu）每 3 个月会在 PyPi 上发布一个稳定版本，每个月发布一个开发版本（即 POC 版本），每天发布一个 nightly 版本。PyPi 上的稳定版本可以用于 vLLM Ascend 的正式版本，月度开发版本只能用于 vLLM Ascend 的 RC（候选发布）版本以便快速迭代，nightly 版本不能用于 vLLM Ascend 的任何版本和分支。