docs: CONTRIBUTING.md cleanup

1 files changed, 46 insertions, 37 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b83ee8a3..457b2626 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,57 +1,50 @@
 ## Requirements
 
-- [Link requirements](#Lint)
+- [Lint requirements](#lint)
 - Documentation is generated by `scripts/docgen.lua`.
   - Only works on linux and macOS
 
-## Scope of lspconfig
+## Scope of nvim-lspconfig
 
 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.
 
 ## Pull requests (PRs)
 
-- To avoid duplicate work, create a draft pull request.
+- Mark your pull request as "draft" until it's ready for review.
 - Avoid cosmetic changes to unrelated files in the same commit.
-- Use a [feature branch](https://www.atlassian.com/git/tutorials/comparing-workflows) instead of the master branch.
 - Use a **rebase workflow** for small PRs.
   - After addressing review comments, it's fine to rebase and force-push.
 
 ## Adding a server to lspconfig
 
-The general form of adding a new language server is to start with a minimal skeleton. This includes populating the `config` table with a `default_config` and `docs` table.
+To add a new language server, start with a minimal skeleton. See `:help lspconfig-new`.
 
-When choosing a server name, convert all 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`). 
+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`). 
 
-`default_config` should include, at minimum the following:
-* `cmd`: a list which includes the executable name as the first entry, with arguments constituting subsequent list elements (`--stdio` is common).
-Note that Windows has a limitation when it comes to directly invoking a server that's installed by `npm` or `gem`, so it requires additional handling.
+Populate the `config` table with a `default_config` and `docs` table.
 
-```lua
-cmd = { 'typescript-language-server', '--stdio' }
-```
+`default_config` should include at minimum:
 
-* `filetypes`: a list for filetypes the server should match with
-* `root_dir`: a function (or function handle) which returns the root of the project used to determine 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. Note, lspconfig does not offer a dedicated single file mode (this is not codified in the spec). Do not add `vim.fn.cwd` or `util.path.dirname` in `root_dir`. A future version of lspconfig will provide emulation of a single file mode until this is formally codified in the specification. A good fallback is `util.find_git_ancestor`, see other configurations for examples.
+* `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`.
 
-Additionally, the following options are often added:
+Additionally, these options are often useful:
 
-* `init_options`: a 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`: a 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.
+* `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`.
 
-An example for adding a new language server is shown below for `pyright`, a python language server included in lspconfig:
+An example for adding a new config is shown below:
 
 ```lua
 local util = require 'lspconfig.util'
 
-local root_files = {
-  'pyproject.toml',
-  'setup.py',
-  'setup.cfg',
-  'requirements.txt',
-  'Pipfile',
-  'pyrightconfig.json',
-}
-
 local function organize_imports()
   local params = {
     command = 'pyright.organizeimports',
@@ -64,7 +57,14 @@ return {
   default_config = {
     cmd = { 'pyright-langserver', '--stdio' },
     filetypes = { 'python' },
-    root_dir = util.root_pattern(unpack(root_files)),
+    root_dir = util.root_pattern(
+      'pyproject.toml',
+      'setup.py',
+      'setup.cfg',
+      'requirements.txt',
+      'Pipfile',
+      'pyrightconfig.json',
+    ),
     single_file_support = true,
     settings = {
       python = {
@@ -94,15 +94,22 @@ https://github.com/microsoft/pyright
 
 ## Commit style
 
-lspconfig, like neovim core, follows the [conventional commit style](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) please submit your commits accordingly. Generally commits will be of the form:
+Follow the Neovim core [commit message guidelines](https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md#commit-messages). Examples:
 
-```
-feat: add lua-language-server support
-fix(lua-language-server): update root directory pattern
-docs: update README.md
-```
+* 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".
 
-with the commit body containing additional details.
+  Solution:
+  Rearrange the root dir definition.
+  ```
 
 ## Lint
 
@@ -111,7 +118,7 @@ PRs are checked with the following software:
 - [stylua](https://github.com/JohnnyMorganz/StyLua).
 - [selene](https://github.com/Kampfkarren/selene)
 
-Please run the linter locally before submitting a PR:
+To run the linter locally:
 
     make lint
 
@@ -119,7 +126,9 @@ If using nix, you can use `nix develop` to install these to a local nix shell.
 
 ## Generating docs
 
-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.
+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):