參與 Spark | Apache Spark - Spark 繁體中文

本指南說明對 Apache Spark 進行各種類型貢獻的最佳方式，包括提交程式碼變更前所需的條件。

參與 Spark 不僅僅是撰寫程式碼。協助郵件清單上的新使用者、測試版本和改善文件也受到歡迎。事實上，提出重要的程式碼變更通常需要先透過其他方式協助，在社群中獲得經驗和信譽。這也是成為有效貢獻者的指南。

因此，本指南依序整理貢獻，讓有意長期參與的新貢獻者參考。建立協助他人的記錄，而不要只是開啟拉取請求。

透過協助其他使用者來貢獻

參與 Spark 的絕佳方式是在 user@spark.apache.org 郵件清單或 StackOverflow 上協助回答使用者問題。Spark 永遠都有許多新使用者；花幾分鐘時間協助回答問題是一項非常有價值的社群服務。

貢獻者應訂閱此清單並追蹤，以隨時掌握 Spark 的最新動態。回答問題是協助社群的絕佳且顯著方式，也能展現您的專業知識。

請參閱郵件清單指南，了解如何有效參與郵件清單上的討論，以及 StackOverflow 等論壇。

透過測試版本來貢獻

Spark 的發佈流程以社群為導向，社群成員可以在 dev@spark.apache.org 郵件清單上針對新發佈進行投票。我們邀請 Spark 使用者訂閱此清單以接收公告，並在較新的版本上測試其工作負載，並提供在較新版本中發現的任何效能或正確性問題的回饋。

透過檢閱變更進行貢獻

Spark 原始碼的變更會透過 GitHub pull 要求（稍後說明）提出、檢閱和提交。任何人都可以在這裡檢視和評論目前的變更。檢閱他人的變更是一個很好的方式，可以瞭解變更流程如何運作，並接觸程式碼各部分的活動。您可以透過檢閱變更並提出問題或指出問題（例如錯字或小型的樣式問題）來提供協助。另請參閱 https://spark-prs.appspot.com/，以取得檢視和篩選開啟的 PR 的便利方式。

貢獻文件變更

若要建議變更發佈文件（即出現在 https://spark.dev.org.tw/docs/ 下的文件），請編輯 Spark docs/ 目錄中的 Markdown 原始檔，其 README 檔會顯示如何建立文件以在本地測試您的變更。建議文件變更的流程與下面建議程式碼變更的流程相同。

若要建議變更其餘文件（即不出現在 https://spark.dev.org.tw/docs/ 下的文件），請以類似的方式編輯 spark-website 儲存庫中的 Markdown，並開啟 pull 要求。

貢獻使用者函式庫至 Spark

正如 Java 和 Scala 應用程式可以存取大量的函式庫和公用程式（這些函式庫和公用程式都不是 Java 或 Scala 本身的一部分），Spark 旨在支援豐富的函式庫生態系統。許多新的有用公用程式或功能屬於 Spark 之外，而不是核心。例如：語言支援可能必須是核心 Spark 的一部分，但是有用的機器學習演算法可以很開心地存在於 MLlib 之外。

為此，大型且獨立的新功能通常會被拒絕納入 Spark 本身，但可以且應該作為一個獨立的專案和存放庫來託管，並納入 spark-packages.org 收藏。

提交錯誤報告

理想情況下，錯誤報告應附有建議的程式碼變更以修正錯誤。這並非總是可行，因為發現錯誤的人可能沒有經驗來修正它。可以透過建立 JIRA 來報告錯誤，但不用建立拉取請求（請見下方）。

但是，只有在錯誤報告包含足夠的資訊來理解、隔離並理想地重現錯誤時，錯誤報告才有用。單純遇到錯誤並不表示應該報告錯誤；如下方所示，請先搜尋 JIRA 並在 Spark 使用者／開發人員郵件清單中搜尋並詢問。無法重現的錯誤或簡單的錯誤報告可能會被關閉。

