Contributing guide

March 30, 2026 · View on GitHub

Thank you for considering contributing to screenkey.nvim! We welcome all contributions, whether it's fixing bugs, adding new features, improving documentation, or adding examples of usage.

Table of contents

Getting started

If you want to contribute to screenkey.nvim, and you don't have a specific idea in mind, you can check the TODO list for some ideas.

PR's and commit messages

Please ensure your pull request title and commit messages conform to Conventional Commits. Make sure to use the appropriate type (e.g., feat, fix, docs, etc.) and provide a clear description of the changes.

Each PR should be focused on a single change (e.g. a bug fix, a new feature, a documentation update, etc.). If you have multiple unrelated changes, please consider opening separate PRs for each change.

CI

GitHub Actions will run the following checks on your PR:

  • busted tests
  • luacheck linting for lua files
  • stylua formatting - checks if the lua files are formatted correctly
  • markdownlint linting for markdown files
  • prettier formatting - checks if the markdown files are formatted correctly

If any CI check fails, review the logs, correct any issues in your code, and push the changes. If you're unsure, feel free to ask for assistance in the discussions or open an issue for guidance.

Development

We use the following tools:

Formatting

Linting

Static type checking

Running tests

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

You can run the test suite using luarocks test or busted. For more information on how to set up Neovim as a Lua interpreter, see nlua.

Manual testing

If you want to test your contributions to screenkey.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 or the plugins you use.

Documentation

If you want to contribute to the documentation, please follow these guidelines:

  • If your focus is not inline code comments, please only edit the README.md file — Neovim help docs will be automatically generated from it.
  • Keep your changes consistent with the existing documentation in terms of tone, style, and formatting.
  • Use fenced code blocks (```lua, ```vim, etc.) where appropriate to improve readability.
  • When documenting new features, include brief usage examples if possible.
  • Avoid typos and grammatical errors. Use a spell checker or LLM if needed.

Adding examples of usage

If you have an interesting use case for screenkey.nvim, or an unique configuration, please consider opening a issue with your example. Include screenshots or GIFs if possible, and

General tips when writing code

  • try to keep the code you add consistent with the existing code base
  • use ---@param, ---@return, ---@type, etc. annotations for functions/variables
  • keep functions small and focused on a single task
  • write comments for complex code
  • write tests for your code (if you don't know how, or if it's too complex, ask for help)

Thank you

We appreciate your time and effort in contributing to screenkey.nvim! Thank you!