貢獻概覽#

本地 git 慣例#

如果您在本機追蹤 Arrow 原始碼儲存庫，以下是使用 git 的檢查清單

  • 從您 個人 fork 的 apache/arrow 工作，並提交 pull request 到 “upstream”。

  • 讓您的 fork 的 main 分支與 upstream/main 同步。

  • 在分支上開發，而不是您自己的 “main” 分支。

  • 您將分支命名為何並不重要。有些人喜歡使用 GitHub issue 編號作為分支名稱，其他人則使用描述性名稱。

  • 定期將您的分支與 upstream/main 同步，因為每天都有許多 commit 合併到 main。

  • 建議使用 git rebase 而不是 git merge。

  • 如果發生衝突，且您的本地 commit 歷史記錄有多個 commit，您可以透過將您的本地 commit 合併成單一 commit 來簡化衝突解決流程。保留 commit 歷史記錄並不那麼重要，因為當您的功能分支合併到 upstream 時，會自動發生 squash。

    如何合併本地 commit？

    使用以下指令中止 rebase

    $ git rebase --abort

    接著，可以透過執行以下指令以互動方式合併本地 commit

    $ git rebase --interactive ORIG_HEAD~n

    其中 n 是您本地分支中 commit 的數量。合併後，您可以再次嘗試合併，這次衝突解決應該相對簡單。

    一旦您有了更新的本地副本，您就可以推送到您的遠端儲存庫。請注意，由於您的遠端儲存庫仍然保留舊的歷史記錄，您需要執行強制推送。大多數推送應使用 --force-with-lease

    $ git push --force-with-lease origin branch

    如果遠端有本地端沒有的 commit，例如，如果同事進行了其他 commit，則 --force-with-lease 選項將會失敗。透過使用 --force-with-lease 而不是 --force，您可以確保這些 commit 不會被覆寫，並且可以在需要時提取這些變更。

    設定預設為 rebase

    如果您在儲存庫的 .git/config 中設定以下內容，則可以從 git pull 指令中省略 --rebase 選項，因為預設會隱含此選項。

    [pull]
      rebase = true

Pull request 與審查#

當貢獻 patch 時，請使用此列表作為 Apache Arrow 工作流程的檢查清單

  • 將 patch 作為 GitHub pull request 提交到 main 分支。

  • 為了讓您的 pull request 與 GitHub issue 同步，請在您的 pull request 標題前加上 GitHub issue id (例如：GH-14866: [C++] 移除內部 GroupBy 實作)。

  • 給 pull request 一個清晰、簡潔的描述：當 pull request 合併時，這將保留在擴充的 commit 訊息中。

  • 確保您的程式碼通過單元測試。您可以在每個 Arrow 组件各自的 README 檔案中找到如何執行單元測試的說明。

核心開發人員和其他在您的變更影響的專案部分有利害關係的人員將會審查、請求變更，並希望最終表示他們的批准。為了使每個人的審查過程順利，請嘗試

  • 如果可能，將您的工作分解為小的、單一用途的 patch。

    合併具有許多不相關功能的大型變更要困難得多，特別是如果您是專案新手，較小的變更更容易被維護者接受。

  • 為您的程式碼新增單元測試。

  • 遵循您正在修改的專案部分之風格指南。

    某些語言（例如 C++ 和 Python）在持續整合中執行 lint 檢查。對於所有語言，請參閱其各自的開發人員文件和 README 以取得風格指南。

  • 盡量使其看起來像是程式碼庫只有一位作者，並模擬您看到的任何慣例，無論它們是否經過正式記錄或檢查。

當測試通過且 pull request 已獲得相關方的批准時，committer 將合併 pull request。這是使用命令列工具執行 squash 合併來完成的。

關於 squash 合併的詳細資訊

Pull request 是透過 squash 合併來合併的，以便您的所有 commit 都將註冊為 main 分支的單一 commit；這簡化了 GitHub issue 與 commit 之間的關聯，更容易二分歷史記錄以識別變更引入的位置，並幫助我們能夠將個別 patch cherry-pick 到維護分支上。

您的 pull request 將在 GitHub 介面中顯示為 “merged”。在該 commit 的 commit 訊息中，合併工具會新增 pull request 描述、返回 pull request 的連結，以及對貢獻者和任何共同作者的署名。

實驗性儲存庫#

Apache Arrow 對於在 革命家規則 的背景下開發實驗性儲存庫，有明確的政策。

此政策的主要動機是提供一種輕量級機制，以便在 ASF 和 Apache Arrow 管理模型中進行實驗性工作，並具有必要的創作自由。此政策允許 committers 在新的儲存庫上工作，因為它們提供了許多重要的工具來管理它（例如 github issues、“watch”、“github stars” 來衡量整體興趣）。

流程#

  • Committer 可以 透過在 Apache Arrow 中建立一個單獨的 git 儲存庫（例如，透過 selfserve）並在郵件列表中公告，以及其目標和新建立儲存庫的連結來啟動實驗性工作。

  • Committer 必須 發起一個電子郵件討論串，其唯一目的是向社群介紹儲存庫狀態的更新。

  • 不得 從儲存庫發布正式版本。

  • 任何以任何方式使實驗性儲存庫正式化的決定，無論是透過合併還是遷移，都必須 在郵件列表中討論和投票決定。

  • Committer 負責管理儲存庫的 issue、文件、CI，包括授權檢查。

  • Committer 決定何時封存儲存庫。

儲存庫管理#

  • 儲存庫 必須 在 apache/ 下

  • 儲存庫的名稱 必須 以 arrow-experimental- 為前綴

  • Committer 對儲存庫擁有完全權限（在 ASF 中可能的範圍內）

  • Push / merge 權限 僅能 授予 Apache Arrow committers

開發流程#

  • 儲存庫必須遵循 ASF 關於第三方程式碼的要求。

  • Committer 決定如何管理 issue、PR 等。

分歧#

  • 如果上述任何 “必須” 事項未能實現，且 committer 在收到請求後未採取更正措施，PMC 應該 取得所有權並決定該怎麼做。

特定功能指南#

社群不時會討論他們期望支援的特定類型功能和改進。本節概述了在這方面做出的決定。

位元組順序#

Arrow 格式允許設定位元組順序。由於小端架構的普及，大多數實作預設假設為小端。也已經有一些努力來支援大端平台。根據 郵件列表討論，新平台的要求是

  1. 穩健的（非不穩定的，在合理時間內返回結果）持續整合設定。

  2. 效能關鍵程式碼部分的基準測試，以證明沒有效能衰退。

此外，對於大端支援，實作可以支援兩個層級

  1. 原生位元組順序（所有 Arrow 通訊都發生在相同位元組順序的進程中）。這包括輔助功能，例如讀取和寫入各種檔案格式，例如 Parquet。

  2. 跨位元組順序支援（實作將在適用於 IPC 和 Flight 訊息時進行位元組重新排序）。

關於支援哪個層級的決定是基於維護者對複雜性和技術風險的偏好。一般而言，所有實作都應該對原生位元組順序支援持開放態度（前提是滿足 CI 和效能要求）。跨位元組順序支援是個別維護者需要考慮的問題。

目前旨在實現跨位元組順序支援的實作是

  1. C++

不打算實作跨位元組順序支援的實作

  1. Java

對於其他函式庫，在提交 PR 之前，應先在郵件列表中討論以達成共識。