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 opset 版本、ai.onnx.ml opset 版本和 ai.onnx.training opset 版本正確無誤。
建立發行分支
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 網域更新 opset 版本，以便未來新增和變更運算符時使用。
  - 例如，這個示範 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. 若要推送檔案
    - 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

從 ONNX Github Actions 為候選發行版本收集 wheel 檔案。
- 針對每個 ONNX GitHub Action
  - ONNX GitHub Action
  - 尋找發行分支的執行
    - 或者，點擊「執行工作流程」來開始執行，挑選發行分支，點擊「執行工作流程」
  - 點擊已完成的執行，捲動到「成品」區段 (底部)，然後點擊「wheels」以下載檔案
  - 解壓縮 wheels.zip 檔案，並將其內容合併到單一資料夾中
將產生的 wheels 手動上傳至 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 套件可以安裝
- 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 本身

使用各種 Python 版本、Protobuf 版本和平台的組合測試 PyPI 套件安裝。
- 安裝 TestPyPI 套件後，在發佈分支中執行 pytest。
- Python 版本：適用於此發佈的 Python 版本。
- Protobuf 版本：發佈時最新的 Protobuf 版本 + 用於先前發佈的 Protobuf 版本

合作夥伴驗證

使用 onnxruntime 套件進行測試
- 使用已安裝的 onnxruntime 套件執行來自 test_with_ort.py 的測試腳本。
  - 該腳本使用 onnxruntime 函數（如 InferenceSession 和 InferenceSession.run）在某些範例 ONNX 模型上測試 ONNX 函數，如 load、checker.check_model 和 shape_inference.infer_shapes。
外部儲存庫的未解決問題
- 在轉換器儲存庫中建立 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 分支中修復錯誤，然後將其 cherry-pick 到發佈分支中。
- 與報告者聯絡以確保問題已解決（並在新 RC 中驗證）或延遲到新的發佈版本。

正式發佈¶

驗證步驟必須在此點之前完成！這是新返回點。

git 標籤一旦發佈就不應更改
一旦推送到 PyPI，就無法更新發佈版本。必須改為建立新的發佈版本

設定最終版本號碼¶

建立 PR 以從新發佈版本分支中的 VERSION_NUMBER 檔案中移除「rcX」後綴。

建立發佈標籤¶

根據發佈分支起草發佈
- 在確定不需要更多變更之前，請勿點擊 發佈發佈版本。
  - 如果需要儲存並稍後更新更多內容，請使用 儲存草稿。
  - 發佈將建立新的 git 標籤
- 標籤：請參閱準備頂部以建立標籤。
- 目標：剛切割的發佈分支
- 先前的標籤：選取先前的發佈版本。
- 撰寫
  - 使用先前的發佈版本作為範本
  - 使用來自發佈物流維基的資訊，該資訊應在分支切割之前建立。
  - 新增自維基撰寫以來合併到發佈中的任何其他提交。
- 在發佈版本後，將會自動產生 .tar.gz 和 .zip。

上傳到官方 PyPI¶

注意：¶

一旦將套件上傳到 PyPI，您就無法在同一個 PyPI 實例上覆寫它。
- 請確保在上傳到 PyPI 之前，TestPyPI 上的一切都正常**
PyPI 有與 TestPyPI 分開的登入、密碼和 API 權杖，但流程相同。ONNX PyPI 所有者需要授予存取權等等。

請按照上面將發佈候選版本上傳到TestPyPI中的Wheels和原始碼發佈步驟進行，並進行以下變更

在您的 PyPI 帳戶 (API 權杖區段) 中建立一個新的 onnx 範圍 API 權杖，用於上傳 onnx wheel。
- 在推送發佈版本的 wheels 和原始碼後，移除建立的權杖。
上傳時，從 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 發佈版本不同的獨立專案，您可能需要向擁有者請求存取權限。
- 點擊目標套件 -> 選項 -> 刪除。