ONNX 版本¶

ONNX 项目未来将计划大约每四个月发布一次。我们遵循Semver 版本控制方法，并将在每个版本发布基础上作为社区做出决定，是进行主要版本还是次要版本发布。

准备¶

确定新版本的版本号 (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
在发布物流维基中为发布创建新页面。

创建发布分支¶

在 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 操作集版本、ai.onnx.ml 操作集版本和 ai.onnx.training 操作集版本都正确。
创建发布分支
1. 从分支中点击“新建分支”，并选择 main 作为源。
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 域提升操作集版本，供未来操作符添加和更改使用。
  - 例如，这个演示 PR。

将候选版本上传到 TestPyPI¶

重要

等待 PR 设置发布分支的 VERSION_NUMBER 合并并构建，然后再继续。
要将文件推送到 TestPyPI 或 PyPI，请安装 twine（如果您还没有安装）：pip install twine
- 当 twine 命令提示您输入密码时，请使用 API 令牌。您的密码将不起作用。
  - 注意：TestPyPI 和 PyPI 是单独的帐户，因此请确保您在上传时使用的是正确的帐户。
  - 生成 TestPYI API 令牌
  - 生成 PyPI API 令牌
与 PyPI 一样，发布版本只能推送到 TestPyPI 一次。
- 要更新已推送的文件，您必须增加 VERSION_NUMBER，重新构建并推送一个新的 X.Y.Zrc2 等。
- 要测试推送命令，您可以使用 docker 或 podman 创建一个本地 pypi 服务器
  1. 启动服务器 docker run --rm -it --platform linux/amd64 -p 80:8080 pypiserver/pypiserver:latest run -a . -P .
    - 这将启动一个本地 pypiserver，不需要身份验证（任何用户名/密码都可以使用它）。
    - 容器不保存状态。停止并重新启动它将允许您多次推送相同的版本。
  2. 要推送文件
    - 轮子：twine upload --repository-url http://127.0.0.1:80 --verbose -u fake -p fake *.whl
    - 源代码：twine upload --repository-url http://127.0.0.1:80 --verbose -u fake -p fake dist/*
  3. 要从测试服务器拉取并安装
    - pip uninstall -y onnx && pip install --index-url http://127.0.0.1:80/simple/ --pre onnx

推送轮子

从 ONNX GitHub Actions 收集候选版本的轮子文件。
- 对于每个 ONNX GitHub Action
  - ONNX GitHub Action
  - 找到发布分支的运行
    - 或者通过点击“运行工作流”启动运行，选择发布分支，点击“运行工作流”。
  - 点击已完成的运行，滚动到“工件”部分（底部），然后点击“轮子”下载文件。
  - 提取 wheels.zip 文件并将它们的内容合并到一个文件夹中。
手动将生成的轮子上传到 TestPyPI：twine upload --repository testpypi --verbose -u <YOUR_TESTPYPI_USER> <extracted_wheel.zip_folder>/*.whl。
- ONNX 项目的当前所有者需要授予您对项目的访问权限，您才能推送文件。
- 项目名称和版本内置到文件中。

源代码发行版

确保所有 git 子模块都已更新
- git submodule update --init
确保 git 检出是干净的 -
- 运行 git clean -nxd
  - 确保不存在以下自动生成的标头文件。
    - onnx/onnx-operators.pb.cc
    - onnx/onnx-operator.pb.h
    - onnx/onnx.pb.cc
    - onnx/onnx.pb.h
  - 如果存在，请运行 git clean -ixd 并从本地分支中删除这些文件。
生成源代码发行版文件：python -m build --sdist
- 如果您还没有 build 包，请运行 pip install build。
将源代码发行版文件上传到 TestPyPI：twine upload --repository testpypi --verbose -u <YOUR_TESTPYPI_USER> dist/*
- 笔记
  - ONNX 项目的当前所有者需要授予您对项目的访问权限，您才能推送文件。
  - 项目名称和版本内置到文件中。
确认 TestPyPI 包可以安装
- 轮子安装：pip uninstall -y onnx && pip install -i https://test.pypi.org/simple/ --pre onnx
  - 假设预构建的轮子对您的环境可用，否则将开始源代码安装。
- 源代码安装：pip uninstall -y onnx && pip install -i https://test.pypi.org/simple --no-binary onnx --pre onnx

包验证¶

测试 ONNX 本身

测试 PyPI 包安装，使用各种 Python 版本、Protobuf 版本和平台的不同组合。
- 安装 TestPyPI 包后，在发布分支中运行 pytest。
- Python 版本：适用于发布的 Python 版本。
- Protobuf 版本：发布时的最新 Protobuf 版本 + 用于先前发布的 Protobuf 版本

合作伙伴验证

使用 onnxruntime 包进行测试
- 运行来自 test_with_ort.py 的测试脚本，安装 onnxruntime 包。
  - 脚本测试 ONNX 函数，例如 load、checker.check_model 和 shape_inference.infer_shapes，使用 onnxruntime 函数，例如 InferenceSession 和 InferenceSession.run，在特定示例 ONNX 模型上。
外部仓库的开放问题
- 在转换器仓库中创建 GitHub 问题，为他们提供包链接，并让他们有机会在发布公开之前测试发布。
  - 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 分支中修复这些 bug，然后将其 cherry-pick 到发布分支。
- 跟进报告人，以确保问题已解决（并在新的 rc 中得到验证）或推迟到新的发布。

正式发布¶

必须在这一点之前完成验证步骤！这是新返回值的点。

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

设置最终版本号¶

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

创建发布标签¶

草拟发布基于发布分支
- 在确定不再需要更多更改之前，请**不要**点击 Publish release。
  - 如果需要保存和更新更多内容，请使用 Save Draft。
  - 发布将创建新的 git 标签
- 标签：请参阅准备的顶部，以获取要创建的标签。
- 目标：刚刚切断的发布分支
- 先前标签：选择先前发布的标签。
- 写入
  - 使用先前发布作为模板
  - 使用来自发布物流 wiki 的信息，该信息应该在分支切断之前创建。
  - 添加自 wiki 编写以来合并到发布中的任何其他提交。
- .tar.gz 和 .zip 将在发布发布后自动生成。

上传到官方 PyPI¶

注意：¶

一旦将包上传到 PyPI，**您就无法在同一个 PyPI 实例上覆盖它**。
- 在上传到 PyPI 之前，请确保 TestPyPI 上一切正常**
PyPI 与 TestPyPI 具有单独的登录名、密码和 API 令牌，但流程相同。ONNX PyPI 所有者需要授予访问权限等。

按照上述将发布候选版本上传到 TestPyPI 中的“轮子”和“源代码分发”步骤操作，但以下更改:

在您的 PyPI 帐户（**API 令牌**部分）中，创建用于上传 onnx 轮子的 onnx 范围的新 API 令牌。
- 在推送发布的轮子和源代码后，删除创建的令牌。
上传时，从 twine 命令中删除 --repository testpypi。
验证上传时，从 pip 命令中删除 -i https://test.pypi.org/simple/ 和 --pre。

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）。

合并到主分支

如果直接在发布分支中进行了紧急更改，请将发布分支合并回主分支。
如果合并到发布分支（在切断后）的所有 PR 都是来自主分支的 cherry-pick，则合并 PR 将显示为空，此步骤不需要执行。

删除 PyPI 上的旧 onnx-weekly 包

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