Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
160 lines (114 loc) · 4.6 KB

CONTRIBUTING.md

File metadata and controls

160 lines (114 loc) · 4.6 KB

Contributing

First off, thanks for taking the time to contribute! ❤️

All contribution types are welcome: bug reports, feature ideas, docs updates, tests, and code improvements. 🎉

Table of Contents

I Have a Question

Before asking a question:

If you still need help, use GitHub Discussions or open a new question issue with your relevant context.

I Want To Contribute

Contributions of all sizes are welcome. Keep changes focused and small. By contributing, you agree your contributions are provided under this repository's LICENSE.

Before opening a PR:

  • For larger changes, start with an issue or discussion first.
  • Prefer one clear purpose per PR.
  • Include related spec/ and docs/ updates when behavior changes.

Reporting Bugs

Before submitting a bug report, read the documentation, check discussions and existing issues, and search the internet for similar reports or fixes to avoid duplicates and continue existing threads.

When reporting a bug, include:

  • Steps to reproduce.
  • Expected result and actual result.
  • Lua version and platform details.
  • Minimal example when possible.

Suggesting Enhancements

For enhancements, read the documentation, check discussions and existing issues to avoid duplicate requests, then open an issue and include:

  • The problem you want to solve.
  • The proposed behavior.
  • Why it helps most users.
  • Any alternatives you considered.

Your First Code Contribution

Testing

Tests live in spec/. Add or update specs there when behavior changes.

Run tests with Busted:

# All tests
busted

# One spec file while iterating
busted spec/<module>_spec.lua

Linting

Run lint checks before opening a PR:

  • Run Lua lint with LuaCheck:

    luacheck .

  • Run Markdown lint for docs with markdownlint-cli2:

    # Global install
markdownlint-cli2 'docs/**/*.md' '!docs/.vitepress/**'

# Without global install
npx --yes markdownlint-cli2 'docs/**/*.md' '!docs/.vitepress/**'

Formatting

Run formatters before opening a PR:

  • Format .md, .json, .yml, .ts, and .mts files with Prettier:

    # Global install
prettier --write .

# Without global install
npx --yes prettier --write .

  • Format .lua files with StyLua:

    stylua .

Module Additions

If adding a module under src/mods/, also update: src/mods/init.lua, types/mods.lua, README.md, docs/modules/index.md, and mods-0.1.0-1.rockspec.

Improving The Documentation

  • Docs are built with VitePress and live in docs/.
  • The module reference pages under docs/src/modules/ are generated. Do not edit those .md files directly.
  • For API documentation changes, update the source annotations in types/ instead of editing generated module pages directly.
  • Module reference pages under docs/src/modules/ are generated automatically from those annotations.
  • For docs setup, build, preview, and local development commands, see docs/README.md.

Styleguides

Commit Messages

This project follows Conventional Commits 1.0.0.