diff --git a/contributing.md b/contributing.md index 8175c11..104ae21 100644 --- a/contributing.md +++ b/contributing.md @@ -4,7 +4,7 @@ Contributing to the language server protocol by proposing extensions to it requi - propose the extension via an issue in this [repository](https://github.com/Microsoft/language-server-protocol). Try to get early feedback before spending too much effort implementing it. - as the [protocol](https://github.com/Microsoft/vscode-languageserver-node/blob/master/protocol/src/protocol.ts) itself request and notification additions need to be defined using [TypeScript](https://www.typescriptlang.org/). -- a document describing the protocol extension must be written using [GitHub flavored Markdown](https://guides.github.com/features/mastering-markdown/). The document must follow the style of the [protocol](https://github.com/Microsoft/vscode-languageserver-node/blob/master/protocol/src/protocol.ts) document. +- a pull request against the next version of the specfication (currently [3.17](https://github.com/microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-17.md)) describing the protocol extension. The pull request must be written using [GitHub flavored Markdown](https://guides.github.com/features/mastering-markdown/) and must follow the overall syle of the document. - a reference implementation of the protocol for the [VSCode language client library](https://www.npmjs.com/package/vscode-languageclient) is desirable. It will simplify and speed up the review process. A reference implementation for the [VS Code language server library](https://www.npmjs.com/package/vscode-languageserver) is optional. The actual contribution can happen in two ways: @@ -21,11 +21,6 @@ Version 3.4.0 of VS Code's client and server library now have support to propose For a protocol extension the following files have to be created where ${name} is the name of the proposed extension: * **protocol/${name}.proposed.ts**: contains the TypeScript definitions of the protocol extension. -* **protocol/${name}.proposed.md** a markdown file containing the actual documentation of the proposed protocol. As said above the document must follow the style of the actual [protocol specification](https://github.com/Microsoft/vscode-languageserver-node/blob/master/protocol/src/protocol.ts). The markdown must document: - - * the extension to the initialize parameters sent to the server. - * the extensions to the client and server capabilities. - * the actual requests and notifications. * **client/${name}.proposed.ts**: this file contains the actual implementation of the proposed protocol for the `vscode-languageclient`. Since version 3.4.0 the client supports implementing protocol in so called features that can be registered with a client. A static feature is responsible for: * filling in the initialize properties (`fillInitializeParams` method) * filling in the client capabilities (`fillClientCapabilities` method) @@ -36,13 +31,13 @@ For a protocol extension the following files have to be created where ${name} is If you want to 'publish' the protocol extension as a pull request against the [repository](https://github.com/Microsoft/vscode-languageserver-node) the above files need to be added to the following directories: -* `protocol/${name}.proposed.ts` and `protocol/${name}.proposed.md` files go into the `protocol\src` folder, additionally prefixed with `protocol.` as follows: `protocol.${name}.proposed.{md,ts}`. -* the `client/${name}.proposed.ts` file goes into the `client/src` folder. -* the `server/${name}.proposed.ts` file goes into the `server/src` folder. +* `protocol/${name}.proposed.ts` file goes into the `protocol/src/common` folder, additionally prefixed with `protocol.` as follows: `protocol.${name}.proposed.ts`. +* the `client/${name}.proposed.ts` file goes into the `client/src/common` folder. +* the `server/${name}.proposed.ts` file goes into the `server/src/common` folder. -Please also ensure that you re-export the proposed API from the `client/src/main.ts` and the `server/src/main.ts`. Corresponding stubs can be found at the end of these files. +Please also ensure that you re-export the proposed API from the `server/src/common/api.ts`. Corresponding stubs can be found at the end of these files. -Users who want to make use of new proposed protocols needs to create the a client and register the proposed protocol with it in the following way: +Users who want to make use of new proposed protocols need to create a client and register the proposed protocol with it in the following way: ```ts let client = new LanguageClient('...', serverOptions, clientOptions); @@ -64,7 +59,7 @@ If you decide to publish the protocol extension in its own repository it must co This section contains an example of a protocol extension that adds workspace folder support. -### File _protocol/workspaceFolders.proposed.ts_ +### File _protocol/common/workspaceFolders.proposed.ts_ ```ts /* -------------------------------------------------------------------------------------------- @@ -155,107 +150,66 @@ export interface WorkspaceFoldersChangeEvent { } ``` -### File _protocol/workspaceFolders.proposed.md_ +### Content of the Pull Request against the specification ``` -#### Workspace Folders - -Many tools support more than one root folder per workspace. Examples for this are VS Code's multi-root support, Atom's project folder support or Sublime's project support. If a client workspace consists of multiple roots then a server typically needs to know about this. The protocol up to know assumes one root folder which is announce to the server by the `rootUri` property of the `InitializeParams`. For workspace folders the following additions are proposed: - -_Client Capabilities_: - -The client sets the following capability if it is supporting workspace folders. - -\`\`\`ts -/** - * The workspace client capabilities - */ -workspace: { - /** - * The client has support for workspace folders - */ - workspaceFolders?: boolean; -} -\`\`\` - -_InitializeParams_: - -An additional property `workspaceFolders` which contain the configured workspace folders when the server starts. - - -\`\`\`ts -/** - * The actual configured workspace folders. - */ -workspaceFolders: WorkspaceFolder[] | null; -\`\`\` - -where a `WorkspaceFolder` is defined as follows: - -\`\`\`ts -export interface WorkspaceFolder { - /** - * The associated URI for this workspace folder. - */ - uri: string; - - /** - * The name of the workspace folder. Defaults to the - * uri's basename. - */ - name: string; -} -\`\`\` - -##### Workspace Folders Request +Many tools support more than one root folder per workspace. Examples for this are VS Code's multi-root support, Atom's project folder support or Sublime's project support. If a client workspace consists of multiple roots then a server typically needs to know about this. The protocol up to now assumes one root folder which is announced to the server by the `rootUri` property of the `InitializeParams`. If the client supports workspace folders and announces them via the corresponding `workspaceFolders` client capability, the `InitializeParams` contain an additional property `workspaceFolders` with the configured workspace folders when the server starts. The `workspace/workspaceFolders` request is sent from the server to the client to fetch the current open list of workspace folders. Returns `null` in the response if only a single file is open in the tool. Returns an empty array if a workspace is open but no folders are configured. -_Request_: +_Client Capability_: +* property path (optional): `workspace.workspaceFolders` +* property type: `boolean` +_Server Capability_: +* property path (optional): `workspace.workspaceFolders` +* property type: `WorkspaceFoldersServerCapabilities` defined as follows: + +\`\`\`typescript +export interface WorkspaceFoldersServerCapabilities { + /** + * The server has support for workspace folders + */ + supported?: boolean; + + /** + * Whether the server wants to receive workspace folder + * change notifications. + * + * If a string is provided, the string is treated as an ID + * under which the notification is registered on the client + * side. The ID can be used to unregister for these events + * using the `client/unregisterCapability` request. + */ + changeNotifications?: string | boolean; +} +\`\`\` + +_Request_: * method: 'workspace/workspaceFolders' * params: none _Response_: +* result: `WorkspaceFolder[] | null` defined as follows: -* result: `WorkspaceFolder[] | null` -* error: code and message set in case an exception happens during the 'workspace/workspaceFolders' request - -##### DidChangeWorkspaceFolders Notification - -The `workspace/didChangeWorkspaceFolders` notification is sent from the client to the server to inform the client about workspace folder configuration changes. - -_Notification_: - -* method: 'workspace/didChangeWorkspaceFolders' -* params: `DidChangeWorkspaceFoldersParams` defined as follows: - -\`\`\`ts -export interface DidChangeWorkspaceFoldersParams { +\`\`\`typescript +export interface WorkspaceFolder { /** - * The actual workspace folder change event. + * The associated URI for this workspace folder. */ - event: WorkspaceFoldersChangeEvent; -} - -/** - * The workspace folder change event. - */ -export interface WorkspaceFoldersChangeEvent { - /** - * The array of added workspace folders - */ - added: WorkspaceFolder[]; + uri: DocumentUri; /** - * The array of the removed workspace folders + * The name of the workspace folder. Used to refer to this + * workspace folder in the user interface. */ - removed: WorkspaceFolder[]; + name: string; } \`\`\` +* error: code and message set in case an exception happens during the 'workspace/workspaceFolders' request ``` -### File _client/workspaceFolders.proposed.ts_ +### File _client/common/workspaceFolders.proposed.ts_ ```ts export interface WorkspaceFolderMiddleware { @@ -365,7 +319,7 @@ export class WorkspaceFoldersFeature implements DynamicFeature { } ``` -### File _server/workspaceFolders.proposed.ts_ +### File _server/common/workspaceFolders.proposed.ts_ ```ts export interface WorkspaceFoldersProposed {