發行版本#

以下指南包含關於如何準備 NumPy 發行版本的詳細資訊。

如何準備發行版本#

這些指示概述了為 NumPy 建置二進位發行版本所需的事項。

目前的建置與發行資訊#

有用的資訊可以在以下位置找到

原始碼樹狀結構
- INSTALL.rst
- pavement.py
NumPy 文件
發行腳本
- numpy/numpy-vendor

支援的平台與版本#

NEP 29 概述了支援的 Python 版本；對於 2020 年上半年，這將是 Python >= 3.6。每次我們將程式碼合併到主分支時，都會針對所有這些版本測試 NumPy。二進位安裝程式可能適用於這些版本的子集（見下文）。

OS X

支援 OS X 版本 >= 10.9，關於 Python 版本支援，請參閱 NEP 29。我們為 OSX 建置二進位 wheel 檔案，這些檔案與 Python.org Python、系統 Python、homebrew 和 macports 相容 - 有關詳細資訊，請參閱此 OSX wheel 建置摘要。
Windows

我們在 Windows 上建置 32 位元和 64 位元 wheel 檔案。支援 Windows 7、8 和 10。我們使用 mingw-w64 工具鏈、cibuildwheels 和 GitHub Actions 建置 NumPy。

Linux

我們為 NumPy 建置和發布 manylinux2014 wheel 檔案。許多 Linux 發行版都包含它們自己的 NumPy 二進位建置版本。
BSD / Solaris

未提供二進位檔案，但已報告在 Solaris 和 BSD 上成功建置。

工具鏈#

我們在雲端基礎架構上建置所有 wheel 檔案 - 因此此編譯器列表僅供參考和在本機除錯建置使用。請參閱 .travis.yml 腳本，該腳本位於 numpy wheels 儲存庫中，以取得使用 multibuild 的建置配方過時來源。

編譯器#

使用的 gcc 版本與 Python 本身在每個平台上建置時所用的版本相同。目前這表示

OS X 在 travis 上的建置目前使用 clang。看起來可以安全地從 travis-ci OSX 10.9 VM 建置適用於 OSX >= 10.6 的二進位 wheel 檔案，當針對來自 Python.org 安裝程式的 Python 進行建置時；
Windows 建置使用 mingw-w64 工具鏈；
Manylinux2014 wheel 檔案使用 Manylinux Docker 映像檔上提供的 gcc。

您將需要 Cython 來建置二進位檔案。Cython 將 NumPy 發行版中的 .pyx 檔案編譯為 .c 檔案。

OpenBLAS#

所有 wheel 檔案都連結到透過 openblas-libs 儲存庫提供的 OpenBLAS 版本。共用物件 (或 DLL) 與 wheel 檔案一起發布，並重新命名以防止與檔案系統中可能存在的其他 OpenBLAS 共用物件發生名稱衝突。

建置原始碼封存檔與 wheel 檔案#

NumPy wheel 檔案和 sdist 現在使用 cibuildwheel 與 github actions 建置。

建置文件#

我們不再建置 PDF 檔案。所有需要的只是

virtualenv (pip)。

其他需求將在文件建置過程中自動滿足。

上傳到 PyPI#

上傳唯一需要的應用程式是

twine (pip)。

您還需要 PyPI 權杖，最好將其保存在金鑰環中。請參閱 twine 金鑰環文件，以了解如何執行此操作。

產生作者/PR 列表#

您將需要個人存取權杖 https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/，以便腳本可以存取 github NumPy 儲存庫。

gitpython (pip)
pygithub (pip)

發行內容#

Wheels 我們目前在 Windows、OSX 和 Linux 上支援 Python 3.8-3.10。
- Windows：使用 Github actions 建置的 32 位元和 64 位元 wheel 檔案；
- OSX：使用 Github actions 建置的 x64_86 和 arm64 OSX wheel 檔案；
- Linux：使用 Github actions 建置的 x64_86 和 aarch64 Manylinux2014 wheel 檔案。
其他發行說明和變更日誌
原始碼發行版 我們以 .tar.gz 格式建置原始碼發行版。

