企业官网建设流程全解析

ONNX Runtime WebGPU 插件 EP 发布流程：按次版本划分支、命名空间标签与三阶段 Release 工作流

【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime

本篇基于 ONNX Runtime 仓库中 plugin-ep-webgpu/RELEASE.md 的发布规范展开，完整覆盖 WebGPU 插件执行提供程序（Plugin EP）的语义化版本管理、plugin-ep-webgpu/前缀的分支与标签命名规则、与主 ORT 发布惯例的差异，以及"准备分支—构建验证—正式发布"的三步工作流。读完之后，你能够按照仓库约定独立完成一次 patch 或 minor 版本发布，并理解 CI 管道中版本号的自动派生机制。

发布对象：WebGPU 插件 EP 是什么

在讨论发布流程之前，先明确"发布"的是哪个东西。WebGPU 插件 EP 是独立于主onnxruntime二进制分发的执行提供程序：它被主 ONNX Runtime 构建以--use_webgpu shared_lib产出为共享库（onnxruntime_providers_webgpu.{dll,so,dylib}），再由 plugin-ep-webgpu 目录下的打包源打成：

• 各平台的 Python wheelonnxruntime-ep-webgpu（源在 plugin-ep-webgpu/python）；
• 跨平台的 NuGet 包Microsoft.ML.OnnxRuntime.EP.WebGpu（源在 plugin-ep-webgpu/csharp）；
• 供 Foundry Local 消费的分平台 zip 包。

因此，一次插件 EP 发布最终体现为多个包制品，但版本控制只需要围绕一组文件展开，这就是本规范保持简洁的前提。

版本管理：语义化版本与 VERSION_NUMBER 文件

插件 EP 遵循语义化版本（Semantic Versioning），三个分量的含义在 RELEASE.md 中定义如下：

• MAJOR— 不兼容的 API/ABI 变更；
• MINOR— 向后兼容的功能新增；
• PATCH— 向后兼容的缺陷与安全修复。

当前版本号追踪在 plugin-ep-webgpu/VERSION_NUMBER 文件中，仓库现状为0.4.0。该文件是 CI 管道的"基础版本单一事实来源"：管道根据构建参数（release / dev）从中派生出最终包版本。与之配套的是 plugin-ep-webgpu/MIN_ONNXRUNTIME_VERSION（当前为1.24.4），它声明了兼容的核心onnxruntime最低版本。按 plugin-ep-webgpu/README.md 的说明，各包并不对某个具体 ORT 包声明硬依赖，而是把这个版本串在打包时注入各包 README，并由原生插件 EP 代码在注册时做运行时兼容性校验。

从 tools/ci_build/set_plugin_ep_build_variables.py 的源码可以看到版本号派生的具体规则：

• package_version=release时，包版本与 Python 版本都直接等于VERSION_NUMBER的内容（如0.4.0）；
• package_version=dev时，管道通过git rev-parse --short=8 HEAD和 commit 的 UTC 时间戳生成形如0.4.0.devYYYYMMDDHHMMSS（PEP 440 格式）与0.4.0-dev.YYYYMMDDHHMMSS+<sha>（semver 格式）的开发版本串，并用两个正则分别校验 semver 2.0.0 与 PEP 440 合法性后才写入管道变量；
• package_version=rc目前会直接让构建失败并提示 "RC versioning is not yet implemented"。这一点与 RELEASE.md 中"pre-release 标签约定是前瞻性（forward-looking）的，目前发布流程还没有 release candidate"的表述完全吻合——约定先定好，实现随后跟上。

分支与标签命名：命名空间 + 前缀双保险

所有发布 ref 都统一置于plugin-ep-webgpu/命名空间下，这样它们在git branch/git tag列表中聚成一组，也不会和主 ONNX Runtime 的发布 ref 冲突。具体有三类：

1. Release 分支：plugin-ep-webgpu/rel-X.Y
   • 每个 minor 版本线一个分支（例如plugin-ep-webgpu/rel-1.0）；
   • 承载该 minor 线上的所有 patch 发布（1.0.0、1.0.1、1.0.2、……）；
   • 在首次发布时从main分叉出来。
2. Release 标签：plugin-ep-webgpu/vX.Y.Z
   • 每次实际发布的产物打一个标签（例如plugin-ep-webgpu/v1.0.0）；
   • 标签不可变（immutable），是"到底发布了什么"的事实来源（source of truth）。
3. Pre-release 标签：plugin-ep-webgpu/vX.Y.Z-rc.N
   • 用于 release candidate 及其他预发布制品，采用 semver 风格的后缀；
   • 目前为前瞻性约定，流程中尚无 RC 环节（与上文的 RC 未实现状态对应）。

一个细节值得注意：分支用rel-前缀、标签用v前缀，两者在 ref 层级上永远不会产生歧义——即使同一条 minor 线上既有rel-1.0分支又有v1.0.0标签，也不会互相覆盖或混淆。

与主 ONNX Runtime 惯例的差异：为什么按 minor 划分支

主 ORT 仓库采用的是按 patch划分的发布分支，形式为rel-X.Y.Z（例如rel-1.20.0、rel-1.20.1，每个 patch 一个分支）。WebGPU 插件 EP 则刻意选择了按 minor划分的rel-X.Y，RELEASE.md 给出了两条理由：

• 简单性：每条受支持的 minor 线只有一个长生命周期分支，每次 patch 发布用该分支上的一个标签来标记。"标签"是不可变的发布记录，"分支"只是下一个 patch 的暂存处。对于一个体量、发布节奏都有限的组件，这套模型足够用，还能避免按 patch 模型造成的分支蔓延（branch sprawl）。
• 通用惯例：per-minor 模型是更广泛的开源社区惯例（Linux、LLVM、Python、Node、Kubernetes 都如此），ORT 生态之外的贡献者会感到熟悉。

