貢獻

如果您計劃投入大量精力在一個大型的 pull request 中，其中包含可能影響 Ruby LSP 長期維護的多項決策，請先開啟一個討論，以對齊方向。

ruby-lsp 儲存庫包含三個子專案

語言伺服器（ruby-lsp），位於儲存庫的頂層。大多數功能都在這裡實現，因為伺服器中實現的所有功能都適用於所有編輯器
VS Code 擴充功能，位於 vscode 目錄下。任何自訂 VS Code 功能都在這裡實現
文件網站，位於 jekyll 目錄下。Ruby LSP 和 Rails 附加元件的所有使用者文件都包含在此處

本貢獻指南按每個元件進行劃分。

初始設定

要開始為 Ruby LSP 貢獻，請確保安裝所有相依性，如下所示

在頂層執行 bundle install 將安裝 Ruby 相依性
在 jekyll 目錄中執行 bundle install 將安裝文件相依性
在 vscode 目錄中執行 yarn install 將安裝 VS Code 擴充功能的 Node.js 相依性

為伺服器貢獻

這是 ruby-lsp gem 的結構

lib/ruby_indexer：程式碼索引器，用於從工作區提取宣告
lib/ruby_lsp/*.rb：語言伺服器的基礎部分，例如 worker、佇列、處理請求等
lib/ruby_lsp/requests：請求實作。這些與語言伺服器規格一一對應
lib/ruby_lsp/listeners：Prism 分派器監聽器。伺服器的大部分基礎結構都依賴於監聽器模式，以在遍歷 AST 時最大化效能。請注意，單一請求可能依賴於多個監聽器

新增或變更現有功能時，請先在規格中識別哪個請求負責該功能。然後識別伺服器中哪個檔案實作了該請求，並開始考慮實作方式。

使用 VS Code 時，請開啟 lsp.code-workspace 檔案，而不是僅開啟常規資料夾。它包含用於有效並排使用子專案的設定

除錯

即時除錯伺服器

使用 VS Code 時，可以即時除錯目前正在執行的語言伺服器的開發執行個體

CMD/CTRL + SHIFT + P 開啟命令面板
搜尋 Debug the Ruby LSP server。此命令將在除錯模式下重新啟動伺服器，允許您使用除錯工具連線。請注意，除錯模式僅適用於關閉編輯器或 Ruby LSP 重新啟動之前
伺服器在除錯模式下啟動後，請透過前往 執行和除錯，選取 附加至現有伺服器 工作並按一下執行，來附加除錯工具
您現在應該可以在 UI 中設定中斷點，觸發請求時將會停止在這些中斷點

注意事項：由於您正在除錯您自己的編輯器中目前正在執行的語言伺服器執行個體，如果執行目前在中斷點暫停，則功能將不可用。

了解 Prism AST

Ruby LSP 使用 Prism 來剖析和了解 Ruby 程式碼。處理某個功能時，很常需要檢查給定程式碼片段的 Prism AST 結構，以便了解請求為何以特定方式觸發。

如果您正在使用 VS Code，您可以使用顯示語法樹命令來檢查整個文件或選取的 AST 結構。

對於其他編輯器，使用我們的 IRB 設定是實現相同目的的最簡單方法

bundle exec irb 以我們的設定啟動 IRB。它將為您要求所有程式庫
然後剖析您想要更了解的 Ruby 程式碼，並開始檢查

source = <<~RUBY
  class Foo
    def bar
    end
  end
RUBY

ast = Prism.parse(source).value

請查看Prism 文件以取得更多相關資訊。

追蹤 LSP 請求和回應

在 VS Code 中，您可以透過啟用追蹤來驗證伺服器中發生的情況，這允許不同層級的記錄。

{
  // Your JSON settings
  //
  // - `off`: no tracing
  // - `messages`: display requests and responses notifications
  // - `verbose`: display each request and response as JSON
  "ruby lsp.trace.server": "messages"
}

手動測試變更

在您進行變更或新增功能之後，您可以透過重新啟動語言伺服器在編輯器中驗證它。在 VS Code 中，這可以透過執行命令 Ruby LSP: restart 來達成，這將重新啟動伺服器並接收您的變更。

對於其他編輯器，您必須手動重新啟動語言伺服器才能接收最新的變更。

除錯測試

在 VS Code 中，我們建議

在 UI 中設定中斷點
開啟將會觸發該中斷點的測試
按一下範例頂端的 debug 程式碼鏡頭按鈕

或者（對於其他編輯器），在程式碼中新增 binding.b 陳述式，並在終端機中執行測試，也可以讓您除錯程式碼。

編寫測試

Ruby LSP 中有兩種測試類型。第一種類型可能很熟悉：標準 Minitest 檔案，其中包含一堆使用方法宣告語法的範例。

第二種測試類型是我們的固定裝置/期望框架。在 test/fixtures 下新增固定裝置將自動使框架針對該固定裝置執行所有請求。預設情況下，框架僅檢查功能在針對固定裝置執行時是否不會當機。這對於確保當使用較不常見的 Ruby 語法時，關鍵請求不會中斷很有用。

若要進一步檢查請求是否會中斷固定裝置，您可以將期望新增至 test/expectations/NAME_OF_THE_REQUEST，這可讓您斷言請求和固定裝置組合的預期回應。

例如，如果我們有 test/fixtures/foo.rb，則新增 test/expectations/semantic_highlighting/foo.exp.json 將使框架驗證當在 foo.rb 固定裝置中執行語義高亮時，預期會出現 foo.exp.json 回應。

請檢查現有的固定裝置和期望組合，以取得範例。

何時使用每種類型的測試

固定裝置/期望框架主要用於完整文件請求（每次都為整個檔案計算的語言伺服器功能）。

特定於位置或在不同機制下運作的請求和功能應僅使用常規 Minitest 測試。

執行測試套件

有多種可用的執行測試方法。

# Run the entire test suite
bundle exec rake

# Run only indexing tests
bundle exec rake test:indexer

# Run only language server tests (excluding indexing)
bundle exec rake test

# Using the custom test framework to run a specific fixture example
# bin/test test/requests/the_request_you_want_to_run_test.rb name_of_fixture
bin/test test/requests/diagnostics_expectations_test.rb def_bad_formatting

此外，我們使用 RuboCop 進行 Linting，並使用 Sorbet 進行類型檢查。

# Run linting
bundle exec rubocop

# Run type checking
bundle exec srb tc

為 VS Code 擴充功能貢獻

開始本節之前，請確保已安裝相依性。

除了此處描述的內容之外，VS Code 擴充功能 API 文件也是收集有關擴充功能如何與編輯器互動的更多資訊的好地方。

VS Code 擴充功能目前具有以下主要部分

Ruby 環境啟動的版本管理器整合
ruby/debug 用戶端實作
測試控制器實作
Copilot 聊天參與者
相依性樹狀結構實作
LSP 用戶端
工作區抽象，用於表示編輯器中的每個使用中工作區

測試變更

開啟 lsp.code-workspace 檔案，而不是僅開啟常規資料夾。它包含使用如下所述的「執行和除錯」所需的組態。

我們盡力確保盡可能徹底的測試。但是，有些測試難以編寫，尤其是那些與 VS Code 小工具互動的測試。

舉例來說，如果執行測試時顯示一個對話框，測試就沒有簡單的方法可以點擊對話框上的按鈕以繼續執行。對於這些情況，我們使用 sinon 來模擬預期的調用和回應。

注意：client.test.ts 是一個整合式測試，它會啟動開發版本的 ruby-lsp gem 並針對它執行請求。

執行測試

執行測試最簡單的方法是在「執行和偵錯」中選擇 Extension tests 工作，然後點擊執行。這將執行所有測試，結果將顯示在 VS Code 的偵錯主控台中。

或者，您也可以通過終端機執行測試，這將在儲存庫中下載測試用的 VS Code 版本，並針對它執行測試。您可以通過啟動工作來執行測試，以避免下載。

注意：無法執行單個測試檔案或範例。

即時偵錯

可以即時偵錯擴充功能的開發版本。詳細資訊可以在 VS Code 擴充功能文件中找到，但本節將包含簡短的描述。

即時偵錯涉及兩個 VS Code 視窗。第一個是您將修改程式碼的地方，第二個視窗將是擴充功能的開發版本運行的位置。您需要在第一個視窗中更改程式碼，重新載入並在第二個視窗中驗證更改。

首先，在「執行和偵錯」面板中使用 Run extension 工作啟動擴充功能偵錯。這將開啟第二個 VS Code 視窗，其中正在運行擴充功能的開發版本。
在第一個原始的 VS Code 視窗中進行所需的更改。
點擊偵錯工具列中的重新載入按鈕，將您最近的更改載入到第二個 VS Code 視窗中。
執行操作以在第二個視窗中驗證您的更改。

如果您希望執行逐步偵錯，您只需在您修改程式碼的第一個視窗中通過 UI 添加中斷點即可 - 而不是在運行擴充功能開發版本的第二個視窗中添加。

貢獻文件

Ruby LSP 使用 Jekyll 來產生文件，其原始碼位於 /jekyll 資料夾下。在進行任何變更之前，請確保您已執行初始設定。

之後，按照以下步驟進行並驗證您的變更。

進行所需的變更。
在開發環境中啟動 jekyll。
```
bundle exec jekyll serve
```
通過訪問 https://127.0.0.1:4000/ruby-lsp 在本地驗證您的更改。

貢獻 Ruby LSP Rails 附加元件

請參閱 https://github.com/Shopify/ruby-lsp-rails/blob/main/CONTRIBUTING.md