Contributing guide

February 21, 2026 · View on GitHub

Contributions are more than welcome!

This document assumes that you already know how to use GitHub and Git. If that's not the case, we recommend learning about it first here.

Strict No LLM / No AI Policy

No LLMs for issues.

No LLMs for pull requests.

No LLMs for comments on issues/PRs, including translation. English is encouraged, but not required. You are welcome to post in your native language and rely on others to have their own translation tools of choice to interpret your words.

First-time contributors

I label issues that I think should be easy for first-time contributors with good-first-issue.

Commit messages

This project uses Conventional Commits.

Development

I use

nix for development and testing.
stylua, .editorconfig, and alejandra for formatting.
luacheck, and markdownlint, for linting.
sumneko-lua-language-server for static type checking.

Type safety

Lua is incredibly responsive, giving immediate feedback for configuration. But its dynamic typing makes Neovim plugins susceptible to unexpected bugs at the wrong time. To mitigate this, I rely on LuaCATS annotations, which are checked in CI.

Running tests

This plugin uses busted for testing.

The best way to run tests is with Nix (see below), because this includes tests that take different envrionments into account (e.g. with/without fast-tags, hoogle, ...).

If you do not use Nix, you can run a basic version of the test suite using luarocks test. For more information, see the neorocks tutorial.

Development using Nix

To enter a development shell:

nix-shell

or (with flakes enabled)

nix develop

To apply formatting, while in a devShell, run

pre-commit run --all

If you use direnv, just run direnv allow and you will be dropped in this devShell.

To run tests locally

nix-build -A haskell-tools-test

Or (with flakes enabled)

nix build .#checks.<your-system>.haskell-tools-test --print-build-logs

For formatting and linting:

nix-build -A pre-commit-check

Or (with flakes enabled)

nix build .#checks.<your-system>.formatting --print-build-logs

If you have flakes enabled and just want to run all checks that are available, run:

nix flake check --print-build-logs