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

  • 在发布物流 Wiki 中为该发布创建新页面

创建发布分支

  • 在 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. 从 分支 中点击“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 版本，以供未来算子添加和更改使用。

将发布候选版本上传到 TestPyPI

重要

  • **等待** 设置发布分支 VERSION_NUMBER 的 PR 合并并构建完成后再继续。

  • 要将文件推送到 TestPyPI 或 PyPI，如果尚未安装 twine，请安装它：pip install twine

    • 当 twine 命令提示输入密码时，请使用 API token。您的密码将无法使用。

  • 与 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. 推送文件

        • wheels: 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

推送 Wheels

  1. 从 ONNX Github Actions 中收集发布候选版本的 wheel 文件。

    • ONNX GitHub Action

    • 找到发布分支的运行

      • 或者通过点击“Run workflow”，选择发布分支，点击“Run Workflow”来启动运行

      • 点击已完成的运行，滚动到底部找到“Artifacts”部分，点击“wheels”下载文件

      • 解压 wheels.zip 文件，并将其内容合并到一个文件夹中

  2. 手动将生成的 wheels 上传到 TestPyPI：twine upload --repository testpypi --verbose -u <YOUR_TESTPYPI_USER> <extracted_wheel.zip_folder>/*.whl。

    • 在推送文件之前，ONNX 项目的当前所有者需要授予您访问权限。

    • 项目名称和版本内置在文件中。

源码分发包

  1. 确保所有 git 子模块已更新

    • git submodule update --init

  2. 确保 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 并从本地分支中删除这些文件

  3. 生成源码分发文件：python -m build --sdist

    • 如果尚未安装 build 包，运行 pip install build。

  4. 将源码分发文件上传到 TestPyPI：twine upload --repository testpypi --verbose -u <YOUR_TESTPYPI_USER> dist/*

    • 注意

      • 在推送文件之前，ONNX 项目的当前所有者需要授予您访问权限。

      • 项目名称和版本内置在文件中。

  5. 确认 TestPyPI 包可以安装

    • Wheel 安装：pip uninstall -y onnx && pip install -i https://test.pypi.org/simple/ --pre onnx

      • 假设您的环境有预构建的 wheel 包可用，否则将开始源码安装。

    • 源码安装：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 版本

合作伙伴验证

正式发布

在此之前必须完成验证步骤！这是关键点。

  • git 标签一旦发布就不应更改

  • 一旦推送到 PyPI，就无法更新该发布。必须创建一个新的发布来代替。

设置最终版本号

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

创建发布标签

  • 基于发布分支起草发布

    • 在确定不需要更多更改之前，请**不要**点击 Publish release。

      • 如果需要稍后保存和更新更多内容，请使用 Save Draft。

      • 发布后将创建新的 git 标签

    • 标签：有关要创建的标签，请参阅准备工作的顶部。

    • 目标：刚切出的发布分支

    • 上一标签：选择上一个发布。

    • 撰写

      • 使用之前的发布作为模板

      • 使用来自发布物流 Wiki 的信息，该 Wiki 应在分支切出前创建。

      • 添加自 wiki 撰写以来合并到该发布中的任何额外提交。

    • 发布后将自动生成 .tar.gz 和 .zip 文件。

上传到正式 PyPI

注意：

  • 一旦包上传到 PyPI，**您无法在同一 PyPI 实例上覆盖它**。

    • **在上传到 PyPI 之前，请确保 TestPyPI 上的一切都正常**

  • PyPI 的登录信息、密码和 API token 与 TestPyPI 是分开的，但过程相同。ONNX PyPI 所有者需要授予访问权限等。

按照上面将发布候选版本上传到 TestPyPI 中的 **Wheels** 和 **源码分发包** 步骤进行，并做如下更改

  • 在您的 PyPI 账户（**API tokens** 部分）中创建一个 onnx 范围的新 API token 用于上传 onnx wheel 包。

    • 推送该发布的 wheel 包和源码包后，移除创建的 token。

  • 上传时，从 twine 命令中移除 --repository testpypi。

  • 验证上传时，从 pip 命令中移除 -i https://test.pypi.org/simple/ 和 --pre。

PyPI 发布后

公告

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

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

合并到 main 分支

  • 如果直接在发布分支中进行了紧急更改，请将发布分支合并回 main 分支。

  • 如果合并到发布分支（切出后）的所有 PR 都是从 main 分支 cherry-pick 的，则合并 PR 将显示为空，此步骤不需要。

移除 PyPI 上的旧 onnx-weekly 包

  • 移除 PyPI 上针对刚刚发布的版本的所有onnx-weekly 包，以节省空间。

  • 步骤

    • 前往 PyPI onnx-weekly/releases

      • 这是一个与 onnx 发布分开的项目，因此您可能需要向所有者请求访问权限

    • 点击目标包 -> 选项 -> 删除。

移除 PyPI 上的旧发布候选包

  • 移除 PyPI 上至少早于上一个发布版本指定时间的onnx 发布候选包，以节省空间。

  • 步骤

    • 前往 PyPI onnx-weekly/releases

      • 这是一个与 onnx 发布分开的项目，因此您可能需要向所有者请求访问权限

    • 点击目标包 -> 选项 -> 删除。