Merge pull request #1349 from mjlbach/contributing-overhaul

Contributing overhaul

6 files changed, 154 insertions, 71 deletions

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 7c0d9133..ce14ade8 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -18,7 +18,7 @@ jobs:
         sudo luarocks install luacheck
     - name: Run luacheck
       run: |
-        sudo make lint
+        luacheck lua/* test/*
   style-lint:
     runs-on: [ubuntu-latest]
     steps: 
diff --git a/ADVANCED_README.md b/ADVANCED_README.md
index dbb1b7e9..a4849b4b 100644
--- a/ADVANCED_README.md
+++ b/ADVANCED_README.md
@@ -14,7 +14,56 @@ part of the default configuration. The allowed arguments are detailed [below](#s
 require'lspconfig'.<server>.setup{<config>}
 ```
 
-### Example: using the defaults
+### The structure of `config`
+
+The `configs` module is a singleton where configs are defined. In `vim.validate`
+parlance here is the "spec":
+
+    configs.SERVER_NAME = {
+      default_config = {'t'};
+      on_new_config = {'f', true};
+      on_attach = {'f', true};
+      commands = {'t', true};
+      docs = {'t', true};
+    }
+    docs = {
+      description = {'s', true};
+      default_config = {'t', true};
+    }
+
+- Keys in `docs.default_config` match those of
+  `configs.SERVER_NAME.default_config`, and can be used to specify custom
+  documentation. This is useful for functions, whose docs cannot be easily
+  auto-generated.
+- `commands` is a map of `name:definition` key:value pairs, where `definition`
+  is a list whose first value is a function implementing the command and the
+  rest are either array values which will be formed into flags for the command
+  or special keys like `description`. Example:
+  ```
+  commands = {
+    TexlabBuild = {
+      function()
+        buf_build(0)
+      end;
+      "-range";
+      description = "Build the current buffer";
+    };
+  };
+  ```
+
+The `configs.__newindex` metamethod consumes the config definition and returns
+an object with a `setup()` method, to be invoked by users:
+
+    require'lspconfig'.SERVER_NAME.setup{}
+
+After you set `configs.SERVER_NAME` you can add arbitrary language-specific
+functions to it if necessary.
+
+Example:
+
+    configs.texlab.buf_build = buf_build
+
+### Example: using a default config
 
 To use the defaults, just call `setup()` with an empty `config` parameter.
 For the `gopls` config, that would be:
@@ -160,5 +209,7 @@ lspconfig.SERVER.setup{config}
     created as a result of {root_dir} returning a unique value. You can use this
     as an opportunity to further modify the new_config or use it before it is
     sent to |vim.lsp.start_client()|. If you set a custom `on_new_config`, ensure that 
-    `new_config.cmd = cmd` is present within the function body.
+    you read the original `on_new_config` defined in lspconfig, as many server configurations
+    leverage this to modify `cmd` at runtime, and this functionality should likely be duplicated
+    in your override.
 ```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 68f7042c..32c91f06 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,73 +1,88 @@
 ## Requirements
 
 - [Neovim](https://neovim.io/) 0.5 or later
+- Lint task requires [luacheck](https://github.com/luarocks/luacheck#installation) and [stylua](https://github.com/JohnnyMorganz/StyLua). If using nix, you can use `nix develop` to install these to a local nix shell.
 - Documentation is generated by `scripts/docgen.lua`.
-  - Only works on unix, you can ignore it on Windows.
-- Lint task requires [luacheck](https://github.com/luarocks/luacheck#installation) and [stylua](https://github.com/JohnnyMorganz/StyLua).
+  - Only works on linux and macOS
 
-## Lint
+## Scope of lspconfig
 
-PRs are checked with Luacheck and stylua. To run the linter locally:
+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.
 
-    make lint
-    stylua .
+## Adding a server to lspconfig
 
-## Generating docs
+The general form of adding a new language server is to start with a minimal skeleton. This includes populated the `config` table with a `default_config` and `docs` table.
 
-> Note: Github Actions automatically generates the docs, so only modify
-> `README_template.md` or the `docs` object on the server config.
-> Don't modify `README.md` directly.
+`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)
+* `filetypes`: a list for filetypes a 
+* `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.
 
-To preview the generated `README.md` locally, run `scripts/docgen.lua` from
-`nvim` (from the project root):
+Additionally, the following options are often added:
 
-    nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'
+* `init_options`: a table sent during initialization, corresponding to initializationOptions sent in [initializeParams](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#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/specification-3-17/#didChangeConfigurationParams) shortly after server initialization. This is an undocumented convention for most language servers. There is often some duplication with initOptions.
 
-## Configs
+A minimal example for adding a new language server is shown below for `pyright`, a python language server included in lspconfig:
 
-The `configs` module is a singleton where configs are defined. In `vim.validate`
-parlance here is the "spec":
+```lua
+-- Only `configs` must be required, util is optional if you are using the root resolver functions, which is usually the case.
+local configs = require 'lspconfig/configs'
+local util = require 'lspconfig/util'
 
-    configs.SERVER_NAME = {
-      default_config = {'t'};
-      on_new_config = {'f', true};
-      on_attach = {'f', true};
-      commands = {'t', true};
-      docs = {'t', true};
-    }
-    docs = {
-      description = {'s', true};
-      default_config = {'t', true};
-    }
+-- Having server name defined here is the convention, this is often times also the first entry in the `cmd` table.
+local server_name = 'pyright'
 
-- Keys in `docs.default_config` match those of
-  `configs.SERVER_NAME.default_config`, and can be used to specify custom
-  documentation. This is useful for functions, whose docs cannot be easily
-  auto-generated.
-- `commands` is a map of `name:definition` key:value pairs, where `definition`
-  is a list whose first value is a function implementing the command and the
-  rest are either array values which will be formed into flags for the command
-  or special keys like `description`. Example:
-  ```
-  commands = {
-    TexlabBuild = {
-      function()
-        buf_build(0)
-      end;
-      "-range";
-      description = "Build the current buffer";
-    };
-  };
-  ```
+configs[server_name] = {
+  default_config = {
+    -- This should be executable on the command line, arguments (such as `--stdio`) are additional entries in the list.
+    cmd = { 'pyright-langserver' },
+    -- These are the filetypes that the server will either attach or start in response to opening. The user must have a filetype plugin matching the filetype, either via the built-in runtime files or installed via plugin.
+    filetypes = { 'python' },
+    -- The root directory that lspconfig uses to determine if it should start a new language server, or attach the current buffer to a previously running language server.
+    root_dir = util.find_git_ancestor
+    end,
+  },
+  docs = {
+    -- extremely important: the package.json that contains language server settings, not the package.json that contains javascript dependencies for the project, or the package.json that contains vscode specific settings
+    package_json = 'https://raw.githubusercontent.com/microsoft/pyright/master/packages/vscode-pyright/package.json',
 
-The `configs.__newindex` metamethod consumes the config definition and returns
-an object with a `setup()` method, to be invoked by users:
+    -- The description should include at minimum the link to the github project, and ideally the steps to install the language server.
+    description = [[
+https://github.com/microsoft/pyright
 
-    require'lspconfig'.SERVER_NAME.setup{}
+`pyright`, a static type checker and language server for python
 
-After you set `configs.SERVER_NAME` you can add arbitrary language-specific
-functions to it if necessary.
+`pyright` can be installed via `npm`
+`npm install -g pyright`
+]],
+  },
+}
+```
 
-Example:
+## 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:
+
+```
+feat: add lua-language-server support
+fix(lua-language-server): update root directory pattern
+docs: update README.md
+```
+
+with the commit body containing additional details.
+
+## Lint
 
-    configs.texlab.buf_build = buf_build
+PRs are checked with Luacheck and stylua. Please run the linter locally before submitting a PR:
+
+    make lint
+
+## Generating docs
+
+Github Actions automatically generates the `CONFIG.md`. Only modify `scripts/README_template.md` or the `docs` table in the server config (the lua file). Do not modify `CONFIG.md` directly.
+
+To preview the generated `CONFIG.md` locally, run `scripts/docgen.lua` from
+`nvim` (from the project root):
+
+    nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'
diff --git a/Makefile b/Makefile
index 6f3c6db6..5b3f0b17 100644
--- a/Makefile
+++ b/Makefile
@@ -1,10 +1,10 @@
 test:
 	sh ./scripts/run_test.sh
 lint:
+	@echo "\nRunning luacheck\n"
 	luacheck lua/* test/*
-
-style-lint:
+	@echo "\nRunning stylua\n"
 	stylua --check .
 
-.PHONY: test lint style-lint
+.PHONY: test lint
 
diff --git a/flake.lock b/flake.lock
index dac8dc8e..bf440813 100644
--- a/flake.lock
+++ b/flake.lock
@@ -1,5 +1,20 @@
 {
   "nodes": {
+    "flake-utils": {
+      "locked": {
+        "lastModified": 1634851050,
+        "narHash": "sha256-N83GlSGPJJdcqhUxSCS/WwW5pksYf3VP1M13cDRTSVA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "c91f3de5adaf1de973b797ef7485e441a65b8935",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
         "lastModified": 1626644568,
@@ -16,6 +31,7 @@
     },
     "root": {
       "inputs": {
+        "flake-utils": "flake-utils",
         "nixpkgs": "nixpkgs"
       }
     }
diff --git a/flake.nix b/flake.nix
index 7661b81a..deaf48f7 100644
--- a/flake.nix
+++ b/flake.nix
@@ -1,17 +1,18 @@
 {
   description = "Quickstart configurations for the Nvim LSP client";
 
-  outputs = { self, nixpkgs }: let
-    pkgs = import nixpkgs { system = "x86_64-linux";};
-    in {
+  inputs.flake-utils.url = "github:numtide/flake-utils";
 
-    devShell."x86_64-linux" = pkgs.mkShell {
-
-      buildInputs = [
-        pkgs.stylua
-        pkgs.luaPackages.luacheck
-      ];
-    };
-
-  };
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let pkgs = nixpkgs.legacyPackages.${system}; in
+      rec {
+        devShell = pkgs.mkShell {
+          buildInputs = [
+            pkgs.stylua
+            pkgs.luaPackages.luacheck
+          ];
+        };
+      }
+    );
 }