nvim-lspconfig/CONTRIBUTING.md

137 lines
4.9 KiB
Markdown
Raw Normal View History

2020-09-05 23:22:27 +00:00
## Requirements
2024-10-01 11:55:44 +00:00
- [Lint requirements](#lint)
2020-09-05 23:22:27 +00:00
- Documentation is generated by `scripts/docgen.lua`.
2021-10-30 20:33:00 +00:00
- Only works on linux and macOS
2024-10-01 11:55:44 +00:00
## Scope of nvim-lspconfig
2021-10-30 20:33:00 +00:00
The point of lspconfig is to provide the minimal configuration necessary for a server to act in compliance with the language server protocol. In general, if a server requires custom client-side commands or off-spec handlers, then the server configuration should be added *without* those in lspconfig and receive a dedicated plugin such as nvim-jdtls, nvim-metals, etc.
2021-10-30 20:33:00 +00:00
2021-12-26 21:22:34 +00:00
## Pull requests (PRs)
2024-10-01 11:55:44 +00:00
- Mark your pull request as "draft" until it's ready for review.
2021-12-26 21:22:34 +00:00
- Avoid cosmetic changes to unrelated files in the same commit.
- Use a **rebase workflow** for small PRs.
- After addressing review comments, it's fine to rebase and force-push.
2021-10-30 20:33:00 +00:00
## Adding a server to lspconfig
2024-10-01 11:55:44 +00:00
To add a new language server, start with a minimal skeleton. See `:help lspconfig-new`.
2021-10-30 20:33:00 +00:00
2024-10-01 11:55:44 +00:00
When choosing a config name, convert dashes (`-`) to underscores (`_`). If the name of the server is a unique name (`pyright`, `clangd`) or a commonly used abbreviation (`zls`), prefer this as the server name. If the server instead follows the pattern x-language-server, prefer the convention `x_ls` (`jsonnet_ls`).
2024-10-01 11:55:44 +00:00
Populate the `config` table with a `default_config` and `docs` table.
2024-10-01 11:55:44 +00:00
`default_config` should include at minimum:
2024-10-01 11:55:44 +00:00
* `cmd`: a list which includes the executable name as the first entry, with arguments constituting subsequent list elements (`--stdio` is common).
```lua
cmd = { 'typescript-language-server', '--stdio' }
```
* `filetypes`: list of filetypes that should activate this config.
* `root_dir`: function which returns the root of the project, used to decide if lspconfig should launch a new language server, or attach a previously launched server when you open a new buffer matching the filetype of the server.
* See `:help lspconfig-new`.
* See `vim.fs.root()`
* Do not use `vim.fn.cwd` or `util.path.dirname`.
2021-10-30 20:33:00 +00:00
2024-10-01 11:55:44 +00:00
Additionally, these options are often useful:
2021-10-30 20:33:00 +00:00
2024-10-01 11:55:44 +00:00
* `init_options`: table sent during initialization, corresponding to `initializationOptions` sent in [initializeParams](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initializeParams) as part of the first request sent from client to server during startup.
* `settings`: table sent during [`workspace/didChangeConfiguration`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#didChangeConfigurationParams) shortly after server initialization. This is an undocumented convention for most language servers. There is often some duplication with `initOptions`.
2021-10-30 20:33:00 +00:00
2024-10-01 11:55:44 +00:00
An example for adding a new config is shown below:
2021-10-30 20:33:00 +00:00
```lua
2021-11-25 17:40:39 +00:00
local util = require 'lspconfig.util'
2021-10-30 20:33:00 +00:00
local function organize_imports()
local params = {
command = 'pyright.organizeimports',
arguments = { vim.uri_from_bufnr(0) },
}
vim.lsp.buf.execute_command(params)
end
return {
2021-10-30 20:33:00 +00:00
default_config = {
cmd = { 'pyright-langserver', '--stdio' },
2021-10-30 20:33:00 +00:00
filetypes = { 'python' },
2024-10-01 11:55:44 +00:00
root_dir = util.root_pattern(
'pyproject.toml',
'setup.py',
'setup.cfg',
'requirements.txt',
'Pipfile',
'pyrightconfig.json',
),
single_file_support = true,
settings = {
python = {
analysis = {
autoSearchPaths = true,
useLibraryCodeForTypes = true,
diagnosticMode = 'workspace',
},
},
},
},
commands = {
PyrightOrganizeImports = {
organize_imports,
description = 'Organize Imports',
},
2021-10-30 20:33:00 +00:00
},
docs = {
description = [[
https://github.com/microsoft/pyright
`pyright`, a static type checker and language server for python
]],
},
}
```
## Commit style
2024-10-01 11:55:44 +00:00
Follow the Neovim core [commit message guidelines](https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md#commit-messages). Examples:
2021-10-30 20:33:00 +00:00
2024-10-01 11:55:44 +00:00
* Adding a new config for "lua-language-server":
```
feat: lua-language-server
```
* Fixing a bug for "lua-language-server":
```
fix(lua-language-server): update root directory pattern
Problem:
Root directory incorrectly prefers "foo".
2021-10-30 20:33:00 +00:00
2024-10-01 11:55:44 +00:00
Solution:
Rearrange the root dir definition.
```
2020-09-05 23:22:27 +00:00
## Lint
PRs are checked with the following software:
- [luacheck](https://github.com/luarocks/luacheck#installation)
- [stylua](https://github.com/JohnnyMorganz/StyLua).
- [selene](https://github.com/Kampfkarren/selene)
2024-10-01 11:55:44 +00:00
To run the linter locally:
2020-09-05 23:22:27 +00:00
make lint
If using nix, you can use `nix develop` to install these to a local nix shell.
2020-09-05 23:22:27 +00:00
## Generating docs
2024-10-01 11:55:44 +00:00
GitHub Actions automatically generates `server_configurations.md`. Only modify
`scripts/README_template.md` or the `docs` table in the server config Lua file.
Do not modify `server_configurations.md` directly.
To preview the generated `server_configurations.md` locally, run `scripts/docgen.lua` from
`nvim` (from the project root):
nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'