發行流程#

同意發行時程#

典型的發行時程是一個 beta 版、兩個候選發行版和最終發行版。最好先在郵件列表中討論時程，以便人們及時提交他們的 commit、合併文件 wiki 編輯等。設定日期後，建立新的 maintenance/x.y.z 分支，在主分支中為下一個版本新增空的發行說明，並更新 Trac 里程碑。

確保目前分支正確地建置套件#

當 PR 標頭以 REL 開頭時，CI 會建置 wheel 檔案。您在發行前的最後一個 PR 應該如此標記，並且所有測試都應該通過。您也可以執行

git clean -fxdq
python setup.py bdist_wheel
python setup.py sdist

有關建置流程本身的詳細資訊，最好閱讀下面的逐步指示。

注意

以下步驟針對 beta 版、候選發行版和最終發行版重複執行。

檢查棄用#

在建立發行分支之前，應檢查所有應移除的已棄用程式碼是否已實際移除，以及所有新的棄用是否在文件字串或棄用警告中說明程式碼將在哪個版本中移除。

檢查 C API 版本號碼#

C API 版本需要在三個位置追蹤

numpy/_core/meson.build
numpy/_core/code_generators/cversions.txt
numpy/_core/include/numpy/numpyconfig.h

此過程分為三個步驟。

如果 API 已變更，請在 numpy/core/meson.build 中遞增 C_API_VERSION。只有在針對目前 API 編譯的任何程式碼都將與上次發行的 NumPy 版本向後相容時，API 才不會變更。對 C 結構的任何變更或對公開介面的新增都將使新的 API 無法向後相容。
如果第一步中的 C_API_VERSION 已變更，或者如果 API 的雜湊已變更，則需要更新 cversions.txt 檔案。若要檢查雜湊，請執行腳本 numpy/_core/cversions.py 並記下列印的 API 雜湊。如果該雜湊與 numpy/_core/code_generators/cversions.txt 中的最後一個雜湊不符，則雜湊已變更。使用適當的 C_API_VERSION 和雜湊，將新條目新增至 cversions.txt。如果 API 版本未變更，但雜湊不同，您將需要註解掉該 API 版本的前一個條目。例如，在 NumPy 1.9 中新增了註解，這變更了雜湊，但 API 與 1.8 中的相同。雜湊用作 API 變更的檢查，但它並非決定性的。

如果步驟 1 和 2 正確完成，則編譯發行版本不應發出「在建置開始時偵測到 API 不符」的警告。
numpy/_core/include/numpy/numpyconfig.h 將需要新的 NPY_X_Y_API_VERSION 巨集，其中 X 和 Y 是發行版本的主要和次要版本號碼。只有在 include 檔案中的某些函式或巨集已棄用時，才需要從先前版本增加提供給該巨集的值。

numpy/_core/meson.build 中的 C ABI 版本號碼僅應針對主要發行版本更新。

檢查發行說明#

使用 towncrier 建置發行說明並提交變更。這將移除 doc/release/upcoming_changes 中的所有片段，並新增 doc/release/<version>-note.rst。

towncrier build --version "<version>"
git commit -m"Create release note"

檢查發行說明是否為最新版本。

使用「重點」區段更新發行說明。提及以下一些內容

主要新功能
已棄用和移除的功能
支援的 Python 版本
對於 SciPy，支援的 NumPy 版本
近期展望

逐步指示#

這是 Linux 上 NumPy 2.1.0 發行版本的逐步導覽，已修改為使用 GitHub Actions 和 cibuildwheels 建置，並上傳到 anaconda.org NumPy 的暫存儲存庫。命令可以複製到命令列中，但請務必將 2.1.0 替換為正確的版本。應將其與一般發行指南一起閱讀。

設施準備#

