提交 Pull Request

如果您想貢獻 ESLint 儲存庫，請使用 GitHub pull request。這是我們評估您的程式碼並將其合併到程式碼庫中的最快方式。請不要提交包含程式碼片段的 issue。這樣做意味著我們需要手動合併變更並更新任何適當的測試。這降低了您的程式碼及時包含的可能性。請使用 pull request。

開始使用

如果您想處理 pull request，並且您以前從未提交過程式碼，請按照以下步驟操作

1. 設定開發環境。
2. 如果您想實作重大變更或核心變更，請確保有一個 issue 描述您正在做的事情，並且該 issue 已被接受。您可以建立新的 issue，或者只是表明您正在處理現有的 issue。錯誤修復、文件變更和其他 pull request 不需要 issue。

在那之後，您就可以開始處理程式碼了。

使用程式碼

提交 pull request 的過程相當簡單，並且通常每次都遵循相同的模式

1. 建立新分支.
2. 進行變更.
3. Rebase 到 upstream.
4. 執行測試.
5. 再次檢查您的提交.
6. 推送您的變更.
7. 提交 pull request.

每個步驟的詳細資訊如下。

步驟 1：建立新分支

發送 pull request 的第一步是在您的 ESLint fork 中建立一個新分支。給分支一個描述性的名稱，描述您正在修復的內容，例如

git checkout -b issue1234
1

您應該在這個分支中完成 issue 的所有開發工作。

注意： 不要將多個 issue 的修復合併到一個分支中。為您正在處理的每個 issue 使用單獨的分支。

步驟 2：進行變更

依照程式碼慣例對程式碼和測試進行變更。完成後，將變更提交到您的分支

git add -A
git commit
1
2

所有 ESLint 專案都遵循Conventional Commits 來撰寫我們的提交訊息。（注意：我們不支援訊息中的可選範圍。）以下是一個提交訊息範例

tag: Short description of what you did

Longer description here if necessary

Fixes #1234
1
2
3
4
5

提交訊息的第一行（摘要）必須具有特定格式。此格式由我們的建置工具檢查。雖然提交訊息不會直接檢查，但它將用於產生 pull request 的標題，該標題將在提交 pull request 時檢查。

tag 是以下其中之一

• fix - 用於錯誤修復。
• feat - 用於向後相容的增強功能或新增回報問題的規則變更。
• fix! - 用於向後不相容的錯誤修復。
• feat! - 用於向後不相容的增強功能或功能。
• docs - 僅限文件變更。
• chore - 用於非使用者面向的變更。
• build - 僅限建置過程變更。
• refactor - 不影響 API 或使用者體驗的變更。
• test - 僅限測試檔案的變更。
• ci - 變更我們的 CI 設定檔和腳本。
• perf - 改善效能的程式碼變更。

使用您正在處理的 issue 的標籤來確定最佳標籤。

訊息摘要應為變更的單句描述，且長度必須為 72 個字元或更短。如果 pull request 解決了一個 issue，則應在提交訊息的正文中以 Fixes #1234 的格式提及 issue 編號。如果提交並未完全修復 issue，則使用 Refs #1234 而不是 Fixes #1234。

以下是一些好的提交訊息摘要範例

build: Update Travis to only test Node 0.10
fix: Semi rule incorrectly flagging extra semicolon
chore: Upgrade Esprima to 1.2, switch to using comment attachment
1
2
3

步驟 3：Rebase 到 upstream

在您發送 pull request 之前，請務必 rebase 到 upstream 來源。這確保您的程式碼在最新的可用程式碼上執行。

git fetch upstream
git rebase upstream/main
1
2

步驟 4：執行測試

在 rebase 之後，請務必再次執行所有測試，以確保沒有任何問題

npm test
1

如果存在任何失敗的測試，請更新您的程式碼，直到所有測試都通過。

步驟 5：再次檢查您的提交

在您的程式碼準備就緒後，現在是再次檢查您的提交以確保其符合我們的慣例的好時機。以下是要檢查的事項

• 提交訊息的格式正確。
• 變更不會引入功能倒退。請務必執行 npm test 以驗證您的變更，然後再提交 pull request。
• 為不相關的變更建立單獨的 pull request。包含多個不相關變更的大型 pull request 可能會在不合併的情況下關閉。
• 所有變更都必須附帶測試，即使您正在處理的功能以前沒有測試。
• 所有使用者面向的變更都必須附帶適當的文件。
• 遵循程式碼慣例。

步驟 6：推送您的變更

接下來，將您的變更推送到您的 clone

git push origin issue1234
1

如果您因為某些參考過舊而無法推送，請改為強制推送

git push -f origin issue1234
1

步驟 7：發送 pull request

現在您已準備好發送 pull request。前往您的 ESLint fork，然後依照GitHub 文件了解如何發送 pull request。

為了向 ESLint 專案提交程式碼或文件，當您發送您的第一個 pull request 時，系統會要求您簽署我們的 CLA。（閱讀更多關於 OpenJS Foundation CLA 流程，請訪問 https://cla.openjsf.org/。）

pull request 標題會從第一個提交的摘要自動產生，但可以在提交 pull request 之前編輯。

pull request 的描述應說明您做了什麼以及如何看到其效果。

當 pull request 合併時，其提交將被壓縮為一個單一提交。壓縮提交訊息的第一行將包含 pull request 的標題和 pull request 編號。pull request 標題格式很重要，因為標題用於為每個版本建立變更日誌。標籤和 issue 編號有助於建立更一致且更有用的變更日誌。

後續追蹤

一旦您的 pull request 發送出去，就輪到團隊審查它了。因此，請務必

1. 監控您的 pull request 的 GitHub Actions CI 建置狀態。如果失敗，請調查原因。我們無法合併任何原因導致 CI 建置失敗的 pull request。
2. 回覆團隊成員在 pull request 上留下的評論。請記住，我們希望幫助您完成程式碼，因此請接受我們的回饋。
3. 我們可能會要求您進行變更、rebase 或 squash 您的提交。

更新 Pull Request 標題

如果您的 pull request 標題格式不正確，系統會要求您更新它。您可以透過 GitHub 使用者介面執行此操作。

更新程式碼

如果我們要求您進行程式碼變更，則無需關閉 pull request 並建立新的 pull request。只需回到您 fork 上的分支並進行變更。然後，當您準備好時，您可以將您的變更新增到分支中

git add -A
git commit
git push origin issue1234
1
2
3

在更新程式碼時，通常最好將其他提交新增到您的分支，而不是修改原始提交，因為審查者可以輕鬆判斷哪些變更是為了回應特定審查而進行的。當我們合併 pull request 時，我們會將您分支中的所有提交壓縮為 main 分支上的單一提交。

後續提交中的提交訊息不需要任何特定格式，因為這些提交不會顯示在變更日誌中。

Rebase

如果您的程式碼已過時，我們可能會要求您 rebase。這表示我們希望您將您的變更應用於最新的 upstream 程式碼之上。請確保您已設定開發環境，然後您可以使用以下命令進行 rebase

git fetch upstream
git rebase upstream/main
1
2

您可能會發現當您嘗試 rebase 時存在合併衝突。請解決衝突，然後對您的分支進行強制推送

git push origin issue1234 -f
1