RFC: Introduce versionned ocamllsp capabilities

[xvw]

The OCaml LSP Server prefixes all custom requests with ocamllsp/capabilityName. However, there is a need to modify the input/output of certain custom requests over time. (#1330, #1450).

Tracking changes to custom requests in the OCaml LSP Server is challenging because modifying the input/output of these requests can introduce breaking changes for clients like VSCode and ocaml-eglot. Any structural changes to their parameters or responses may lead to incompatibilities, requiring client-side updates to maintain proper functionality. This makes it difficult to ensure smooth transitions, as both the server and clients must stay in sync, increasing the risk of unexpected failures or degraded user experiences.

I suggest introducing versioned capabilites to desynchronize the release of ocaml-lsp-server and clients:
For example:

• ocamllsp/capabilityX is equivalent to ocamllsp/capabilityX/v1 (for compatibility issues)
• if capabilityX change in the future (like in ocamllsp/switchImplIntf results in "Jsonrpc: json conversion failed: missing field error" #1330 or Search (by types and polarity) does not include location properly #1450) we can just adding ocamllsp/capabilityX/v2.

Materially, this means having a structure that's a bit more cut-up:

**my_capability.mli

val capabilities : string list 

module V1 : sig 
   ....
end

module V2 : sig 
   ....
end

(* etc. *)

From my point of view, this will make the evolution of custom requests (which are at the heart of the OCaml development experience) much simpler, and allow customers to anticipate releases by supporting multiple behaviors.

[mattiasdrp]

I like this idea. I think we need to move towards being able to update custom requests and this is a good middle ground because clients don't have to be updated immediately but the OCaml lsp can be changed without worrying about breaking its API. Do you want me to upgrade my PR to show an example of what you're proposing?

[xvw]

I like this idea. I think we need to move towards being able to update custom requests and this is a good middle ground because clients don't have to be updated immediately but the OCaml lsp can be changed without worrying about breaking its API. Do you want me to upgrade my PR to show an example of what you're proposing?

Thanks!
I think this requires some prior reflection and potentially a mutualization of signatures. So, at first, I think we should just focus on fixing the parameter deserialization function to validate uri | {DocumentUri}. What do you think?

[mattiasdrp]

Sounds like a good plan!