ONNX 发布¶

ONNX 项目将计划大致以四个月的周期发布。我们遵循 Semver 版本控制方法，并将作为一个社区在每次发布时决定是进行主要版本发布还是次要版本发布。

准备工作¶

联系 SIG Arch/Infra 负责人，确认发布分支所需的 Status Check 是否仍然有效且最新，以及是否有任何依赖可能需要更新的过时硬编码 runner 镜像版本。检查发布分支的“所需检查”是否仍然最新或需要调整：“Branches”->“Branch protection rules”
确定新发布的版本 (X.Y.Z)
- 在发布 Slack 频道中讨论 (https://lfaifoundation.slack.com/archives/C018VGGJUGK)
- 对于 (v.X.Y.Z)，如果发布版本是 1.16.0，
  - X=1, Y=16, Z=0
  - 新分支将是 rel-1.16.0
    - 分支保护规则将自动应用于遵循此格式的分支。
  - 新标签将是 v1.16.0
在发布物流维基中为发布创建新页面
在创建发布分支之前，强烈建议准备一份**初步发布说明**——最好维护在一个共享位置，例如**发布维基页面**。这些说明应包括**新功能**的清晰摘要、**错误修复**列表、任何**已知问题**，特别是任何**弃用或移除**，并附带相关工单或文档的链接（如适用）。准备好这些信息可确保团队在分支切出后能够自信而及时地立即创建 rc1（发布候选版本 1），而不会出现延迟。在此阶段迅速行动还有助于**减少主分支和发布分支并行工作的需要**，从而最大限度地减少合并冲突、重复工作和协调开销。这种做法支持更顺畅、更透明的发布流程。
- 为了生成良好的发布说明，如果拉取请求具有有意义的名称和相应的标签，将会很有帮助。标签也可以追溯添加到已合并的 PR 中。
- 使用的标签可以在此处找到。
- 如果在 GitHub 上起草发布，将获得初步发布说明。

创建发布分支¶

在 main 分支中，在创建发布分支之前
1. 更新 version.h 中的 LAST_RELEASE_VERSION。
  - 将其设置为 X.Y.Z，这与您当前正在创建的发布分支相同。
  - 发布分支切出后，main 中的 VERSION_NUMBER 将增加到下一个未来版本。
2. 确保 ONNX proto 文件、Versioning.md、schema.h、helper.py 和 helper_test.py 中的发布版本、IR 版本、ai.onnx opset 版本、ai.onnx.ml opset 版本以及 ai.onnx.training opset 版本对于新发布都是正确的。
创建发布分支
1. 从 branches 点击 “New branch” 并选择 main 作为 Source。
2. 确保新分支上的所有测试都通过。
切出发布分支后
1. 创建 PR 以将 main 中的 VERSION_NUMBER 文件设置为下一个未来版本 X.Y+1.0。
2. 创建 PR 以将新发布分支中的 VERSION_NUMBER 文件设置为 X.Y.Zrc1。
  - 例如，1.16.0 的第一个发布候选版本将是 1.16.0rc1
3. 在 onnx/defs/operator_sets.h 和 onnx/defs/schema.h 中提升 ai.onnx 领域的 opset 版本，以供未来的操作符添加和更改使用。
  - 例如，此演示 PR。

将发布候选版本上传到 PyPI¶

转到 “Actions” -> 选择 “Create Releases” -> 点击 “Run workflow” 按钮，使用以下配置

RC-Candidates

发布到 https://pypi.ac.cn/（从 onnx 1.19.2 开始，之前是 test.pypi.org）
Build-mode: Release
此按钮触发不同操作系统的构建

所有独立运行的工件都可以在与任务关联的地方找到

在最终合并之前，必须通过设置的部署环境手动确认。

包验证¶

合作伙伴验证

用户应使用 pip install onnx=={rc version} 安装 rc-packages
使用 onnxruntime 包进行测试
- 使用已安装的 onnxruntime 包运行 test_with_ort.py 中的测试脚本。
  - 该脚本在某些示例 ONNX 模型上测试 ONNX 函数，如 load、checker.check_model 和 shape_inference.infer_shapes，以及 onnxruntime 函数，如 InferenceSession 和 InferenceSession.run。
为外部仓库开放 Issue
- 在转换器仓库中创建 GitHub issue，向他们提供包链接和在发布公开之前测试发布的机会。
  - https://github.com/microsoft/onnxruntime
    - 示例：https://github.com/microsoft/onnxruntime/issues/19783
    - 注意：他们的仓库中存在 How_To_Update_ONNX_Dev_Notes，记录了如何引入新的 ONNX 版本。
  - https://github.com/pytorch/pytorch
    - 示例：https://github.com/pytorch/pytorch/issues/121258
  - https://github.com/onnx/tensorflow-onnx
    - 示例：https://github.com/onnx/tensorflow-onnx/issues/2310
  - https://github.com/onnx/onnx-tensorrt
    - 示例：https://github.com/onnx/onnx-tensorrt/issues/956
  - https://github.com/onnx/sklearn-onnx
    - 示例：https://github.com/onnx/sklearn-onnx/issues/1079
  - https://github.com/microsoft/onnxconverter-common
    - 示例：https://github.com/microsoft/onnxconverter-common/issues/277
  - https://github.com/onnx/onnxmltools
    - 示例：https://github.com/onnx/onnxmltools/issues/685
  - https://github.com/Quantco/spox
  - https://github.com/conda-forge/onnx-feedstock
如果发现问题，则应在 onnx main 分支中修复错误，然后将其 cherry-pick 到发布分支中。
- 跟进报告者以确保问题已解决（并在新的 rc 中验证）或推迟到新的发布。

正式发布¶

在此之前必须完成验证步骤！这是没有回头路的时候。

git 标签一旦发布就不应更改
一旦推送到 PyPI，就无法更新发布。必须重新创建一个新的发布

设置最终版本号¶

创建 PR，从新发布分支的 VERSION_NUMBER 文件中删除 “rcX” 后缀。

创建发布标签¶

基于发布分支起草一个发布
- 在确定不再需要更改之前，请勿点击 Publish release。
  - 如果需要保存并稍后更新更多内容，请使用 Save Draft。
  - 发布将创建新的 git 标签
- 标签：请参阅准备工作顶部以了解要创建的标签。
- 目标：刚刚切出的发布分支
- 上一标签：选择上一发布。
- 撰写
  - 使用以前的发布作为模板
  - 使用发布物流维基中的信息，该维基应在分支切出之前创建。
  - 添加自维基撰写以来已合并到发布中的任何其他提交。
- 发布后将自动生成 .tar.gz 和 .zip 文件。

上传到官方 PyPI¶

从 1.19 版本发布开始，最终发布也将通过 Github “Action” -> “Create releases”（见上文）推送到 pypi。官方发布请使用以下配置

注意：¶

一旦软件包上传到 PyPI，**您不能在同一个 PyPI 实例上覆盖它**。
- 请确保在上传到 PyPI 之前 TestPyPI 上的所有内容都正常**
PyPI 与 TestPyPI 的登录名、密码和 API 令牌是分开的，但过程相同。ONNX PyPI 所有者需要授予访问权限等。

PyPI 发布后¶

宣布

Slack
- 发布在 onnx-release 和 onnx-general 频道中。
通过电子邮件列表通知 ONNX 合作伙伴
ONNX 新闻发布
- 更新 news.json，请参阅示例 news.json PR

使用新的 ONNX 版本更新 conda-forge 包

ONNX 的 Conda 构建通过 conda-forge/onnx-feedstock 完成，该仓库运行用于构建包并将其上传到 conda-forge 的基础设施。

发布在 https://github.com/onnx/onnx/releases 可用后的几个小时内，regro-cf-autotick-bot 应该会自动创建一个 PR。
如果自动 PR 出现构建失败
1. 创建 conda-forge/onnx-feedstock 的个人 fork
2. 基于自动 PR 分支创建个人分支
3. 解决构建问题
4. 基于您的分支提交替换 PR
- 示例：https://github.com/conda-forge/onnx-feedstock/pull/116
如果未创建自动 PR，则需要手动提交 PR
- 示例：https://github.com/conda-forge/onnx-feedstock/pull/50
- 注意：使用来自 https://github.com/onnx/onnx/releases 的发布 tar.gz 文件的 sha256 哈希值 (sha256sum onnx-X.Y.Z.tar.gz)。

合并到主分支

检查发布分支中的哪些更改也与 main 相关
- 如果直接在发布分支中进行了紧急更改，请将发布分支合并回主分支。
- 如果合并到发布分支（切出后）的所有 PR 都是从 main cherry-pick 的，则合并 PR 将显示为空，此步骤不需要。

删除 PyPI 上旧的 onnx-weekly 包

从 PyPI 中删除所有针对刚发布的版本的 onnx-weekly 包，以节省空间。
步骤
- 转到 PyPI onnx-weekly/releases
  - 这是一个与 onnx 发布分开的项目，因此您可能需要向所有者请求访问权限
- 点击目标包 -> Options -> Delete。

删除 PyPI 上旧的发布候选包

从 PyPI 中删除 onnx-release-candidate 包，至少直到由上一个发布版本指定的时间，以节省空间。
步骤
- 转到 PyPI onnx-weekly/releases
  - 这是一个与 onnx 发布分开的项目，因此您可能需要向所有者请求访问权限
- 点击目标包 -> Options -> Delete。