ONNX Releases

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

  • Reach out to the SIG Arch/Infra leads to confirm whether the required status checks for the release branches are still valid and up to date, and whether any rely on outdated hardcoded runner image versions that may need updatingCheck whether the ‘required checks’ for the release branches are still up to date or need to be adjusted: ‘Branches’ -> ‘Branch protection rules’

  • Determine version (X.Y.Z) for the new release

    • Discuss in Slack channel for Releases (https://lfaifoundation.slack.com/archives/C018VGGJUGK)

    • For (v.X.Y.Z), if release is to be 1.16.0,

      • X=1, Y=16, Z=0

      • The new branch will be rel-1.16.0

        • Branch protections rules are automatically applied to branches following this format.

      • The new tag will be v1.16.0

  • Create new page for the release in Release logistics wiki

  • Before creating a release branch, it is highly recommended to have in mind to compile preliminary release notes — ideally maintained in a shared location such as the release wiki page. These notes should include a clear summary of the new features, a list of bug fixes, any known issues, and especially any deprecations or removals, with links to relevant tickets or documentation where applicable. Having this information ready ensures that the team can confidently and promptly create a rc1 (release candidate 1) immediately after the branch is cut, without delays. Acting quickly at this stage also helps to reduce the need for parallel work on both the main and release branches, minimizing merge conflicts, duplicated effort, and coordination overhead. This practice supports a smoother, more transparent release process.

    • To generate good release notes, it is helpful if pull requests have meaningful names and corresponding labels. Labels can also be added retrospectively to PRs that have already been merged.

    • The labels used can be found here

    • The preliminary release notes one gets if one drafts a release on GitHub.

Create Release Branch

  • In main branch, before creating the release branch:

    1. Bump the LAST_RELEASE_VERSION in version.h.

      • Set to X.Y.Z, which is same as the release branch you are currently creating.

      • After the release branch is cut, VERSION_NUMBER in main will be increased to the next future version.

    2. Make sure the release version, IR version, ai.onnx opset version, ai.onnx.ml opset version, and ai.onnx.training opset version are correct for the new release in ONNX proto files, Versioning.md, schema.h, helper.py, and helper_test.py.

  • Create a release branch

    1. Click “New branch” from branches and choose main as Source.

    2. Make sure all tests pass on the new branch.

  • After cutting the release branch:

    1. Create PR to set VERSION_NUMBER file in main to the next future release, X.Y+1.0.

    2. Create PR to set VERSION_NUMBER file in the new release’s branch to X.Y.Zrc1.

      • For example the first release candidate for 1.16.0 would be 1.16.0rc1

    3. 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.

Upload release candidate to TestPyPI without offline steps (starting with onnx version 1.19)

  • Go to “Actions” -> select “Create Releases” -> Push the button “Run workflow” with the following config:

RunWorkflow

RC-Candidates

create_releases_overview_jobs

  • All artifacts of the single runs could be found associated to the job

create_releases_artifact_overview

  • Before the final merge, it must be confirmed manually via the set up deployment environments.

Package verification

Partner Validation

Official Release

Validation steps must be completed before this point! This is the point of new return.

  • git tags should not be changed once published

  • Once pushed to PyPI there is no way to update the release. A new release must be made instead

Set final version number

  • Create PR to remove “rcX” suffix from VERSION_NUMBER file in the new release’s branch.

Create release tag

  • Draft a release based on the release branch:

    • DO NOT click Publish release until you are sure no more changes are needed.

      • Use Save Draft if need to save and update more later.

      • Publishing will create the new git tag

    • Tag: See top of Preparation for tag to create.

    • Target: The release branch that was just cut

    • Previous tag: Select the previous release.

    • Write:

      • Use previous releases as a template

      • Use information from Release logistics wiki which should have been created prior to branch cut.

      • Add any additional commits that merged into the release in since wiki was written.

    • .tar.gz and .zip will be auto-generated after publishing the release.

Upload to Official PyPI

  • Starting with the release of 1.19, the final release will also be pushed to pypi via Github “Action” -> “Create releases” (see above). Use the following config for official release:

RunWorkflow_Final

NOTES:

  • 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**

  • PyPI has separate logins, passwords, and API tokens from TestPyPI but the process is the same. An ONNX PyPI owner will need to grant access, etc.

After PyPI Release

Announce

Update conda-forge package with the new ONNX version

Conda builds of ONNX are done via conda-forge/onnx-feedstock, which runs infrastructure for building packages and uploading them to conda-forge.

Merge into main branch

  • Check which changes to the release branch are also relevant for main:

    • If urgent changes were made directly into the release branch, merge the release branch back into main branch.

    • If all PRs merged into the release branch (after it was cut) were cherry-picks from main, the merge PR will show as empty and this step is not needed.

Remove old onnx-weekly packages on PyPI

  • Remove all onnx-weekly packages from PyPI for the just released version to save space.

  • Steps:

    • Go to PyPI onnx-weekly/releases

      • This is a separate project than the onnx releases so you may need to request access from an owner

    • Click target package -> Options -> Delete.

Remove old release-candidate packages on PyPI

  • Remove onnx-release-candidate packages from PyPI up to at least the time specified by the previous release version to save space.

  • Steps:

    • Go to PyPI onnx-weekly/releases

      • This is a separate project than the onnx releases so you may need to request access from an owner

    • Click target package -> Options -> Delete.