pandas 維護#

本指南適用於 pandas 維護人員。對於希望了解 pandas 開發流程以及成為維護人員所需的步驟的貢獻者來說，這也可能很有趣。

主要的貢獻指南可以在 為 pandas 貢獻 找到。

角色#

pandas 使用兩個層級的權限：分流和核心團隊成員。

分流成員可以標記和關閉問題和拉取請求。

核心團隊成員可以標記和關閉問題和拉取請求，並且可以合併拉取請求。

GitHub 發布了完整的 權限清單。

任務#

pandas 在很大程度上是一個志工專案，因此這些任務不應被視為對分流和維護者的「期望」。相反，它們是一般性地說明成為維護者是什麼意思。

  • 分流新提交的問題（請參閱 問題分流）

  • 檢閱新開啟的拉取請求

  • 回應現有問題和拉取請求的更新

  • 推動對停滯問題和拉取請求的討論和決策

  • 提供經驗/智慧，針對 API 設計問題，以確保一致性和可維護性

  • 專案組織（執行/參加開發人員會議，代表 pandas）

https://matthewrocklin.com/blog/2019/05/18/maintainer 可能是有趣的背景閱讀。

問題分流#

分流是處理社群回報問題的重要第一步，即使是部分貢獻也是協助維護 pandas 的好方法。只有在完成以下所有步驟後，才能移除「需要分流」標籤。

以下是分流新開啟問題的典型工作流程。

  1. 感謝回報者開啟問題

    問題追蹤器是許多人除了使用函式庫之外，與 pandas 專案本身的第一次互動。因此，我們希望它是一個令人歡迎且愉快的體驗。

  2. 是否提供了必要的資訊？

    理想情況下，報告者會填寫問題範本，但許多人並未填寫。如果缺少關鍵資訊（例如他們使用的 pandas 版本），請隨時索取該資訊，並將問題標記為「需要資訊」。報告應遵循 錯誤報告和增強要求 中的準則。如果您未遵循範本，您可能想要連結到該範本。

    請確保標題準確反映問題。如果標題不清楚，請自行編輯。

  3. 這是一個重複的問題嗎？

    我們有許多公開問題。如果一個新問題明顯是重複的，請將新問題標記為「重複」，並關閉該問題，並附上原始問題的連結。請務必感謝報告者，並鼓勵他們參與原始問題，並嘗試修復它。

    如果新問題提供了相關資訊，例如更好或稍有不同的範例，請將其新增到原始問題中，作為原始貼文的留言或編輯。

  4. 問題是否極小且可重現?

    對於問題回報，我們要求回報者提供一個最小的可重現範例。請參閱 https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports 以取得良好的說明。如果範例無法重現，或者如果它明顯不是最小的，請隨時詢問回報者是否可以提供範例或簡化提供的範例。請確認撰寫最小的可重現範例是一項艱難的工作。如果回報者有困難，您可以嘗試自己撰寫一個，我們將編輯原始文章以納入它。

    如果無法提供可重現範例，請新增「需要資訊」標籤。

    如果提供了可重現範例，但您看到簡化，請使用您較簡單的可重現範例編輯原始文章。

    確保問題存在於主分支，並且在完成所有步驟之前，它具有「需要分流」標籤。在您驗證它存在於主分支後，請在問題中新增註解，以便其他人知道它已獲得確認。

  5. 這是一個定義明確的功能要求嗎？

    一般來說，pandas 偏好在提交請求提出之前，在問題中討論和設計新功能。鼓勵提交者為新功能包含建議的 API。讓他們撰寫完整的文件字串是確定具體事項的好方法。

    使用「需要討論」標籤標記新功能要求，因為在決定提案是否在 pandas 的範圍內之前，我們需要與多位 pandas 維護人員進行討論。

  6. 這是一個使用問題嗎？

    我們希望使用問題在 StackOverflow 上詢問，並加上 pandas 標籤。 https://stackoverflow.com/questions/tagged/pandas

    如果很容易回答，請隨時連結到相關文件部分，讓他們知道未來這類問題應該在 StackOverflow 上，並關閉問題。

  7. 我應該新增哪些標籤和里程碑？

    套用相關標籤。這有點像一門藝術，需要經驗。查看類似的問題，了解標籤的用法。

    如果問題定義明確，且修正方法看似相當直接，請將問題標籤為「適合新手」。

    完成上述步驟後，請務必移除「需要分類」標籤。

調查回歸#

回歸是無意間損壞先前運作中程式碼的錯誤。調查回歸的常見方法是使用 git bisect，它會找出引發錯誤的第一個提交。

例如：使用者回報在 pandas 版本 1.5.0 中，pd.Series([1, 1]).sum() 會傳回 3，但在版本 1.4.0 中會傳回 2。首先，在 pandas 目錄中建立一個包含下列內容的檔案 t.py