如果錯誤報告說明錯誤是如何透過哪個提交引入的，將非常有幫助，這樣審閱者就能輕易了解錯誤。當拉取請求合併時，這也有助於提交者決定錯誤修正應回溯到多早。修正錯誤的拉取請求應將問題縮小到根本原因。

效能回歸也是一種錯誤。修正效能回歸的拉取請求必須提供基準測試來證明問題確實已修正。

請注意，資料正確性／資料遺失錯誤非常嚴重。請確保對應的錯誤報告 JIRA 單據標示為 correctness 或 data-loss。如果錯誤報告沒有獲得足夠的關注，請寄送電子郵件至 dev@spark.apache.org，以吸引更多關注。

也可以建議新功能。這些功能通常沒有幫助，除非附有詳細資訊，例如設計文件和／或程式碼變更。大型新貢獻應先考慮 spark-packages.org（請見上方），或先在郵件清單中討論。功能要求可能會被拒絕，或在一段時間沒有活動後關閉。

貢獻 JIRA 維護

由於 Apache Spark JIRA 中提出的問題數量龐大，難免會有一些問題是重複的，或變得過時而最終以其他方式修復，或無法重現，或可以從更多細節中受益，等等。通過推進討論或甚至解決 JIRA，有助於識別這些問題並解決它們。大多數貢獻者都可以直接解決 JIRA。在確定你是否非常確定應該解決問題時要做出判斷，儘管可以輕鬆地撤消更改。如有疑問，請在 JIRA 上留言。

在解決 JIRA 時，遵守一些有用的慣例

如果有一個可以指出已解決問題的更改，則將其解析為已修復
- 僅當解析為已修復時，才設定修復版本
- 將受讓人設定為對解決方案貢獻最多的人，通常是打開解決問題的 PR 的人。
- 如果有多人貢獻，則優先分配給更“初級”的非提交者貢獻者
對於無法根據報告針對主版本重現的問題，將其解析為無法重現
- 如果很明顯其他以前的拉取請求已解決了它，那麼修復也是合理的。連結到它。
如果問題與另一個問題相同或是一個子集，則解析為重複
- 確保連結到它重複的 JIRA
- 優先解析活動或討論較少的問題作為重複
如果問題明顯過時，並且適用於自開啟以來發生根本性變化的問題或組件，則解析為不是問題
如果問題沒有意義——例如，不可操作的非 Spark 問題，則解析為無效
如果是一個連貫的問題，但有明確的跡象表明沒有支持或興趣對其採取行動，則解析為不會修復
如果雨傘只是容器問題，不對應於它們自己的可操作更改，則經常標記為已完成

準備貢獻程式碼變更

選擇要貢獻的內容

Spark 是個異常繁忙的專案，平均每隔幾個小時就會有一個新的 JIRA 或拉取請求。審查可能需要提交者花費數小時或數天的時間。如果貢獻者專注於有用、清晰、易於評估且已通過基本檢查的變更，則對所有人都有利。

有時，貢獻者已經考慮到一個特定的新變更或錯誤。如果尋求想法，請諮詢 JIRA 中的入門任務清單，或詢問 user@spark.apache.org 郵件清單。

在繼續之前，貢獻者應評估建議的變更是否可能相關、新穎且可操作

是否清楚程式碼必須變更？只有在明確找出問題或變更時，提出 JIRA 和拉取要求才適當。如果只是在使用 Spark 時遇到問題，請先使用郵件清單，而不是考慮提交 JIRA 或提出變更。如有疑問，請先透過電子郵件 user@spark.apache.org 詢問可能的變更
搜尋 user@spark.apache.org 和 dev@spark.apache.org 郵件清單檔案以尋找相關討論。問題通常已在之前討論過，並有不需要變更程式碼的解決方案，或記錄哪些類型的變更不會被接受為解決方案。
搜尋 JIRA 以尋找現有問題：https://issues.apache.org/jira/browse/SPARK
在右上角的搜尋方塊中輸入 spark [搜尋字詞]。如果已存在邏輯上類似的問題，請先參與現有 JIRA 和拉取要求的討論，而不是建立新的問題。
變更的範圍是否符合貢獻者的經驗等級？任何人都可以建議修正錯字，但重構核心排程邏輯需要對 Spark 有更深入的了解。有些變更需要先累積經驗（見上文）。

