指南

Pull Request 指南

我們希望大力鼓勵的一種理念是

在建立 PR 之前，先建立一個 issue。

目的是將問題與可能的解決方案分開。

錯誤修正： 如果您只是修正一個小錯誤，可以直接提交 pull request，但我們強烈建議您提出一個 issue 詳細說明您正在修正的內容。如果我們不接受該特定修正，但又想追蹤該問題，這會很有幫助。請記住，專案維護者保留接受或拒絕傳入 PR 的權利，因此最好將問題與修復問題的程式碼分開。在某些情況下，專案維護者可能會要求您在繼續之前從 PR 建立一個單獨的 issue。

重構： 對於小的重構，它可以是一個獨立的 PR，詳細說明您正在重構什麼以及原因。如果存在疑慮，專案維護者可能會要求您在繼續之前為 PR 建立一個 #SIP。

功能/大型變更： 如果您打算變更公開 API，或對實作進行任何重要的變更，我們要求您提出一個新的 issue 作為 #SIP (Superset Improvement Proposal，Superset 改善提案)。這讓我們可以在您投入大量精力之前就您的提案達成協議。歡迎您連同 SIP 一起提交 PR（有時對於示範是必要的），但在 SIP 獲得批准之前，我們不會審閱/合併程式碼。

一般而言，小的 PR 總是比大的 PR 更容易審閱。最佳實務是將您的工作分解為較小的獨立 PR，並參照同一個 issue。這將大大縮短周轉時間。

如果您希望分享尚未準備好合併的工作，請建立一個草稿 PR。這將使維護者和 CI 執行器能夠優先處理成熟的 PR。

最後，永遠不要提交會將 master 分支置於損壞狀態的 PR。如果 PR 是完成大型功能的多個 PR 的一部分，並且無法單獨工作，您可以建立一個功能分支，並將所有相關的 PR 合併到功能分支中，然後再從功能分支建立到 master 的 PR。

協定

撰寫

• 填寫 PR 範本的所有部分。

• 使用下列其中一個語意前綴為 PR 命名（靈感來自Karma）

  • feat（新功能）
  • fix（錯誤修正）
  • docs（文件變更）
  • style（格式化、遺失的分號等；無應用程式邏輯變更）
  • refactor（重構程式碼）
  • test（新增遺失的測試、重構測試；無應用程式邏輯變更）
  • chore（更新任務等；無應用程式邏輯變更）
  • perf（與效能相關的變更）
  • build（建置工具、Docker 設定變更）
  • ci（測試執行器、GitHub Actions 工作流程變更）
  • other（不對應於上述的變更 -- 應該很少！）
  • 範例
    • feat: 將圖表匯出為 ZIP 檔案
    • perf(api): 改善 API 資訊效能
    • fix(chart-api): 快取指示器始終顯示值已快取

• 如果尚未準備好審閱，請在標題中新增前綴 [WIP]（WIP = 進行中）。我們建議先建立一個帶有 [WIP] 的 PR，並在您通過 CI 測試並至少閱讀過一次您的程式碼變更後再移除它。

• 如果您認為您的 PR 貢獻了一個可能造成重大變更的內容，請在語意前綴之後但在 PR 標題中的冒號之前加上 !，例如：feat!: Added foo functionality to bar

• 螢幕截圖/GIF： 使用者介面的變更需要變更前/後的螢幕截圖，或用於互動的 GIF

  • 建議的擷取工具（Kap、LICEcap、Skitch）
  • 如果未提供螢幕截圖，提交者將使用 need:screenshot 標籤標記 PR，並且在提供螢幕截圖之前不會審閱。

• 相依性： 請小心新增新的相依性，並避免不必要的相依性。

  • 對於 Python，請將其包含在 pyproject.toml 中，表示任何特定限制，並在 requirements.txt 中釘選到特定版本，以確保應用程式建置是確定性的。
  • 對於 TypeScript/JavaScript，請在 package.json 中包含新的程式庫

• 測試： pull request 應包含測試，可以是 doctest、單元測試或兩者。請務必解決所有錯誤和測試失敗。請參閱測試以了解如何執行測試。

• 文件： 如果 pull request 新增了功能，則應在同一個 PR 中更新文件。

• CI： 在所有 CI 測試通過之前，審閱者不會審閱程式碼。有時可能會出現不穩定的測試。您可以關閉並開啟 PR 以重新執行 CI 測試。如果問題仍然存在，請回報。在 CI 修復程式部署到 master 後，請重新整理您的 PR。

• 程式碼覆蓋率： 請確保程式碼覆蓋率不會降低。

• 當準備好審閱時，請移除 [WIP]。請注意，它可能會在批准後立即合併，因此請確保 PR 已準備好合併，並且不要期望有更多時間進行批准後編輯。

• 如果 PR 未準備好審閱且閒置超過 30 天，我們將因閒置而關閉它。歡迎作者重新開啟並更新。

