The ONNX project, going forward, will plan to release roughly on a four month cadence. We follow the Semver versioning approach and will make decisions as a community on a release by release basis on whether to do a major or minor release.

Preparation

• Install Twine, a utility tool to interact with PyPI. Do - pip install twine

• Get hold of the username and password for the ‘onnx’ PyPI account. Release manager should get onnx pypi account credentials from steering committee or from previous release manager.

• Pick a release tag (v.1.X.X) for the new release through mutual consent – Slack channel for Releases (https://lfaifoundation.slack.com/archives/C018VGGJUGK)

• Prepare a change log for the release –

  • git log --pretty=format:"%h - %s" <tag of the previous release>...<new tag>

  • And draft a new release statement - https://github.com/onnx/onnx/releases listing out the new features and bug fixes, and potential changes being introduced in the release.

• Before creating the release branch, increase VERSION_NUMBER in the main branch. The following files will be updated: VERSION_NUMBER file and version.h

• Please use target VERSION_NUMBER with rc (e.g., 1.x.0rc1) to test TestPyPI in advance before using target VERSION_NUMBER (e.g., 1.x.0) for final release.

• Make sure that the IR version number and opset version numbers are up-to-date in ONNX proto files, Versioning.md, schema.h, helper.py and helper_test.py. Please note that this also needs to be happened in the main branch before creating the release branch.

• Create a release branch (please use rel-* as the branch name) from main. Checkout the release tag in a clean branch on your local repo. Make sure all tests pass on that branch.

• Create an issue in onnxruntime repo. See a sample issue for details. The issue is to request onnxruntime to update with the onnx release branch and to run all CI and packaging pipelines (How_To_Update_ONNX_Dev_Notes). It is possible that onnx bugs are detected with onnxruntime pipeline runs. In such case the bugs shall be fixed in the onnx main branch and cherry-picked into the release branch. Follow up with onnxruntime to ensure the issue is resolved in time before onnx release.

Upload to TestPyPI

Wheels

• In release branch update the version number in file [VERSION_NUMBER] to something like 1.x.0rc1 as release candidate for verification before finally using the targeted version number for this release.

• Windows

  • Use GitHub Action (.github/workflows/release_win.yml) under onnx repo to produce wheels for Windows.

• Linux

  • Use GitHub Action (.github/workflows/release_linux_x86_64.yml) and (.github/workflows/release_linux_aarch64.yml) under onnx repo to produce x64/aarch64 wheels for Linux.

• Mac

  • Use GitHub Action (.github/workflows/release_mac.yml) under onnx repo to produce wheels for Mac.

• After success, upload the produced wheels manually to TestPyPI: twine upload --verbose *.whl --repository-url https://test.pypi.org/legacy/ -u PYPI_USERNAME -p PYPI_PASSWORD.

Source Distribution

• Make sure all the git submodules are updated

  • git submodule update --init

• Make sure the git checkout is clean –

  • Do git clean -nxd and make sure that none of the auto-generated header files like the following are not present.

    • onnx/onnx-operators.pb.cc

    • onnx/onnx-operator.pb.h

    • onnx/onnx.pb.cc

    • onnx/onnx.pb.h

  • If they are present run git clean -ixd and remove those files from your local branch

• Do python setup.py sdist to generate the source distribution.

• Do twine upload dist/* --repository-url https://test.pypi.org/legacy/ -u PYPI_USERNAME -p PYPI_PASSWORD to upload it to the test instance of PyPI.

TestPyPI package verification

Test ONNX itself

• Test the PyPI package installation with different combinations of various Python versions, Protobuf versions and platforms.

  • Python versions : Applicable python versions for the release.

  • Protobuf versions : Latest protobuf version at the time of the release + protobuf version used for previous release

  • Utilize the following matrix to check:

    	3.7	3.8	3.9	3.10
    Linux
    Windows
    Mac

• After installing the PyPI package, run pytest in the release branch.

Partner Validation

• Test with onnxruntime package: To test the interaction with onnxruntime, use ONNX functions like load, checker.check_model, shape_inference.infer_shapes, save with onnxruntime functions like InferenceSession and InferenceSession.run on certain example ONNX model. For example, run the test script from test_with_ort.py with installed onnxruntime package.

• Test with ONNX converters: Create GitHub issues in converters repos to provide them the package links and have them test the TestPyPI packages.

  • https://github.com/pytorch/pytorch

  • https://github.com/onnx/onnx-tensorflow

  • https://github.com/onnx/tensorflow-onnx

  • https://github.com/onnx/sklearn-onnx

  • https://github.com/onnx/onnxmltools

  • https://github.com/onnx/keras-onnx

  • https://github.com/onnx/onnx-tensorrt

  • https://github.com/onnx/onnx-coreml

Source distribution verification

• Test the source distribution by doing pip install --index-url https://test.pypi.org/simple --no-binary onnx onnx in a new environment.

Upload to official PyPI

NOTE: Once the packages are uploaded to PyPI, you cannot overwrite it on the same PyPI instance. Please make sure everything is good on TestPyPI before uploading to PyPI

Wheels

• Windows/Linux/Mac

  • Same as TestPyPI, use twine upload --verbose *.whl --repository-url https://upload.pypi.org/legacy/ -u PYPI_USERNAME -p PYPI_PASSWORD instead.

Source Distribution

• Follow the same process in TestPyPI to produce the source distribution.

• Use twine upload --verbose dist/* --repository-url https://upload.pypi.org/legacy/ instead to upload to the official PyPI.

• Test with pip install --no-binary onnx onnx

After PyPI Release

Release summary

• Upload the source distribution, .tar.gz and .zip, in the release summary.

• Create release in github with the right tag and upload the release summary along with .tar.gz and .zip

Announce

• Announce in slack, for instance, onnx-general channel.

• Notify ONNX partners like converter team and runtime team.

• Create a news by updating js/news.json to announce ONNX release under onnx/onnx.github.io repo. For instance: https://github.com/onnx/onnx.github.io/pull/83.

Deploy released content to document website

• To update the website https://onnx.ai/onnx/ with the released content, manually deploy released content to document website by running pages.yml.

• Steps: start actions -> Workflows -> Deploy static content to Pages -> Run workflow -> Use workflow from “rel-*” -> Run workflow.

Update conda-forge package with the new ONNX version

• Conda builds of ONNX are done via conda-forge, which runs infrastructure for building packages and uploading them to conda-forge. If it does not happen automatically, you need to submit a PR to https://github.com/conda-forge/onnx-feedstock (see https://github.com/conda-forge/onnx-feedstock/pull/1/files or https://github.com/conda-forge/onnx-feedstock/pull/50/files for example PRs) You will need to have uploaded to PyPI already, and update the version number and tarball hash of the PyPI uploaded tarball.

Merge into main branch

• After everything above is done, merge the release branch into the main branch to make it consistent. This step is needed only when there are urgent changes that are made directly into the release branch. The main branch does not have these needed changes. In all other circumstances, the merge PR shall show as empty so nothing needs to be merged.

Remove old onnx-weekly packages on TestPyPI

• Once ONNX has been released on PyPI, remove all previous versions of onnx-weekly package on TestPyPI to save space.

• Steps: Login and go here -> Choose target package -> Options -> Delete.

Bump opset version for ai.onnx

• Bump opset version for ai.onnx domain in onnx/defs/operator_sets.h and onnx/defs/schema.h for use by future operator additions and changes. For example, this demo PR.