提取請求

• 設定您的本機環境
  • 步驟 1：Fork
  • 步驟 2：建置
  • 步驟 3：Branch
• 進行變更
  • 步驟 4：程式碼
  • 步驟 5：Commit
    • Commit 訊息指南
  • 步驟 6：Rebase
  • 步驟 7：測試
  • 步驟 8：Push
  • 步驟 9：開啟提取請求
  • 步驟 10：討論與更新
    • 核准與請求變更工作流程
  • 步驟 11：Landing
  • 持續整合測試

設定您的本機環境

步驟 1：Fork

Fork 此專案在 GitHub 上，並在本機端複製您的 fork。

$ git clone git@github.com:username/electron.git
$ cd electron
$ git remote add upstream https://github.com/electron/electron.git
$ git fetch upstream

步驟 2：建置

建置步驟與相依性會因您的作業系統而略有不同。請參閱這些關於在本機端建置 Electron 的詳細指南

• 在 macOS 上建置
• 在 Linux 上建置
• 在 Windows 上建置

一旦您在本機端建置專案後，即可開始進行變更！

步驟 3：Branch

為了讓您的開發環境井然有序，請建立本機分支來存放您的工作。這些分支應直接從 main 分支分支出來。

$ git checkout -b my-branch -t upstream/main

進行變更

步驟 4：程式碼

大多數針對 electron/electron 儲存庫開啟的提取請求都包含對 shell/ 資料夾中的 C/C++ 程式碼、lib/ 資料夾中的 JavaScript 程式碼、docs/api/ 中的文件或 spec/ 資料夾中的測試所做的變更。

請務必不時在任何程式碼變更上執行 npm run lint，以確保它們遵循專案的程式碼樣式。

請參閱程式碼樣式以取得更多關於修改專案不同部分的程式碼時的最佳實務資訊。

步驟 5：Commit

建議將您的變更在個別 commit 中進行邏輯分組。許多貢獻者發現，跨多個 commit 分割的變更更容易審查。提取請求中的 commit 數量沒有限制。

$ git add my/changed/files
$ git commit

請注意，多個 commit 在被 landed 時會被壓縮。

Commit 訊息指南

一個好的 commit 訊息應描述變更了什麼以及原因。「Electron」專案使用語意化 commit 訊息來簡化發行流程。

在提取請求可以合併之前，它必須具有帶有語意前綴的提取請求標題。

具有語意前綴的 commit 訊息範例

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on Linux

常見前綴

• fix: Bug 修正
• feat: 新功能
• docs: 文件變更
• test: 新增遺失的測試或更正現有測試
• build: 影響建置系統的變更
• ci: 對我們的 CI 組態檔與腳本的變更
• perf: 改善效能的程式碼變更
• refactor: 既不修正錯誤也不新增功能的程式碼變更
• style: 不影響程式碼意義的變更 (linting)

撰寫 commit 訊息時要記住的其他事項

1. 第一行應
   • 包含變更的簡短描述（最好少於 50 個字元，且不超過 72 個字元）
   • 完全以小寫字母表示，但專有名詞、縮寫和指代程式碼的詞（如函式/變數名稱）除外
2. 將第二行留空。
3. 將所有其他行換行在 72 個字元處。

重大變更

在其選用主體或頁尾區段開頭具有文字 BREAKING CHANGE: 的 commit 會引入重大 API 變更（與語意化版本控制中的 Major 相關）。重大變更可以是任何類型的 commit 的一部分。例如，fix:、feat: 和 chore: 類型以及任何其他類型都有效。

請參閱 conventionalcommits.org 以取得更多詳細資訊。

步驟 6：Rebase

一旦您 commit 變更後，最好使用 git rebase（而不是 git merge）將您的工作與主要儲存庫同步。

$ git fetch upstream
$ git rebase upstream/main

這可確保您的工作分支具有來自 electron/electron main 的最新變更。

步驟 7：測試

Bug 修正和功能應始終附帶測試。已提供測試指南，以簡化流程。查看其他測試以了解其結構也很有幫助。

在提取請求中提交變更之前，請務必執行完整的測試套件。若要執行測試

$ npm run test

請確保 linter 沒有回報任何問題，且所有測試都通過。請勿提交未通過任一檢查的修補程式。

如果您正在更新測試，且想要執行單一規格以進行檢查

$ npm run test -match=menu

上述指令只會執行符合 menu 的規格模組，這對於任何正在測試的人來說都很有用，否則這些測試將會在測試週期的最後。

步驟 8：Push

一旦您的 commit 準備就緒（通過測試和 linting），即可開始開啟提取請求的流程，方法是將您的工作分支 push 到您在 GitHub 上的 fork。

$ git push origin my-branch

步驟 9：開啟提取請求

從 GitHub 內部，開啟新的提取請求會向您顯示一個範本，您應填寫該範本。它可以在此處找到。

如果您未充分填寫此範本，您的 PR 可能會因為維護人員尋求更多資訊或釐清模糊之處而延遲合併。

步驟 10：討論與更新

您可能會收到關於您的提取請求的回饋或變更請求。這是提交流程的重要環節，因此請不要氣餒！有些貢獻者可能會立即簽署提取請求。其他人可能會提供詳細的評論或回饋。這是評估變更是否正確且必要的必要流程。

若要對現有的提取請求進行變更，請對您的本機分支進行變更，新增一個包含這些變更的新 commit，然後將其 push 到您的 fork。GitHub 將會自動更新提取請求。

$ git add my/changed/files
$ git commit
$ git push origin my-branch

有許多更進階的機制可以使用 git rebase 管理 commit，但超出本指南的範圍。

如果您正在等待某事的答案，請隨時在提取請求中發佈評論以 ping 審查人員。如果您遇到似乎不熟悉的單字或縮寫，請參閱此詞彙表。

核准與請求變更工作流程

所有提取請求都需要您修改區域的程式碼擁有者的核准才能夠 landed。每當維護人員審查提取請求時，他們可能會請求變更。這些變更可能很小，例如修正錯字，或者可能涉及實質性的變更。這些請求旨在提供協助，但有時可能會顯得唐突或沒有幫助，尤其是在它們沒有包含關於如何變更它們的具體建議時。

請盡量不要氣餒。如果您覺得審查不公平，請說出來或尋求其他專案貢獻者的意見。通常，此類評論是審查人員沒有花費足夠時間進行審查的結果，並且並非惡意。這些困難通常可以透過一點耐心來解決。也就是說，審查人員應提供有用的回饋。

步驟 11：Landing

為了要 landed，提取請求需要至少一位 Electron 程式碼擁有者審查並核准，並通過 CI。之後，如果沒有其他貢獻者反對，則可以合併提取請求。

恭喜您，並感謝您的貢獻！

持續整合測試

每個提取請求都會在持續整合 (CI) 系統上進行測試，以確認它在 Electron 支援的平台上運作。

理想情況下，提取請求將在所有 CI 平台上通過（「呈現綠色」）。這表示所有測試都通過，且沒有 linting 錯誤。然而，CI 基礎架構本身在特定平台上失敗或所謂的「不穩定」測試失敗（「呈現紅色」）的情況並不少見。每個 CI 失敗都必須手動檢查以判斷原因。

當您開啟提取請求時，CI 會自動啟動，但只有核心維護人員可以重新啟動 CI 執行。如果您認為 CI 給出誤判，請要求維護人員重新啟動測試。