再加上plugin-ep-webgpu/命名空间前缀，插件的发布 ref 与主 ORT 的发布 ref 就保持了清晰的隔离。可以推断，这套设计的核心思想是：把"可变"（分支）与"不可变"（标签）的职责拆开，并让命名空间承担与主线发布的隔离职责。

发布工作流：三步走

第一步：准备发布分支

按发布类型走对应的子流程（原文 RELEASE.md 的 Step 1）：

新的 minor 或 major 发布：

1. 从main创建发布分支plugin-ep-webgpu/rel-X.Y。此时main上的VERSION_NUMBER应已经是X.Y.0，即反映即将切出的那个发布；
2. 把main上的VERSION_NUMBER提升到下一个开发版本（例如切1.0.0后，把main提升到1.1.0）。

Patch 发布：

1. 在既有发布分支plugin-ep-webgpu/rel-X.Y上，把VERSION_NUMBER提升到X.Y.Z。

可以看到版本号的管理完全集中在 plugin-ep-webgpu/VERSION_NUMBER 这一个文件上：main上永远指向"下一个 minor 的 .0"，各 release 分支上则滚动指向最新 patch。

第二步：集成修复、构建并验证包

这一步可循环执行多次，直到满意为止（原文 Step 2）：

1. 把修复集成进发布分支——可以从maincherry-pick，也可以直接在发布分支上做。后者除非是发布分支特有的修复，否则应回灌到main；
2. 在发布分支的 tip 上运行打包管道（WebGPU Plugin EP Packaging Pipeline，管道定义见 tools/ci_build/github/azure-pipelines/plugin-webgpu-pipeline.yml）。
3. 确认紧随其后的打包测试管道（WebGPU Plugin EP Test Pipeline，定义见 tools/ci_build/github/azure-pipelines/plugin-webgpu-test-pipeline.yml）运行成功。打包管道成功后会自动触发测试管道——两者刻意分离，源码注释解释为：这样测试侧（Dockerfile、Vulkan 配置、测试脚本）可以独立迭代，而不必重新从源码构建 Dawn/WebGPU；
4. 可选：运行发布管道发布测试版包做预演。NuGet 发布管道支持把PublishLocation参数设为 "nugettest"（int.nugettest.org）或 "ado"（ADO nightly feed）。原文特别警告：该管道同样用于发布到 nuget.org，运行前务必二次确认PublishLocation取值；Python 测试发布则固定发布到 ADO nightly feed；
5. 按需执行其他人工验证。

结合管道定义文件，第二步还有一些值得了解的工程细节：

• 打包管道支持五个平台的独立开关：build_windows_x64、build_windows_arm64、build_linux_x64、build_linux_aarch64、build_macos_arm64，默认全部开启；
• package_version参数可选release/dev（源码中# - RC # not implemented yet被注释掉），默认dev；
• 管道内置参数校验：非dev的包版本必须搭配Release的 CMake 构建类型，否则在 Validate_Parameters 阶段直接报错失败（"Non-dev package version requires Release build type"）；
• 除手动触发外，打包管道还有每日 09:00（UTC）的 nightly 计划任务，仅在main相对上次成功构建有源码变更时执行；
• 版本号派生步骤通过 tools/ci_build/github/azure-pipelines/templates/set-plugin-ep-build-variables-step.yml 调用前述 Python 脚本完成，epVersionFile变量即指向plugin-ep-webgpu/VERSION_NUMBER。

另外，plugin-ep-webgpu/paths.txt 定义了与 WebGPU EP 相关的路径清单（如onnxruntime/core/providers/webgpu、plugin-ep-webgpu等），CI 用它在识别"两次发布之间发生了什么变更"（例如生成 release notes）时过滤提交——这也是发布流程的一部分工具。

第三步：正式发布

原文（Step 3）的最终动作序列是：

1. 运行打包管道并把Package Version参数设为release，这次运行产出的就是 release 构建；
2. 运行发布管道发布正式包，注意要把第 1 项的 release 构建选为源打包管道运行：NuGet 发布时PublishLocation设为 "nuget"；Python 发布走对应的 Python publishing 管道；
3. 在产出 release 构建的那个 commit上，给发布分支打上标签plugin-ep-webgpu/vX.Y.Z——"同一个 commit"是关键，保证标签精确指向实际发布的代码；
4. 在该标签上创建一个 GitHub release。

第 3 步呼应了命名约定中的原则：标签是不可变记录，因此一旦打完vX.Y.Z就不能再动；后续同一 minor 线上的下一个 patch，则回到第一步（patch 分支上提升VERSION_NUMBER）重新走完整流程。

小结：这套发布约定给了什么

回到 plugin-ep-webgpu/RELEASE.md 的规范本身，它用很少的篇幅约定了三件事，并与仓库中的实现证据一一对应：

• 版本：semver 三分量 + 单一VERSION_NUMBER文件（现值0.4.0），CI 依据 tools/ci_build/set_plugin_ep_build_variables.py 派生出 release/dev 两种包版本串，RC 约定先行、实现待补；
• 命名：plugin-ep-webgpu/命名空间 +rel-X.Y按 minor 分支 +vX.Y.Z不可变标签，与主 ORT 的按 patch 分支模型显式解耦；
• 流程：准备分支 → 可循环的构建/测试验证（含发布测试版预演与PublishLocation防误操作提醒）→ release 构建 + 发布 + 同 commit 打标签 + GitHub release。

对于维护者而言，按此约定操作即可保证任何一次发布都能通过"标签 + 命名空间 + VERSION_NUMBER"三要素被精确定位和追溯；对于使用者而言，这些标签就是判断"我装的包是从哪份代码构建出来"的唯一可靠依据。

【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime