Contributing guide

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

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

Commit messages / PR title

Please ensure your pull request title conforms to Conventional Commits.

CI

Our CI checks are run using nix.

Development

Dev environment

We use the following tools:

Formatting

• .editorconfig (with editorconfig-checker)
• stylua [Lua]
• alejandra [Nix]

Linting

• luacheck

Static type checking

• lua-language-server

Nix devShell

• Requires flakes to be enabled.

We provide a flake.nix that can bootstrap all of the above development tools.

To enter a development shell:

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.

Running tests

We use busted for testing, but with Neovim as the Lua interpreter.

The easiest way to run tests is with Nix (see below).

If you do not use Nix, you can also run the test suite using luarocks test. For more information on how to set up Neovim as a Lua interpreter, see

• The neorocks tutorial.

Or

• nlua.

Running tests and checks with Nix

If you just want to run all checks that are available, run:

nix flake check -L --option sandbox false

To run tests locally, using Nix:

nix build .#checks.<your-system>.integration-nightly -L --option sandbox false

For example:

nix build .#checks.x86_64-linux.integration-nightly -L --option sandbox false

For formatting and linting:

nix build .#checks.<your-system>.pre-commit-check -L

For static type checking:

nix build .#checks.<your-system>.type-check-nightly -L

Manual testing

If you want to test your contributions to rocks.nvim manually, we recommend you set NVIM_APPNAME to something other than nvim, so that your test environment doesn't interfere with your regular Neovim installation.

We also provide a Nix flake output that you can use to test-drive rocks.nvim:

nix run .#neovim-with-rocks

It sets NVIM_APPNAME to nvimrocks.