Prefixing `sourcekit/` to LSP/BSP Extension Methods

Development SourceKit-LSP
1

Prefixing sourcekit/ to LSP/BSP Extension Methods

We are planning a naming change for SourceKit-LSP-specific LSP/BSP extensions.
All extension method names will be prefixed with sourcekit/ (e.g. textDocument/tests → sourcekit/textDocument/tests).

Motivation

This change is intended to avoid potential conflicts with future LSP/BSP standard methods. As the protocols evolve, unprefixed extension names may collide with standardized ones, so introducing a prefix provides a clear namespace for SourceKit-specific functionality.

Relevant PRs

Impact on swift-tools-protocols API

This change only affects the method names on the wire. The Swift type names in swift-tools-protocols will not change. So most library users should be able to adopt this change without any source changes, aside from updating to a version that includes the new method names.

Migration Plan

SourceKit-LSP

  • Accept incoming requests/notifications using both old and new names
  • Send outgoing messages using the new names, falling back to the old names if the new ones result in methodNotFound
  • Accept experimental LSP client capabilities under both naming schemes
  • Advertise experimental LSP server capabilities under both naming schemes
  • Start advertising experimental BSP client capabilities for incoming messages under both naming schemes

Editors (e.g. VS Code extensions)

  • Should advertise client capabilities using both naming schemes
  • Should determine which method names to use based on the server’s advertised capabilities
  • Should accept incoming requests/notifications using both naming schemes

Build Servers (e.g. SwiftPM)

  • swift-tools-protocols users
    • Should adopt the updated swift-tools-protocols as soon as possible
    • Until then (given the limited benefit of dual support on this path):
      • Should accept client-to-server messages using the old names
      • Should send server-to-client messages using the old names
  • Others
    • Should advertise server capabilities using both naming schemes
    • Should determine which method names to use based on the sourcekit-lsp advertised capabilities
    • Should accept incoming requests/notifications using both naming schemes

Deprecation Plan

  • Old (unprefixed) method names will be considered deprecated immediately after this change
  • Support for old names in sourcekit-lsp will be removed one year after the Swift 6.4 release

Affected Methods (for reference)

For completeness, the following extension methods are affected by this change.

LSP (peer: editor)

Incoming (Editor → SourceKit-LSP) Requests

  • textDocument/doccDocumentation → sourcekit/textDocument/doccDocumentation
  • textDocument/tests → sourcekit/textDocument/tests
  • workspace/getReferenceDocument → sourcekit/workspace/getReferenceDocument
  • sourceKit/_isIndexing → sourcekit/isIndexing
  • workspace/_outputPaths → sourcekit/workspace/outputPaths
  • workspace/_setOptions → sourcekit/workspace/setOptions
  • workspace/_sourceKitOptions → sourcekit/workspace/sourceKitOptions
  • workspace/synchronize → sourcekit/workspace/synchronize
  • workspace/triggerReindex → sourcekit/workspace/triggerReindex
  • workspace/playgrounds → sourcekit/workspace/playgrounds
  • workspace/tests → sourcekit/workspace/tests

Incoming (Editor → SourceKit-LSP) Notifications

  • window/didChangeActiveDocument → sourcekit/window/didChangeActiveDocument

Outgoing (SourceKit-LSP → Editor) Requests

  • workspace/peekDocuments → sourcekit/workspace/peekDocuments
  • workspace/playgrounds/refresh → sourcekit/workspace/playgrounds/refresh
  • workspace/tests/refresh → sourcekit/workspace/tests/refresh
BSP (peer: build server)

Incoming (Build Server → SourceKit-LSP) Notifications

  • build/sourceKitOptionsChanged → sourcekit/build/sourceKitOptionsChanged

Outgoing (SourceKit-LSP → Build Server) Requests

  • buildTarget/prepare → sourcekit/buildTarget/prepare
  • textDocument/sourceKitOptions → sourcekit/textDocument/sourceKitOptions
  • workspace/waitForBuildSystemUpdates → sourcekit/workspace/waitForBuildSystemUpdates

Feedback Requested

  • Does this migration plan seem reasonable for editors and build servers?
  • Is the timeline sufficient for downstream adoption?
  • Any concerns around capability negotiation or fallback behavior?
2 Likes
2

We have merged the pull requests for this to main branches, but we are not planning to cherry-pick them to release/6.4.x.

So here is the new deprecation plan:

  • Old (unprefixed) method names will be considered deprecated in Swift 6.5
  • Support for old names in sourcekit-lsp will be removed one year after the Swift 6.5 release