審閱

• 撰寫審閱時請使用建設性的語氣。
• 如果需要進行變更，請清楚說明在 PR 獲得批准之前需要完成哪些工作。
• 如果要求您使用一些變更來更新您的 pull request，則無需建立新的 pull request。請將您的變更推送至同一個分支。
• 提交者保留拒絕任何 PR 的權利，並且在某些情況下可能會要求作者提出 issue。

測試環境

• Apache GitHub 組織的成員可以透過建立一個僅包含 /testenv up 命令的註解，直接在 pull request 上啟動一個臨時測試環境。
  • 請注意，組織成員資格必須公開才能使此驗證正常運作。
• 可以透過在命令後指定旗標名稱（以 FEATURE_ 作為前綴）和值，為測試環境設定功能旗標。
  • 格式：/testenv up FEATURE_<功能旗標名稱>=true|false
  • 範例：/testenv up FEATURE_DASHBOARD_NATIVE_FILTERS=true
  • 可以在單一命令中設定多個功能旗標，以空格分隔
• 工作流程腳本將建立一個註解，其中包含臨時環境的位址和登入資訊。
• 一旦 PR 的 Docker 建置 CI 工作流程成功完成，就可以建立測試環境。
• 當新 commit 新增至 pull request 時，測試環境目前不會自動更新。
• 測試環境目前不支援非同步工作者，但這是計劃中的功能。
• 執行測試環境將在關閉 pull request 時關閉。

合併

• 合併 PR 至少需要一個批准。
• PR 通常在合併前保持開啟至少 24 小時。
• 合併 PR 後，關閉相應的 issue。

合併後責任

• 如果 PR 引入新的問題，專案維護者可能會聯絡 PR 作者。
• 如果發現嚴重問題（例如損壞 master 分支 CI），專案維護者可能會還原您的變更。

管理 Issue 和 PR

為了處理傳入的 issue 和 PR，提交者會讀取 issue/PR 並使用標籤標記它們以進行分類，並幫助貢獻者找出應採取行動的位置，因為貢獻者通常具有不同的專業知識。

分類目標

• 對於 issue： 分類、篩選 issue、標記作者的必要操作。
• 對於 PR： 分類、標記作者的必要操作。如果 PR 已準備好審閱，請標記審閱者的必要操作。

首先，新增類別標籤（又稱雜湊標籤）。每個 issue/PR 必須有一個雜湊標籤（垃圾郵件除外）。以 # 開頭的標籤定義 issue/PR 類型

標籤	適用於 Issue	適用於 PR
#bug	錯誤報告	錯誤修正
#code-quality	描述程式碼、架構或生產力方面的問題	重構、測試、工具
#feature	新功能請求	新功能實作
#refine	提出改進建議，例如調整邊距或改進 UI 樣式，不包括新功能、錯誤修正和重構。	改進實作，例如調整邊距或改進 UI 樣式，不包括新功能、錯誤修正和重構。
#doc	文件	文件
#question	疑難排解：安裝、在本機執行、詢問如何執行某些操作。稍後可以變更為 #bug。	不適用
#SIP	Superset 改善提案	不適用
#ASF	與 Apache 軟體基金會政策相關的任務	與 Apache 軟體基金會政策相關的任務

然後視需要新增其他類型的標籤。

• 描述性標籤（又稱點標籤）： 這些以 . 開頭的標籤描述 issue/PR 的詳細資訊，例如 .ui、.js、.install、.backend 等。每個 issue/PR 可以有零個或多個點標籤。
• 需要標籤： 這些標籤具有 need:xxx 的模式，描述進展所需的工作，例如 need:rebase、need:update、need:screenshot。
• 風險標籤： 這些標籤的格式為 risk:xxx，用於描述採用此工作所帶來的潛在風險，例如 risk:db-migration。其目的是為了更好地理解影響，並提醒大家注意需要更嚴格測試的 PR。
• 狀態標籤： 這些標籤描述狀態（abandoned、wontfix、cant-reproduce 等）。被拒絕或在未完成的情況下關閉的 Issue/PR 應具有一個或多個狀態標籤。
• 版本標籤： 這些標籤的格式為 vx.x，例如 v0.28。Issue 上的版本標籤描述的是回報錯誤的版本。PR 上的版本標籤描述的是將包含此 PR 的第一個發佈版本。

如果作者提供的標題不夠具描述性，提交者也可以更新標題以反映 Issue/PR 的內容。

如果 PR 通過了 CI 測試且沒有任何 need: 標籤，則表示已準備好進行審閱，請添加標籤 review 和/或 design-review。

如果 Issue/PR 已閒置 >= 30 天，則將被關閉。如果它沒有任何狀態標籤，請添加 inactive。

在建立 PR 時，如果您希望將其包含在特定版本中，請使用版本標籤標記它。例如，若要考慮將 PR 納入 Superset 1.1，請使用標籤 v1.1。

