總覽

所有程式碼和文件的變更都應該 提交。 專案的 GitHub 套件庫。

Most projects have a dedicated contribution guide with details specific to that project, or specific types of contribution. This documentation can be found on Read the Docs. For example, Briefcase's documentation contains contribution guides for both code and documentation.

所有提交的作品都必須遵守 BeeWare 行為規範](/社群/行為/行為規範/) 行為準則。

更改注意事項

幾個 BeeWare 專案，特別是 Briefcase 和 Toga，要求每個 拉取請求都要提交變更備註。這些變更說明 編譯在一起，產生新版本的發行說明。 新版本的釋出說明。

BeeWare 使用 Towncrier 來管理變更記錄。 管理變更備註。

應在 changes 目錄中建立變更備註檔案，並以下列格式命名 使用此格式命名：

<PR/Issue #>.<Change Type>.rst

例如，修正 GitHub 問題 #42 的拉取請求會命名為 42.bugfix.rst`。如果拉取請求與特定的 問題相關聯，則可以使用拉取請求編號來代替。您可能需要 創建拉取請求無變更備註，以獲得分配的拉取請求編號，然後推送該更新。 編號，然後再推送包含變更備註與 新分配的拉取請求編號。

變更備註的變更類型應為下列其中之一：

  • 功能
  • 修正錯誤
  • 文件
  • 刪除
  • 雜項

misc 種類保留給不影響使用者的變更，且不需要在發行公告中註明。 不需要在發行公告中註明的變更。小的排版修正 文件中的小排版修正、CI 設定的更新，以及尚未正式發行的功能的錯誤修正。 尚未正式發行的功能的錯誤修正，這些都是 使用 misc 標記描述的功能。

變更備註應該是一行文字，從使用者的角度提供高層次的 的摘要，而非深入的技術描述或實施細節。 技術描述或實施細節。它有別於 提交資訊不同。提交資訊描述了所做的事情，以便 未來的開發人員可以了解變更的原因。變更說明 是 「面向使用者 」的描述，用新的功能來描述。 變更的結果。將變更說明看成 變更注意事項是宣告變更的新聞稿，而不是提交說明。 提交描述。

例如，如果您修正了一個由日期處理引起的錯誤，提交訊息或拉取請求的描述可能會是 訊息或拉取請求的描述可能是

在 DateWidget 驗證鏈中新增 MM-DD-YYYY 格式驗證器。 鏈。

此處描述了對實作所做的變更 - 詳細資訊 會對檢閱程式碼的人有所幫助。但是 相應的變更備註可能會寫成這樣

日期 widget 現在可以接受 US 格式的日期。

這描述了終端使用者將會體驗到的功能變更。 使用者將會體驗到的功能變更。使用者可以閱讀此描述，而無需瞭解任何 有關實作的任何資訊。

代碼風格

BeeWare的專案使用Pre-commit來自動化 程式碼風格。這些檢查定義在 .pre-commit-config.yaml」檔中定義，並自動在 在 CI 中執行。 開啟時，會自動在 CI 中執行。

要在您的本地開發環境中自動執行預提交檢查 與每個 git commit，執行 pre-commit install。

包括預先承諾檢查：

  • Black 確保 統一的程式碼格式
  • docformatter確保 文件和註解的統一格式
  • pyupgrade 確保程式碼 使用最新的 Python 最佳實作
  • isort 確保統一的 `import 語句
  • flake8檢查常見的編碼 和語法問題
  • 驗證 TOML 檔案等結構化文件的雜項檢查，以及 移除不必要的空白

其他指引：

  • 避免在註解中使用「我們」，例如：「Loop over」而非「We loop over 過"

  • 變數、函式和方法名稱使用下劃線，而非 camelCase。 名稱

  • 使用 InitialCaps 表示類別名稱（或返回類別的工廠函式 類別)

  • Use Sphinx-style docstrings and PEP 257; type annotation with PEP 484 is optional but encouraged.

    例如：

    def function_name(param1: int, param2: str) -> bool：
    """具有類型和 docstring 的函數範例。

    :param param1：第一個參數。
    :param param2：第二個參數。

    :returns：回傳值。True 代表成功，否則為 False。
    """

  • 在測試說明文件中，說明每個測試所要展示的預期行為。 證明的預期行為。不要包含前言，例如「測試」或「確保 確保 "等前言。

  • 保留票單參照給晦澀不明的問題，這些票單具有 額外的細節，而這些細節在文件或 註解。在句子末尾包含票單編號，例如 這樣：

    def test_foo()：
    """A test docstring looks like this (#123456)."""

  • Unless otherwise specified, follow PEP 8 (with careful attention paid to Section 2).