mirror of
https://github.com/microsoft/language-server-protocol.git
synced 2025-12-23 08:48:16 +00:00
Update contribution.md
This commit is contained in:
Dirk Bäumer
GitHub
parent
b7c1afdb0f
commit
d09fd2d3a1
1 changed files with 48 additions and 94 deletions
142
contributing.md
142
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<undefined> {
|
|||
}
|
||||
```
|
||||
|
||||
### File _server/workspaceFolders.proposed.ts_
|
||||
### File _server/common/workspaceFolders.proposed.ts_
|
||||
|
||||
```ts
|
||||
export interface WorkspaceFoldersProposed {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue