Gopls：貢獻

歡迎貢獻！但是，開發進展迅速，我們的評審能力有限。因此，在提交 CL 之前，請務必：

如果尚不存在，請先為 bug 或功能請求**提交一個 issue**。這使我們能夠識別重複的請求，或將特定問題合併到更普遍的問題中，並評估問題的優先順序。
請透過在 issue 下評論，或者如果您能夠，請將 issue 分配給自己，**認領它**。這有助於我們避免兩個人處理同一個問題。
對於任何複雜度的 CL，請在 issue 跟蹤器中**提出一個實現計劃**。在陷入程式碼評審細節之前，先進行高層次的計劃討論會更有效率。

當您提交 CL 時，應包含：

一個**CL 描述**，總結更改，說明其必要性，從高層次進行解釋，對比更明顯或更簡單的實現方式，並連結到相關的 issue。
**測試**（整合測試或標記測試）；
針對新功能或修改的功能的**文件**；以及
新功能或重要更改的**釋出說明**。

在程式碼評審期間，請解決所有評審員的評論。有些評論會導致直接的程式碼更改；另一些則需要更復雜的響應。當評審員提問時，最好的回應通常不是直接回答，而是修改程式碼以避免提出問題，例如透過使程式碼自解釋。如果您不同意某個評論，指出評審員的錯誤，或者提議在後續更改中解決某個評論（並在當前 CL 中留下 TODO 評論），都是可以的。但請不要在未採取行動的情況下忽略評論，這可能會導致評審員重複自己，或者導致嚴重問題被忽視。

更多詳情，請參閱 Go 專案的貢獻指南。

查詢 issue

所有 gopls issue 都貼有相應的標籤（請參閱gopls 標籤）。適合貢獻者處理的 issue 會額外標記 help-wanted 標籤。

在開始處理某個 issue 之前，請留下一條評論表示您認領了它。

入門

gopls 的大部分邏輯位於 golang.org/x/tools/gopls/internal 目錄下。有關程式碼組織的概述，請參閱 design/implementation.md。

構建

要構建一個包含您更改的 gopls 版本

cd /path/to/tools/gopls
go install

為了確認您正在使用正確的 gopls 版本進行測試，請檢查您的 gopls 版本是否如下所示：

$ gopls version
golang.org/x/tools/gopls master
    golang.org/x/tools/gopls@(devel)

獲取幫助

直接聯絡 gopls 團隊的最佳方式是透過 gophers slack 上的 #gopls-dev 頻道。請隨時就您的貢獻或一般的貢獻問題提問。

錯誤處理

為了使用者體驗，只要可行，重要的邏輯錯誤就不會導致伺服器崩潰，這一點很重要。

Go 程式的表示形式非常複雜。包元資料的匯入圖、已解析檔案的語法樹及其相關的型別資訊共同構成了龐大的 API 表面積。即使輸入有效，也有許多邊緣情況需要考慮，當您考慮缺少匯入、解析錯誤和型別錯誤時，這種情況會呈指數級增長。

當您的邏輯必須處理您認為“不可能發生”的錯誤時，您應該怎麼做？

如果可能返回錯誤，請使用 bug.Errorf 函式將錯誤返回給使用者，同時還將該 bug 記錄在 gopls 的快取中，以降低被忽略的可能性。
如果繼續操作是安全的，您可以呼叫 bug.Reportf 來記錄錯誤並照常繼續。
如果無法繼續，請呼叫 bug.Fatalf 來記錄錯誤，然後使用 log.Fatalf 停止程式。如果存在 recover 處理程式可能挽救局面的情況，您也可以使用 bug.Panicf。
只有當您可以在本地證明錯誤是不可能的，才應該呼叫 log.Fatal。如果錯誤可能因某些輸入而發生，無論可能性多麼小，您都應使用上述方法之一。此外，如果安全性的證明依賴於程式碼庫中廣泛分佈的不變式，那麼您應該改用 bug.Panicf。

另請注意，恐慌（panicking）比 log.Fatal 更可取，因為它允許 VS Code 的崩潰報告能夠識別和捕獲堆疊。

透過 bug.Errorf 及其類似函式報告的 bug 可以透過 gopls bug 命令檢索，該命令會開啟一個 GitHub Issue 模板，並填充每個 bug 的摘要及其頻率。bug 的文字會被仔細地列印到 stdout，以避免與 GitHub 共享使用者名稱和錯誤訊息字串（可能包含專案識別符號）。使用者被邀請在願意的情況下分享。

測試

更改後執行測試的常用命令是：

gopls$ go test -short ./...

（-short 標誌會跳過一些執行緩慢的測試。TryBot 生成器會在多種平臺上執行完整的測試集。）

Gopls 測試混合了兩種型別。

標記測試將每個測試場景表達在一個獨立的文字檔案中，該檔案包含目標 .go、go.mod 和 go.work 檔案，其中註釋中的特殊註解驅動測試。這些測試通常易於編寫和快速迭代，但表達能力有限。
整合測試是常規的 Go func Test(*testing.T) 函式，它們對一個假的 LSP 啟用客戶端編輯器 API 進行一系列呼叫。該 API 允許您開啟和編輯檔案、導航到定義、呼叫其他 LSP 操作以及斷言狀態屬性。

由於 LSP 的非同步性質，整合測試會斷言編輯器最終必須達到的狀態，即使程式很快出錯，也可能需要一段時間才能將錯誤報告為在幾分鐘內未能達到期望狀態。我們建議您設定 GOPLS_INTEGRATION_TEST_TIMEOUT=10s 來減少除錯時的整合測試超時時間。

當整合測試失敗時，它們會列印客戶端和伺服器之間 LSP 會話的日誌。雖然冗長，但一旦您學會閱讀它們，它們對除錯非常有幫助。

如果您需要幫助，請隨時聯絡 gopls 團隊。

CI

當您郵寄 CL 並您或另一位貢獻者在 Gerrit 中分配 Run-TryBot=1 標籤時，TryBots 將在 golang.org/x/tools 和 golang.org/x/tools/gopls 模組中執行測試，如上所述。

此外，一個名為“gopls-CI”的附加通道將由 Kokoro 執行，這是一個類似 Jenkins 的 Google 基礎設施，用於執行 Dockerized 測試。這使我們能夠在 TryBots 中難以新增的各種環境中執行 gopls 測試。特別是，Kokoro 會在舊版 Go 版本上執行測試，這些版本已不再受 TryBots 支援。按照該政策，對這些舊版 Go 版本的支援是盡力而為的，測試失敗可能會被跳過而不是修復。

與 TryBots 一樣，Kokoro 執行由 Run-TryBot=1 標籤觸發，但與 TryBots 不同的是，如果“gopls-CI”結果在 Gerrit 中被移除，它們不會自動重新執行。要強制對包含 Run-TryBot=1 標籤的 CL 重新執行 Kokoro CI，您可以在 Gerrit 中回覆“kokoro rerun”進行評論。

除錯

除錯更改的最簡單方法是使用偵錯程式執行單個 gopls 測試。

另請參閱故障排除。

文件

除測試新行為的測試外，每個新增或更改功能的 CL 都應包含：

一個**釋出說明**，簡要說明更改；以及
在功能索引中**全面的文件**。

釋出說明應放在以即將釋出的版本命名的檔案中，例如 release/v0.16.0.md。（如果您的功能是釋出後新增的第一個功能，請建立該檔案。）

設計文件

本文件的原始碼可以在 golang.org/x/tools/gopls/doc 下找到。