CONTRIBUTING.md

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

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.
• 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.

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.

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