import pandas as pd
assert pd.Series([1, 1]).sum() == 2

然後執行

git bisect start
git bisect good v1.4.0
git bisect bad v1.5.0
git bisect run bash -c "python setup.py build_ext -j 4; python t.py"

這會找出改變行為的第一個提交。必須在每個步驟重新建置 C 擴充，因此搜尋可能需要一段時間。

離開 bisect 並重新建置目前版本

git bisect reset
python setup.py build_ext -j 4

在對應的問題中回報你的發現，並 ping 提交作者以取得他們的意見。

注意

在上述 bisect run 指令中，如果 t.py 以 0 退出，則提交會被視為良好，否則視為不良。當引發例外是預期行為時，請將程式碼包在適當的 try/except 陳述式中。請參閱 GH 35685 以取得更多範例。

關閉問題#

在此處要謹慎：許多人會將關閉問題解讀為我們表示對話已經結束。如果確定行為不是錯誤，或功能超出範圍，通常最好給予回報者一些時間回應或自行關閉其問題。不過，有時回報者會直接離開，而我們會在對話結束後關閉問題。如果您認為應該關閉問題，但並非完全確定，請套用「候選關閉」標籤，並等待其他維護人員查看。

檢閱プルリクエスト#

任何人都可以檢閱プルリクエスト：一般貢獻者、分類人員或核心團隊成員。但只有核心團隊成員可以在準備就緒時合併プルリクエスト。

以下是檢閱プル請求時要檢查的一些事項。

  • 測試應位於合理的位置：與密切相關的測試位於同一個檔案中。

  • 新的公開 API 應包含在 doc/source/reference/ 的某個地方。

  • 新的/已變更的 API 應在文件字串中使用 versionadded 或 versionchanged 指令。

  • 面向使用者的變更應在適當的檔案中包含 whatsnew。

  • 回歸測試應參照原始 GitHub 問題編號，例如 # GH-1234。

  • 拉取請求應標籤並指派適當的里程碑（回歸修正和小型錯誤修正的下次修補程式版本，否則為下次次要里程碑）

  • 變更應符合我們的 版本政策。

回溯#

pandas 支援點版本（例如 1.4.3），其目標為

  1. 修正第一個次要版本版本中引入的新功能中的錯誤。

  • 例如，如果在 1.4 中新增新功能且包含錯誤，則可以在 1.4.3 中套用修正。

  1. 修正幾個次要版本前曾運作的錯誤。核心團隊成員間應同意回溯是適當的。

  • 例如，如果某個功能在 1.2 中運作，但在 1.3 之後停止運作，則可以在 1.4.3 中套用修正。

由於 pandas 次要版本基於 GitHub 分支（例如 1.4 的點版本基於 1.4.x 分支），「回溯」表示將拉取請求修正合併至 main 分支和與下次點版本相關的正確次要分支。

預設情況下，如果將拉取請求指派給 GitHub 介面中的下一個點版本里程碑，則一旦合併拉取請求，@meeseeksdev 機器人應會自動執行後向移植程序。將建立新的拉取請求，將拉取請求後向移植到正確的版本分支。有時由於合併衝突，需要建立手動拉取請求來解決程式碼衝突。

如果機器人沒有自動啟動後向移植程序，您也可以在已合併的拉取請求中撰寫 GitHub 註解以觸發後向移植

@meeseeksdev backport version-branch

這將觸發一個工作流程，該工作流程會將給定的變更後向移植到分支 (例如 @meeseeksdev backport 1.4.x)

清除舊問題#

pandas 中的每個開放問題都有代價。開放問題會讓尋找重複問題變得更困難，也可能讓您更難知道在 pandas 中需要做什麼。話雖如此，關閉問題本身並非目標。我們的目標是讓 pandas 達到最佳狀態，而最好的方法是確保我們的開放問題品質很高。

偶爾會修正錯誤，但問題並未連結到拉取請求中。在這些情況下，請註解「此問題已修正，但可以使用測試。」並將問題標示為「良好的第一個問題」和「需要測試」。

如果較舊的問題不符合我們的問題範本，請編輯原始文章，以包含最小範例、實際輸出和預期輸出。問題報告的一致性非常有價值。

如果舊問題缺少可重現的範例，請標記為「需要資訊」，並請他們提供範例（如果可能，請自行撰寫）。如果在合理的時間內未提供，請根據 關閉問題 中的政策關閉問題。

清理舊的 Pull Request#

偶爾，貢獻者無法完成 Pull Request。如果自上次要求變更的審查以來已過一段時間（例如兩週），請溫和地詢問他們是否仍有興趣繼續這項工作。如果再過兩週左右沒有回應，請感謝他們的努力，然後

  • 關閉 Pull Request；

  • 推送到貢獻者的分支，以將其工作推過完成線（如果您是 pandas-core 的一部分）。這有助於將重要的 PR 推過完成線，或解決小型合併衝突。