在開始進行發行之前，請使用 requirements/*_requirements.txt 檔案，以確保您擁有需要的軟體。大多數軟體可以使用 pip 安裝，但有些軟體將需要 apt-get、dnf 或您的系統用於軟體的任何工具。您還需要 GitHub 個人存取權杖 (PAT) 才能推送文件。以下是一些簡化操作的方法

可以設定 Git 以使用金鑰環來儲存您的 GitHub 個人存取權杖。在網路上搜尋詳細資訊。
您可以使用 keyring 應用程式來儲存 twine 的 PyPI 密碼。請參閱線上 twine 文件以取得詳細資訊。

發行前#

新增/移除 Python 版本#

新增或移除 Python 版本時，需要編輯三個檔案

.github/workflows/wheels.yml # 用於 github cibuildwheel
tools/ci/cirrus_wheels.yml # 用於 cibuildwheel aarch64/arm64 建置
pyproject.toml # 用於分類器和最低版本檢查。

在針對 main 分支的普通 PR 中進行這些變更，並在必要時進行回溯移植。在提交摘要的標題行末尾新增 [wheel build]，以便執行 wheel 建置來測試變更。我們目前在新 Python 版本的第一個 Python rc 版本發布後，一旦 manylinux 和 cibuildwheel 支援它，就會發布 wheel 檔案。對於 Python 3.11，我們能夠在 rc1 公告發布後一周內發布。

回溯移植 pull request#

已標記為此發行版本的變更必須回溯移植到 maintenance/2.1.x 分支。

更新 2.1.0 里程碑#

查看具有 2.1.0 里程碑的問題/pr，並將它們推遲到稍後的版本，或者可能移除里程碑。您可能需要新增里程碑。

建立發行 PR#

發行 PR 通常需要更新或建立四個文件

變更日誌
發行說明
.mailmap 檔案
pyproject.toml 檔案

這些變更應在針對維護分支的普通 PR 中進行。提交標題應包含 [wheel build] 指令，以測試 wheel 檔案是否建置。其他小的、雜項修復可能是此 PR 的一部分。提交訊息可能類似於

REL: Prepare for the NumPy 2.1.0 release [wheel build]

- Create 2.1.0-changelog.rst.
- Update 2.1.0-notes.rst.
- Update .mailmap.
- Update pyproject.toml

設定發行版本#

檢查 pyproject.toml 檔案，並在需要時設定發行版本

$ gvim pyproject.toml

檢查 `pavement.py` 和 `doc/source/release.rst` 檔案#

檢查 pavement.py 檔案是否指向正確的發行說明。它應該在上次發行後已更新，但如果沒有，請立即修復它。另請確保說明在 release.rst 檔案中具有條目

$ gvim pavement.py doc/source/release.rst

產生變更日誌#

變更日誌是使用變更日誌工具產生的

$ spin changelog $GITHUB v2.0.0..maintenance/2.1.x > doc/changelog/2.1.0-changelog.rst

其中 GITHUB 包含您的 GitHub 存取權杖。需要檢查文字中是否有非標準貢獻者名稱，並移除 dependabot 條目。最好也移除 PR 標題中可能存在的任何連結，因為它們無法很好地轉換為 markdown，請將它們替換為等寬文字。應透過更新 .mailmap 檔案來修復非標準貢獻者名稱，這需要大量工作。最好在達到此點之前進行多次試運行，並使用 GitHub 問題 ping 惡意參與者以取得所需資訊。

完成發行說明#

如果 doc/release/upcoming_changes/ 中有任何發行說明片段，請執行 spin notes，這會將片段合併到 doc/source/release/notes-towncrier.rst 檔案中，並刪除這些片段

$ spin notes
$ gvim doc/source/release/notes-towncrier.rst doc/source/release/2.1.0-notes.rst

一旦 notes-towncrier 內容已合併到發行說明中，就可以移除 .. include:: notes-towncrier.rst 指令。說明始終需要一些修復，將需要撰寫引言，並且應指出重大變更。對於修補程式發行版本，也可以附加變更日誌文字，但對於初始發行版本則不行，因為它太長了。檢查先前的發行說明以查看這是如何完成的。

發行逐步導覽#

請注意，在下面的程式碼片段中，upstream 指的是 GitHub 上的根儲存庫，而 origin 指的是其在您的個人 GitHub 儲存庫中的 fork。如果您沒有 fork 儲存庫，而是僅在本地複製了它，則可能需要進行調整。您也可以編輯 .git/config 並新增 upstream (如果它尚不存在)。

1. 準備發行提交#

簽出發行版本的分支，確保它是最新的，並清除儲存庫

$ git checkout maintenance/2.1.x
$ git pull upstream maintenance/2.1.x
$ git submodule update
$ git clean -xdfq

健全性檢查

$ python3 -m spin test -m full

標記發行版本並推送標籤。這需要 numpy 儲存庫的寫入權限

$ git tag -a -s v2.1.0 -m"NumPy 2.1.0 release"
$ git push upstream v2.1.0

如果您需要由於錯誤而刪除標籤

$ git tag -d v2.1.0
$ git push --delete upstream v2.1.0

2. 建置 wheels#

在此過程開始時標記建置將透過 cibuildwheel 觸發 wheel 建置，並將 wheel 檔案和 sdist 上傳到暫存儲存庫。在 github actions 上執行的 CI (適用於所有 x86 架構和 macOS arm64 wheel 檔案) 大約需要 1 小時 1/4。在 cirrus 上執行的 CI (適用於 aarch64 和 M1) 花費的時間更少。您可以在暫存儲存庫中檢查上傳的檔案，但請注意，它與您看到的執行中的作業並非密切同步。

如果您希望手動觸發 wheel 建置，您可以執行以下操作

在 github actions 上 -> Wheel builder 有一個「Run workflow」按鈕，按一下它並選擇要建置的標籤
在 Cirrus 上，我們目前沒有簡單的方法來手動觸發建置和上傳。

如果 wheel 建置由於無關原因而失敗，您可以單獨重新執行它

在 github actions 上，選取 Wheel builder，按一下包含您要重新執行的建置的提交。在左側有一個 wheel 建置列表，選取您要重新執行的建置，然後在結果頁面上點擊逆時針箭頭按鈕。
在 cirrus 上，登入 cirrusci，尋找 v2.1.0 標籤並重新執行失敗的作業。

3. 下載 wheels#

當所有 wheel 檔案都已成功建置和暫存後，請使用 tools/download-wheels.py 腳本從 Anaconda 暫存目錄下載它們

$ cd ../numpy
$ mkdir -p release/installers
$ python3 tools/download-wheels.py 2.1.0

4. 產生 README 檔案#

這需要在下載所有安裝程式後完成，但在更新 pavement 檔案以繼續開發之前完成

$ paver write_release

5. 上傳到 PyPI#

使用 twine 上傳到 PyPI。在最近的 PyPI 變更之後，需要最近版本的 twine，此處使用了版本 3.4.1

$ cd ../numpy
$ twine upload release/installers/*.whl
$ twine upload release/installers/*.gz  # Upload last.

如果其中一個命令在中間中斷，您可能需要選擇性地上傳剩餘檔案，因為 PyPI 不允許上傳同一個檔案兩次。原始碼檔案應最後上傳，以避免當 pip 使用者在處理過程中存取檔案時可能發生的同步問題，這會導致 pip 從原始碼建置而不是下載二進位 wheel 檔案。PyPI 僅允許單個原始碼發行版，此處我們選擇了 zip 封存檔。

6. 上傳檔案到 GitHub#

前往 numpy/numpy，應該有一個 v2.1.0 tag，按一下它並點擊該標籤的編輯按鈕，然後將標題更新為「v2.1.0 (<date>)」。有兩種方法可以新增檔案，使用可編輯的文字視窗和作為二進位上傳。首先編輯使用 pandoc 從 rst 版本翻譯而來的 release/README.md。需要修復的事項：如果包含變更日誌中的 PR 行，則會換行，需要取消換行，連結應變更為等寬文字。然後將內容複製到剪貼簿，並將其貼到文字視窗中。可能需要多次嘗試才能使其看起來正確。然後

將 release/installers/numpy-2.1.0.tar.gz 作為二進位檔案上傳。
將 release/README.rst 作為二進位檔案上傳。
將 doc/changelog/2.1.0-changelog.rst 作為二進位檔案上傳。
如果這是預發行版本，請檢查預發行按鈕。
點擊底部的 {Publish,Update} release 按鈕。

7. 上傳文件到 numpy.org (預發行版本請跳過)#

注意

您將需要 GitHub 個人存取權杖才能推送更新。

此步驟僅適用於最終發行版本，預發行版本和大多數修補程式發行版本可以跳過。make merge-doc 將 numpy/doc 儲存庫複製到 doc/build/merge 中，並使用新文件更新它

$ git clean -xdfq
$ git co v2.1.0
$ rm -rf doc/build  # want version to be current
$ python -m spin docs merge-doc --build
$ pushd doc/build/merge

如果發行系列是新的，您將需要在 doc/build/merge/index.html 首頁上的「在此處插入」註解之後新增一個新區段

$ gvim index.html +/'insert here'

此外，更新版本切換器 json 檔案以新增新的發行版本，並更新標記為 (stable) 和 preferred 的版本

$ gvim _static/versions.json

然後執行 update.py 以更新 _static 中的版本

$ python3 update.py

您可以在瀏覽器中「測試執行」新文件，以確保連結有效，儘管版本下拉式選單不會變更，但它會從 numpy.org 中提取其資訊

$ firefox index.html  # or google-chrome, etc.

更新穩定連結並更新

$ ln -sfn 2.1 stable
$ ls -l  # check the link

一旦一切看起來令人滿意，請更新、提交和上傳變更

$ git commit -a -m"Add documentation for v2.1.0"
$ git push [email protected]:numpy/doc
$ popd

8. 將維護分支重設為開發狀態 (預發行版本請跳過)#

為下一個發行版本建立發行說明，並編輯它們以設定版本。這些說明將是一個骨架，內容很少

$ git checkout -b begin-2.1.1 maintenance/2.1.x
$ cp doc/source/release/template.rst doc/source/release/2.1.1-notes.rst
$ gvim doc/source/release/2.1.1-notes.rst
$ git add doc/source/release/2.1.1-notes.rst

將新的發行說明新增至文件發行列表，並更新 pavement.py 中的 RELEASE_NOTES 變數

$ gvim doc/source/release.rst pavement.py

更新 pyproject.toml 中的 version

$ gvim pyproject.toml

提交結果

$ git commit -a -m"MAINT: Prepare 2.1.x for further development"
$ git push origin HEAD

前往 GitHub 並建立 PR。它應該很快被合併。

9. 在 numpy.org 上公告發行 (預發行版本請跳過)#

這假設您已 fork numpy/numpy.org

$ cd ../numpy.org
$ git checkout main
$ git pull upstream main
$ git checkout -b announce-numpy-2.1.0
$ gvim content/en/news.md

對於所有發行版本，請前往頁面底部並新增一行連結。查看先前的連結以取得範例。
對於週期中的 *.0 發行版本，請在頂部新增一個新區段，其中簡要說明新功能，並將新聞連結指向它。

提交並推送

$ git commit -a -m"announce the NumPy 2.1.0 release"
$ git push origin HEAD

前往 GitHub 並建立 PR。

10. 公告到郵件列表#

應在 numpy-discussion、scipy-devel 和 python-announce-list 郵件列表上公告發行。查看先前的公告以取得基本範本。貢獻者和 PR 列表與上面為發行說明產生的列表相同。如果您交叉發布，請確保 python-announce-list 是 BCC，以便回覆不會傳送到該列表。

11. 發行後更新 main 分支 (預發行版本請跳過)#

簽出 main 分支並轉發移植文件變更。如果程序已變更或改進，您可能還需要更新這些說明

$ git checkout -b post-2.1.0-release-update main
$ git checkout maintenance/2.1.x doc/source/release/2.1.0-notes.rst
$ git checkout maintenance/2.1.x doc/changelog/2.1.0-changelog.rst
$ git checkout maintenance/2.1.x .mailmap  # only if updated for release.
$ gvim doc/source/release.rst  # Add link to new notes
$ git status  # check status before commit
$ git commit -a -m"MAINT: Update main after 2.1.0 release."
$ git push origin HEAD