From 41f21461e4e7710d821321ef05b3539c662c2ee4 Mon Sep 17 00:00:00 2001
From: Rintaro Ishizaki <rishizaki@apple.com>
Date: Tue, 28 Apr 2026 00:46:57 -0700
Subject: [PATCH] [ContributorDoc] Checklist for adding new LSP/BSP messages

---
 .../Adding LSP and BSP Messages.md            | 56 +++++++++++++++++++
 Contributor Documentation/README.md           |  1 +
 2 files changed, 57 insertions(+)
 create mode 100644 Contributor Documentation/Adding LSP and BSP Messages.md

diff --git a/Contributor Documentation/Adding LSP and BSP Messages.md b/Contributor Documentation/Adding LSP and BSP Messages.md
new file mode 100644
index 000000000..0504c0770
--- /dev/null
+++ b/Contributor Documentation/Adding LSP and BSP Messages.md	
@@ -0,0 +1,56 @@
+# Adding LSP and BSP Messages
+
+This document lists every file that must be updated when adding a new LSP or BSP request or notification.
+
+## LSP Message
+
+### In `swift-tools-protocols`
+
+- [ ] Add the Swift file under `Sources/LanguageServerProtocol/Requests/` *(request)* or `Sources/LanguageServerProtocol/Notifications/` *(notification)*
+- [ ] `Sources/LanguageServerProtocol/CMakeLists.txt`:
+  - [ ] Add the file in alphabetical order
+- [ ] `Sources/LanguageServerProtocol/Messages.swift`:
+  - [ ] Add to `builtinRequests` *(request)* or `builtinNotifications` *(notification)*
+
+### In `sourcekit-lsp`
+
+- [ ] `Sources/SourceKitLSP/MessageHandlingDependencyTracker.swift`:
+  - [ ] *(client → server, request)* Add a case to `init(_ request:)`
+  - [ ] *(client → server, notification)* Add a case to `init(_ notification:)`
+- [ ] `Sources/SourceKitLSP/SourceKitLSPServer.swift`:
+  - [ ] *(client → server, request)* Add a case to `handle(request:id:reply:)`
+  - [ ] *(client → server, notification)* Add a case to `handle(notification:)`
+  - [ ] Advertise via `serverCapabilities()`
+  - [ ] If handled by a language service: also advertise in each `LanguageService.initialize` conforming method
+  - [ ] If experimental *(server → client)*: check the client capability before sending
+- [ ] `Sources/SourceKitLSP/CapabilityRegistry.swift`:
+  - [ ] If gated on an experimental **client** capability, add a helper property
+- [ ] `Contributor Documentation/LSP Extensions.md`:
+  - [ ] Document if it is an LSP extension
+
+## BSP Message
+
+### In `swift-tools-protocols`
+
+- [ ] Add the Swift file under `Sources/BuildServerProtocol/Messages/`
+- [ ] `Sources/BuildServerProtocol/CMakeLists.txt`:
+  - [ ] Add the file in alphabetical order
+- [ ] `Sources/BuildServerProtocol/Messages.swift`:
+  - [ ] Add to `requestTypes` *(request)* or `notificationTypes` *(notification)*
+
+### In `sourcekit-lsp`
+
+- [ ] `Sources/BuildServerIntegration/BuildServerMessageDependencyTracker.swift`:
+  - [ ] *(build server → SourceKit-LSP, request)* Add a case to `init(_ request:)`
+  - [ ] *(build server → SourceKit-LSP, notification)* Add a case to `init(_ notification:)`
+- [ ] `Sources/BuildServerIntegration/BuiltInBuildServer.swift`:
+  - [ ] *(SourceKit-LSP → build server, request)* Add the request handler method to the `BuiltInBuildServer` protocol
+  - [ ] *(SourceKit-LSP → build server, notification)* Add the notification handler method to the `BuiltInBuildServer` protocol
+- [ ] `Sources/BuildServerIntegration/BuiltInBuildServerAdapter.swift`:
+  - [ ] *(SourceKit-LSP → build server, request)* Add a case to `handle(request:id:reply:)`
+  - [ ] *(SourceKit-LSP → build server, notification)* Add a case to `handle(notification:)`
+- [ ] `Sources/BuildServerIntegration/BuildServerManager.swift`:
+  - [ ] *(build server → SourceKit-LSP, request)* Add a case to `handle(request:id:reply:)`
+  - [ ] *(build server → SourceKit-LSP, notification)* Add a case to `handle(notification:)`
+- [ ] `Contributor Documentation/BSP Extensions.md`:
+  - [ ] Document if it is a BSP extension
diff --git a/Contributor Documentation/README.md b/Contributor Documentation/README.md
index 00f423b3d..de7a2a0b4 100644
--- a/Contributor Documentation/README.md	
+++ b/Contributor Documentation/README.md	
@@ -2,6 +2,7 @@
 
 The following documentation documents are primarily intended for developers of SourceKit-LSP.
 
+- [Adding LSP and BSP Messages](Adding%20LSP%20and%20BSP%20Messages.md)
 - [Background Indexing](Background%20Indexing.md)
 - [BSP Extension](BSP%20Extensions.md)
 - [Code Action](Code%20Action.md)