如果要關閉 Pull Request，請在原始問題中留言：「#1234 有個停滯的 PR 可能會有幫助。」，如果 PR 已接近被接受，或許可以標記問題為「良好的第一個問題」。

成為 pandas 維護者#

完整的流程概述在我們的 治理文件 中。總之，我們很樂意授予對問題追蹤器提供協助的人員分類權限。

新增維護者的必要步驟為

  1. 聯絡貢獻者並詢問他們是否有興趣加入。

  2. 如果接受邀請，請將貢獻者新增到適當的 GitHub 團隊。

  • pandas-core 適用於核心團隊成員

  • pandas-triage 適用於 pandas 分類成員

如果要加入 pandas-core，還有兩個步驟

  1. 將貢獻者加入 pandas Google 群組。

  2. 建立一個 pull request，將貢獻者的 GitHub 識別碼加入 pandas-dev/pandas/web/pandas/config.yml。

核心團隊成員的目前清單在 pandas-dev/pandas

合併 pull request#

只有核心團隊成員可以合併 pull request。我們有一些準則。

  1. 通常，你不應該在未經核准的情況下自行合併自己的 pull request。例外情況包括修復 CI 的小變更（例如固定套件版本）。如果你對變更非常有信心，在獲得其他核心團隊成員的核准後自行合併是可以的。

  2. 你不應該合併有正在進行討論的 pull request，或是有任何核心維護人員投下 -1 票的 pull request。pandas 透過共識運作。

  3. 對於較大的變更，最好至少有兩個核心團隊成員投下 +1。

除了 關閉問題 中列出的項目外，你應該驗證 pull request 是否指派到正確的里程碑。

合併到修補版本里程碑的 pull request 通常會由我們的機器人回傳。驗證機器人是否注意到合併（通常會在幾分鐘內留下留言）。如果需要手動回傳，請執行此操作，並在你手動完成後移除「需要回傳」標籤。如果你忘記在標記前指派里程碑，你可以要求機器人使用下列方式回傳：

@Meeseeksdev backport <branch>

基準機器#

團隊目前擁有專用硬體，用於主機 pandas 的 ASV 效能基準網站。結果會發布到 https://asv-runner.github.io/asv-collection/pandas/

組態#

機器可以使用 Ansible 腳本檔在 tomaugspurger/asv-runner 中進行組態。

發布#

結果會發布到另一個 GitHub 儲存庫，tomaugspurger/asv-collection。最後，我們在文件伺服器上有一個 cron 工作，從 tomaugspurger/asv-collection 提取，並從 /speed 提供服務。請向 Tom 或 Joris 索取 Web 伺服器的存取權。

除錯#

基準測試由 Airflow 排程。它有一個儀表板，用於查看和除錯結果。您需要設定一個 SSH 隧道才能查看它們

ssh -L 8080:localhost:8080 pandas@panda.likescandy.com

發布流程#

發布流程會建立一個快照的 pandas（一個 git commit），讓使用者可以使用特定版本號。在發布後，新的 pandas 版本將會在以下位置提供

發布新版本的 pandas 的流程會在下一部分詳細說明。

說明中包含 <version>，需要替換為要發布的版本（例如 1.5.2）。此外，要發布的分支 <branch>，取決於要發布的版本是新版本的候選版本，還是其他版本。候選版本從 main 發布，而其他版本從其分支發布（例如 1.5.x）。

先決條件#

為了能夠發布新的 pandas 版本，需要下列權限

  • 合併 pandas 和 pandas-feedstock 儲存庫的權限。對於後者，開啟一個 PR，將您的 GitHub 使用者名稱新增到 conda-forge 配方。

  • 推送到 pandas 儲存庫中的 main 的權限，以推送新的標籤。

  • 寫入 PyPI 的權限.

  • 存取我們的網站/文件伺服器。與基礎架構委員會分享您的公開金鑰，以新增到主伺服器使用者的 authorized_keys 檔案中。

  • 存取社群媒體帳戶，以發布公告。