還原準則

還原在 master 分支中造成問題的變更，是開發過程中正常且預期的環節。在開源社群中，變更的影響不見得總是能完全理解。有鑑於此，在考慮還原時，請記住以下幾點：

• PR 作者是否能提供協助： 如果原始 PR 作者或合併程式碼的工程師能夠快速提供修復程式碼，則這表示不適合還原。
• 問題的嚴重性： 在 master 分支上，問題有多嚴重？是否阻礙了專案的進展？是否會影響使用者？有多少比例的使用者會遇到問題？
• 要還原的變更大小： 還原單一的小型 PR 比還原大型、多 PR 的變更風險低得多。
• 要還原的變更存在時間： 還原最近合併的 PR 比還原較舊的 PR 更容易被接受。在較舊的 PR 中發現的錯誤不太可能造成廣泛的嚴重問題。
• 還原的固有風險： 還原是否會破壞關鍵功能？藥是否比疾病更危險？
• 修復的難度： 如果問題有明確的解決方案，則實作和合併修復程式碼可能比還原更好。

如果您確定還原是可取的，執行還原的貢獻者有責任：

• 聯絡相關人員： 應聯絡 PR 的作者以及合併該工作的工程師，並告知他們將要進行還原。
• 提供簡潔的重現步驟： 確保 PR 的原始作者可以清楚理解並重現問題。
• 讓還原通過程式碼審查： 還原必須經過另一位提交者的核准。

設計準則

大小寫準則

句子大小寫

在 UI 中所有內容都使用句子大小寫 (以下 ** 除外)。

句子大小寫主要是小寫。僅將第一個單字的起始字元大寫，以及其他需要大寫的單字，例如：

• 專有名詞。 產品中的物件不視為專有名詞，例如儀表板、圖表、已儲存的查詢等。專有的功能名稱，例如 SQL Lab、Preset Manager 是視為專有名詞。
• 縮寫 (例如 CSS、HTML)
• 當您引用 UI 標籤本身從句子大小寫大寫時 (例如頁面標題 - 儀表板頁面、圖表頁面、已儲存的查詢頁面等)
• 反映在 UI 中的使用者輸入。例如，使用者命名了儀表板標籤。

句子大小寫 vs. 標題大小寫： 標題大小寫：「A Dog Takes a Walk in Paris」 句子大小寫：「A dog takes a walk in Paris」

為什麼使用句子大小寫？

• 它通常被認為是最快的閱讀方式。
• 它是區分普通名詞和專有名詞的最簡單形式。

如何引用 UI 元素

當撰寫關於 UI 元素的內容時，請使用與 UI 中相同的大小寫。

例如，如果輸入欄位標記為「Name」，則您應將其稱為「Name 輸入欄位」。同樣地，如果按鈕的標籤為「Save」，則將其稱為「Save 按鈕」是正確的。

如果產品頁面的標題為「Settings」，您應在寫作中如下引用：「在 Settings 頁面上編輯您的個人資訊」。

產品頁面通常會與其包含的物件具有相同的標題。在這種情況下，請按照 UI 中顯示的樣子引用頁面，並將物件視為普通名詞。

• 在儀表板頁面上上傳儀表板
• 前往儀表板
• 檢視儀表板
• 檢視所有儀表板
• 在 CSS 範本頁面上上傳 CSS 範本
• 您儲存的查詢將會顯示在「已儲存的查詢」頁面上
• 在 SQL Lab 中建立自訂查詢，然後建立儀表板

**句子大小寫的例外情況**

• 輸入標籤、按鈕和 UI 標籤全為大寫
• 使用者輸入的值 (例如欄名稱、SQL Lab 標籤名稱) 應使用其原始大小寫

程式語言慣例

Python

config.py 中的參數（可透過 Flask app.config 字典存取）假定為始終定義的，因此應直接透過以下方式存取：

blueprints = app.config["BLUEPRINTS"]

而不是：

blueprints = app.config.get("BLUEPRINTS")

或類似的內容，因為後者會導致類型問題。前者類型為 List[Callable]，而後者類型為 Optional[List[Callable]]。

類型標註 / 類型提示

為了確保清晰、一致和可讀性，所有新的函式都應使用 類型提示 並包含文件字串。

請注意，根據 PEP-484，沒有提出明確列出引發例外情況的語法，因此建議將此資訊放入文件字串中，即：

import math
from typing import Union


def sqrt(x: Union[float, int]) -> Union[float, int]:
    """
    Return the square root of x.

    :param x: A number
    :returns: The square root of the given number
    :raises ValueError: If the number is negative
    """

    return math.sqrt(x)

TypeScript

完全支援 TypeScript，並且建議使用 TypeScript 來撰寫所有新的前端元件。修改現有的函式/元件時，歡迎遷移至 TypeScript，但並非必要。可以在 #9162 和 #9180 中找到將函式/元件遷移至 TypeScript 的範例。