值得再次強調的是，對 Spark 的核心或 SQL 和 Catalyst 等高度複雜且重要的模組進行變更更難正確執行。這些變更將受到更嚴格的審查，並採用比變更較不重要的程式碼更高的審查標準。

MLlib 特定的貢獻指南

雖然豐富的演算法集是 MLLib 的重要目標，但擴充專案需要優先考量可維護性、一致性和程式碼品質。新的演算法應

廣為人知
被使用和接受（學術引用和具體使用案例有助於證明這一點）
高度可擴充
有完善的文件
具有與 MLLib 中執行相同功能的其他演算法一致的 API
有合理的開發人員支援預期。
在公開類別、方法和變數上加上 @Since 註解。

錯誤訊息指南

在 Spark 中引發的例外狀況應與標準化且可操作的錯誤訊息相關聯。

錯誤訊息應回答下列問題

什麼是問題？
為什麼會發生問題？
如何解決問題？

撰寫錯誤訊息時，您應該

使用主動語態
避免基於時間的陳述，例如對未來支援的承諾
使用現在式描述錯誤並提供建議
如果解決方案不明確，請提供具體範例
避免聽起來有指責、批判或侮辱意味
直接了當
在使用者介面的錯誤中不要使用程式設計術語

請參閱錯誤訊息指南以取得更多詳細資訊。

程式碼檢閱準則

在考慮如何貢獻程式碼之前，了解如何檢閱程式碼以及變更可能被拒絕的原因很有用。請參閱 Google 工程實務文件中的程式碼檢閱員詳細指南。簡單來說，具有許多或大量正面影響，且負面影響或風險較少的變更，合併的可能性較高，而且合併速度也較快。風險且價值較低的變更不太可能合併，而且可能會被直接拒絕，而不是接受重複的檢閱。

正面影響

修正現有功能中錯誤的根本原因
新增功能或修正大量使用者需要的問題
簡單、有針對性
維持或改善 Python、Java、Scala 之間的一致性
容易測試；有測試
降低複雜度和程式碼行數
變更已經討論過，而且提交者知道

負面影響、風險

只對錯誤的症狀進行應急處理
引入複雜的新功能，特別是需要支援的 API
增加僅有助於利基使用案例的複雜度
新增使用者空間功能，不需要在 Spark 中維護，但可以外部託管並由 spark-packages.org 編製索引
變更公開 API 或語意（很少允許）
新增大型依賴項
變更現有依賴項的版本
新增大量程式碼
在一次「大爆炸」變更中進行大量修改

貢獻程式碼變更

在提出程式碼變更之前，請檢閱前一節。本節記載如何執行此操作。

當您貢獻程式碼時，您聲明該貢獻是您的原創作品，而且您根據專案的開源授權將作品授權給專案。無論您是否明確陳述，透過拉取要求、電子郵件或其他方式提交任何受版權保護的資料，即表示您同意根據專案的開源授權授權該資料，並保證您有合法權限這麼做。

複製 Apache Spark™ 原始碼

如果您有興趣使用最新的開發中程式碼，或對 Apache Spark 開發有興趣，您可以從 Git 檢出主分支

# Master development branch
git clone git://github.com/apache/spark.git

下載 Spark 後，您可以在文件頁面上找到安裝和建置的說明。

JIRA

