CONTRIBUTING.md

Contributing

General

• Before committing, please go through the following steps:

  1. Lint Lua files with selene

  2. Format Lua files with StyLua

  3. If you've updated documentation, format Markdown files with Prettier

     All are available as null-ls built-ins. Failing to lint and format files will cause CI failures, which will prevent your PR from getting merged.

     Optionally, you can install Pre-Commit hooks by cloning the project and running make install-hooks to locally enforce checks on commit.

• Use the Conventional Commits style for your commits.

• Squash your commits so that one commit represents one complete change.

• Mark your PR as WIP until it's ready to merge.

• Make sure tests are passing by running make test in the root of the project. Smaller features / fixes should have unit test coverage, and larger features should have E2E coverage.

• We use Plenary's test suite, which uses a stripped-down version of busted. If you're unsure how to write tests for your PR, please let us know and we can help.

• To format Lua code blocks in our Markdown documentation, we recommend cbfmt, which is available as a null-ls built-in.

Contributing built-ins

• Check if there is an open issue requesting the built-in you are adding and mention in your PR that it closes any relevant issue(s).
• Check other built-in sources for examples and, whenever possible, use helpers to reduce the number of lines of code in your PR.
• A built-in source's arguments are the minimal arguments required for the source to work. Leave out non-essential arguments.
• Built-in sources should target the latest available version of the underlying program unless there is a compelling and widespread reason to use an older version. If older versions require different arguments, mention that in the documentation. If they require a different parser, create a separate built-in.
• Make sure your built-in source has a name.
• If the source doesn't use generator_factory to spawn an external command, define a can_run field to verify if the plugin is installed. Note that this is only necessary for clarification when :checkhealth is run. For example, the gitrebase source relies on git being installed:

local gitrebase = require("null-ls.helpers").make_builtin({
    name = "gitrebase",
    -- other fields...
    can_run = function()
        return require("null-ls.utils").is_executable("git")
    end,
})

• Add the necessary meta field to your built-in so that we can generate extra documentation (basic information comes from the built-in's definition). Metadata should have the following structure:

local my_builtin = require("null-ls.helpers").make_builtin({
    -- place after built-in definition
    meta = {
        url = "https://github.com/my-builtin-repo",
        description = "Description of my built-in and what it does",
        notes = {
            "If present, we'll convert this table into a Markdown list",
        },
    },
})

Sources

Diagnostics

• Include all the information provided by the source. These are the available fields:

-- make sure ranges are 1-indexed (and offset if not)
local diagnostic = {
    message, -- string
    severity, -- 1 (error), 2 (warning), 3 (information), 4 (hint)
    row, -- number, optional (defaults to first line)
    col, -- number, optional (defaults to beginning of line)
    end_row, -- number, optional (defaults to row)
    end_col, -- number, optional (defaults to end of line),
    source, -- string, optional (defaults to "null-ls")
    code, -- number, optional
    filename, -- string, optional
    bufnr, -- number, optional
}

• Try to make sure col and end_col match the precise range of the diagnostic. If you're using our diagnostic helpers, you can use the offset override to adjust the range.

  An easy way to check the range is to use a theme like tokyonight or sonokai that underlines LSP diagnostics.

• Do not include the source's name or code in the message.

• If at all possible, please add one or more tests to check whether your source produces the correct output given an actual raw diagnostic. See the existing tests for examples.

• If your source can produce project-level diagnostics (i.e. diagnostics for more than one file at a time), use the multiple_files option described in HELPERS.

  • Specify that your source supports project diagnostics in its documentation.

  • Make sure each multi-file diagnostic includes either a filename or a bufnr so null-ls can then publish diagnostics properly. If specified, filename should be an absolute path.

  • To prevent performance issues, multi-file sources should default to the ON_SAVE method.

Configuration

In contrast to plugins like ALE, which allow source-specific configuration via buffer-local or global variables, null-ls configuration uses the with method to configure specific sources, described in further detail in BUILTIN_CONFIG.

You can access user configuration by using the params:get_config() method, described in MAIN. You'll then want to document available configuration options using the meta.config table. Each entry in the table should define the following:

• key: the name of the config option
• type: the Lua type of the config option
• description: a description of the option and what it does
• usage (optional): a code snippet showing example usage (useful for callbacks)

See the gitsigns.nvim built-in for examples of accessing and documenting configuration options.