預發布#

  1. 與核心團隊就下列主題達成共識

    • 發布日期（主要/次要版本通常每 6 個月發布一次，而修補程式版本每月發布一次，直到 x.x.5，緊接在下次主要/次要版本之前）

    • 阻礙因素（必須包含在發布中的問題和 PR）

    • 要發布的版本之後的下一版本

  2. 更新並整理要發布的版本之發行說明，包括

    • 設定發布的最終日期

    • 移除任何未使用的項目符號

    • 確定沒有格式化問題、錯字等問題

  3. 確定 CI 對要發布的分支的最後一次提交為綠色

  4. 如果不是候選版本，請確定所有回傳到要發布的分支的拉取請求都已合併

  5. 針對要發布的版本之後的版本建立新的議題和里程碑。如果發布的是候選版本，我們通常會想要為下一個主要/次要版本和下一個修補程式版本建立議題和里程碑。在修補程式版本的里程碑中，我們會加入說明 on-merge: backport to <branch>，因此標記的公關會自動由我們的機器人回傳到發布分支

  6. 將要發布的里程碑中所有議題和公關的里程碑變更為下一個里程碑

發布#

  1. 在要發布的分支的最後一次提交建立一個空的提交和標籤

    git checkout <branch>
git pull --ff-only upstream <branch>
git clean -xdf
git commit --allow-empty --author="Pandas Development Team <[email protected]>" -m "RLS: <version>"
git tag -a v<version> -m "Version <version>"  # NOTE that the tag is v1.5.2 with "v" not 1.5.2
git push upstream <branch> --follow-tags

新版本的說明文件會在 CI 中自動建置和發布，並在推播標籤時觸發

  1. 只有在發布是候選版本時，我們才會在建立標籤後立即為其建立新的分支。例如，如果我們要發布 pandas 1.4.0rc0，我們會想要建立分支 1.4.x 以回傳提交到 1.4 版本。並建立標籤以標示 1.5.0 開發的開始（假設它是下一個版本）

    git checkout -b 1.4.x
git push upstream 1.4.x
git checkout main
git commit --allow-empty -m "Start 1.5.0"
git tag -a v1.5.0.dev0 -m "DEV: Start 1.5.0"
git push upstream main --follow-tags

  2. 從 輪子暫存區域 下載原始碼分發和輪子。請小心確保沒有遺失任何輪子（例如，由於建置失敗）。

    執行 scripts/download_wheels.sh，並使用您要下載輪子/sdist 的版本，應該可以解決問題。此腳本會在您的 pandas 克隆中建立一個 dist 資料夾，並將下載的輪子和 sdist 放置在其中

    scripts/download_wheels.sh <VERSION>

  3. 建立一個 新的 GitHub 發行版本

    • 標籤：<version>

    • 標題：Pandas <version>

    • 說明：複製相同類型的最後一個發布版本的說明（候選版本、主要/次要版本或修補程式版本）

    • 檔案：pandas-<version>.tar.gz 剛才產生的原始碼分發

    • 設為預先發布版本：僅檢查候選版本

    • 設為最新發布版本：保持勾選，除非要為舊版本發布修補程式版本（例如，在發布 1.5 之後發布 1.4.5）

  4. 將輪子傳送到 PyPI

    twine upload pandas/dist/pandas-<version>*.{whl,tar.gz} --skip-existing

  5. 幾個小時後，GitHub 發布版本會觸發一個 自動 conda-forge PR。（如果您不想等待，您可以開啟一個標題為 @conda-forge-admin, please update version 的議題，以觸發機器人。）CI 顯示為綠色後，請將其合併，它會產生 conda-forge 套件。

    如果需要手動執行 PR，則通常需要變更版本、sha256 和建置欄位。如果自上次發布以來，配方中的任何其他內容已變更，則這些變更應可在 ci/meta.yaml 中取得。

發布後#

  1. 透過登入我們的網路伺服器，並編輯 /var/www/html/pandas-docs/stable 來更新符號連結至穩定的文件，以指向 version/<最新版本>，適用於主要和次要版本，或 version/<次要> 至 version/<修補程式>，適用於修補程式版本。確切的說明如下（將範例版本號碼替換為您要發布的版本之適當版本號碼）

    • 登入伺服器並使用正確的使用者。

    • cd /var/www/html/pandas-docs/

    • ln -sfn version/2.1 stable（適用於主要或次要版本）

    • ln -sfn version/2.0.3 version/2.0（適用於修補程式版本）

  2. 如果要發布主要或次要版本，請在我們的原始程式碼中開啟一個公關，以更新 web/pandas/versions.json，讓文件下拉式功能表中出現所需的版本。

  3. 關閉已發布版本的里程碑和問題。

  4. 為下一個版本建立一個新問題，並附上預計發布日期。

  5. 開啟一個公關，其中包含下一個版本的版本說明佔位符。例如，請參閱 1.5.3 的公關。請注意，要使用的範本取決於它是主要、次要或修補程式版本。

  6. 在官方頻道中宣布新版本（使用先前的公告作為參考）

    • pandas-dev 和 pydata 郵件清單

    • Twitter、Mastodon、Telegram 和 LinkedIn

  7. 更新此發行說明，以修正任何不正確的地方，並更新自上次發行以來任何變更的相關資訊。