一般而言，Spark 使用 JIRA 追蹤邏輯問題，包括錯誤和改進，並使用 GitHub 拉取要求管理特定程式碼變更的檢閱和合併。也就是說，JIRA 用於描述應該修正或變更的內容，以及高階方法，而拉取要求則描述在專案原始碼中實作該變更的方式。例如，主要的設計決策會在 JIRA 中討論。

找出變更所屬的現有 Spark JIRA。
1. 如果要建立變更來解決 JIRA 中現有的問題，請不要建立新的 JIRA；請加入現有的討論並開始作業
2. 尋找從 JIRA 連結的現有拉取要求，以了解是否有人已經在處理該 JIRA
如果變更是新的，通常需要一個新的 JIRA。但是，微不足道的變更，其中應該變更的內容與應該如何變更的內容幾乎相同，則不需要 JIRA。範例：修正 Foo scaladoc 中的錯字
如果需要，請建立新的 JIRA
1. 提供描述性的標題。「更新網路使用者介面」或「排程器中的問題」並不足夠。「Kafka 串流支援無法在 YARN 集群模式中處理空佇列」很好。
2. 撰寫詳細的說明。對於錯誤報告，理想情況下應包括問題的簡短重現。對於新功能，可能包括設計文件。
3. 設定必填欄位
  1. 問題類型。一般來說，Spark 中唯一使用的類型只有 Bug、改善和新功能。
  2. 優先順序。設定為重大或以下；較高的優先順序通常由提交者保留設定。主要例外是正確性或資料遺失問題，可以標示為阻擋者。JIRA 傾向於在優先順序欄位值中將「規模」和「重要性」混為一談。它們的意義大致如下
    1. 阻擋者：沒有這個變更就沒有意義，因為這個版本會對大量的少數使用者無法使用。正確性和資料遺失問題應視為其目標版本的阻擋者。
    2. 重大：大量的少數使用者沒有這個功能，而且/或者很難找到解決方法
    3. 主要：少數使用者沒有這個功能，而且有解決方法
    4. 次要：利基使用案例缺少一些支援，但它不會影響使用或很容易找到解決方法
    5. 瑣碎：一個不錯的變更，但不太可能在實務上造成任何問題
  3. 元件
  4. 影響版本。對於 Bug，至少指定一個已知會出現問題或需要變更的版本
  5. 標籤。使用不廣泛，除了下列
    - correctness：正確性問題
    - data-loss：資料遺失問題
    - release-notes：變更的影響需要在版本說明中提及。JIRA 或 pull request 應包含適合納入版本說明的詳細資料 – 參閱下方的「文件文字」。
    - starter：適合新貢獻者的簡單小變更
  6. 文件文字：對於需要在版本說明中輸入條目的問題，這應包含版本管理員應包含在版本說明中的資訊。這應包含受影響行為的簡短摘要，以及已變更行為的詳細資料。可以在開啟 JIRA 時暫時填寫，但問題解決時可能會需要用最終詳細資料更新。
4. 不要設定下列欄位
  1. 修正版本。這只會在解決時由提交者指定。
  2. 目標版本。這會由提交者指定，以表示已接受 PR，可能在目標版本中修正。
5. 不要包含修補程式檔案；pull request 用於提出實際的變更。
如果變更是一個大的變更，請考慮在 dev@spark.apache.org 上邀請討論問題，然後再繼續實作變更。

拉取請求

在 Apache Spark 中建立拉取請求前，請務必確認測試能否在您的分支上通過，因為我們的 GitHub Actions 工作流程會自動為您的拉取請求/後續提交執行測試，而每次執行都會消耗 Apache Spark 儲存庫中 GitHub Actions 的有限資源。下列步驟將帶您完成此流程。

如果您尚未分岔 GitHub 儲存庫，請前往 https://github.com/apache/spark
前往您分岔的儲存庫中的「動作」標籤，並啟用「建置與測試」和「回報測試結果」工作流程
複製您的分岔並建立一個新分支
考量是否需要新增或更新文件或測試作為變更的一部分，並視需要新增。
1. 新增測試時，請務必讓測試具有自我描述性。
2. 此外，當您的拉取請求目標為修正特定問題時，您應考慮在測試中撰寫 JIRA ID。實際上，通常會在 JIRA 類型為錯誤或 PR 新增幾個測試到現有測試類別時新增。請參閱下列範例
  - Scala
    test("SPARK-12345: a short description of the test") { ...
  - Java
    @Test public void testCase() { // SPARK-12345: a short description of the test ...
  - Python
    def test_case(self): # SPARK-12345: a short description of the test ...
  - R
    test_that("SPARK-12345: a short description of the test", { ...
考量是否需要新增或更新基準結果作為變更的一部分，並視需要透過在您的分岔儲存庫中執行基準來新增基準結果。
使用 ./dev/run-tests 執行所有測試，以驗證程式碼是否仍會編譯、通過測試和通過樣式檢查。如果樣式檢查失敗，請檢閱下列程式碼樣式指南。
將提交推送到您的分支。這將觸發您分岔儲存庫上的「建置與測試」和「回報測試結果」工作流程，並開始測試和驗證您的變更。
針對 apache/spark 的 master 分支開啟拉取請求。（只有在特殊情況下才會針對其他分支開啟 PR）。這將觸發 Spark 儲存庫中的「拉取請求上*」工作流程，該工作流程會在「您的」分岔儲存庫上尋找/觀察成功的執行工作流程（如果正在執行，則會等待）。
1. PR 標題應採用 [SPARK-xxxx][組件] 標題 格式，其中 SPARK-xxxx 為相關的 JIRA 編號，組件 為 spark-prs.appspot.com 上顯示的 PR 類別之一，而標題可以是 JIRA 標題或描述 PR 本身的更具體標題。
2. 如果 pull request 仍為進行中，因此尚未準備好合併，但需要推送到 GitHub 以利審查，則在組件後加上 [WIP]。
3. 考慮識別處理變更程式碼的提交者或其他貢獻者。在 GitHub 中找到檔案並按一下「Blame」以查看逐行註解，了解最後變更程式碼的人員。您可以在 PR 說明中加入 @username 以立即 ping 他們。
4. 請聲明這項貢獻為您的原創作品，且您根據專案的開放原始碼授權將作品授權給專案。
如有相關的 JIRA，將標示為「進行中」，且您的 pull request 會自動連結到該 JIRA。您不需要是 JIRA 的受讓人即可處理 JIRA，但歡迎您留言表示已開始處理。
如果您的 pull request 有變更與 SparkR 相關，AppVeyor 會自動觸發以在 Windows 上測試 SparkR，大約需要一小時。與上述步驟類似，修正失敗並推入新的提交，這將要求 AppVeyor 重新測試。

審查流程

其他審查者，包括提交者，可以針對變更發表意見並建議修改。只需將更多提交推送到同一分支即可加入變更。
鼓勵社群中的每個人進行熱烈、有禮貌且快速的技術辯論。結果可能是拒絕所有變更。
請記住，對 Spark 的較重要部分（例如其核心和 SQL 組件）的變更將受到更多審查，並且可能需要比其他變更更多的測試和正確性證明。
審查者可以透過留言表示變更適合合併，例如：「我覺得這個修補程式看起來不錯」。Spark 使用 LGTM 公約來表示對修補程式技術簽核的最高層級：只需留言「LGTM」即可。這特別表示：「我已仔細審查，並承擔與我親自撰寫修補程式相同的責任」。如果您留言 LGTM，您將預期協助修補程式的錯誤或後續問題。持續、明智地使用 LGTM 是獲得社群廣泛認可的絕佳方式，證明您是一位審查者。
有時，其他變更會合併，與您的 pull request 變更衝突。在衝突解決之前，無法合併 PR。例如，可以透過加入遠端來持續追蹤上游變更，方法是 git remote add upstream https://github.com/apache/spark.git，執行 git fetch upstream，接著執行 git rebase upstream/master，再手動解決衝突，然後將結果推送到您的分支。
嘗試對討論做出回應，而不是讓回覆之間相隔好幾天

關閉您的 pull request / JIRA

如果變更獲得接受，它將會合併，而 pull request 將會自動關閉，還有任何相關的 JIRA（如果有的話）
- 請注意，在罕見的情況下，您被要求針對除了 master 之外的分支開啟 pull request，您實際上必須手動關閉 pull request
- JIRA 將會指派給變更的主要貢獻者，作為給予認可的方式。如果 JIRA 沒有及時關閉和/或指派，請在 JIRA 上留言。
如果您的 pull request 最終遭到拒絕，請立即關閉它
- … 因為提交者無法直接關閉 PR
- 如果提交者留言表示「介意關閉這個 PR 嗎？」，Apache 中的自動化程序將會在約一週後自動關閉 pull request。這表示提交者特別要求關閉它。
如果 pull request 幾乎沒有或完全沒有受到關注，請考慮改善說明或變更本身，並在幾天後再次 ping 可能的審閱者。考慮提出較容易納入的變更，例如較小和/或較不具侵入性的變更。
如果它已經過審閱，但在幾週後仍未被採用，在向最相關的審閱者徵求審閱後，或得到中立的反應，結果可能會被視為「溫和的拒絕」。在這種情況下，建議撤回並關閉 PR。
如果 pull request 被關閉，因為它被認為不是解決 JIRA 的正確方法，請讓 JIRA 保持開啟。但是，如果審閱明確表示 JIRA 中指出的問題不會透過任何 pull request 來解決（不是問題，不會修復），那麼也請解決 JIRA。

程式碼風格指南

請遵循現有程式碼庫的風格。

對於 Python 程式碼，Apache Spark 遵循 PEP 8，但有一個例外：程式碼行可以長達 100 個字元，而不是 79 個字元。
對於 R 程式碼，Apache Spark 遵循 Google 的 R 風格指南，但有三個例外：程式碼行可以長達 100 個字元，而不是 80 個字元，函式名稱沒有限制，但它有小寫開頭的後綴，且允許 S4 物件/方法。
對於 Java 程式碼，Apache Spark 遵循 Oracle 的 Java 程式碼慣例和以下的 Scala 指南。後者較為優先。
對於 Scala 程式碼，Apache Spark 遵循官方 Scala 風格指南和 Databricks Scala 指南。後者較為優先。若要格式化 Scala 程式碼，請在提交 PR 之前執行 ./dev/scalafmt。

如有疑問

如果您不確定某項內容的正確樣式，請嘗試遵循現有程式碼庫的樣式。查看程式碼中是否有其他範例使用您的功能。您也可以隨時在 dev@spark.apache.org 清單中詢問，或詢問提交者。

行為準則

Apache Spark 專案遵循 Apache 軟體基金會行為準則。行為準則適用於 Apache 軟體基金會管理的所有空間，包括 IRC、所有公開和私人郵件清單、問題追蹤器、Wiki、部落格、Twitter，以及我們的社群使用的任何其他通訊管道。針對實體活動（例如會議）的特定行為準則已編纂在已發布的 ASF 反騷擾政策中。

我們預期參與 Apache 社群（正式或非正式）的每個人，或聲稱與基金會有任何關聯的人，在任何與基金會相關的活動中，特別是在代表 ASF 擔任任何職位時，都能遵守此行為準則。

此準則並非詳盡無遺或完整。其目的是提煉我們對協作、共享環境和目標的共同理解。我們預期它將在精神上和文字上得到遵循，以便它能豐富我們所有人和我們參與的技術社群。

有關更多資訊和具體指南，請參閱 Apache 軟體基金會行為準則。