Contributing

Contributing

This is the short version. For the full contributing guide, see CONTRIBUTING.md.

Quick links

• Report a bug
• Suggest a change
• Code of Conduct

Getting started

1. Fork the repository.
2. Create a branch from main: git switch -c feat/my-feature
3. Make your changes.
4. Commit using Conventional Commits (enforced via cocogitto).
5. Push and open a Pull Request.

What can you contribute?

Colorschemes

Add a Lantern flame under the relevant plugin or user flame directory. The file must export glow() and ignite() functions. See Customization - Adding a colorscheme for the full template.

Font families

Add a Lantern font flame. See Customization - Adding a font preset.

Lantern wicks

Create a new wick with require("plugs.lantern").add_wick(...) and back it with inline flames, module flames, or flame_dirs. See Customization - Creating custom Lantern wicks.

Bug fixes and features

1. Check open issues for something to work on.
2. For new features, open an issue first to discuss the approach.
3. Follow the code style described below.

Code style

Lua conventions

• Indentation: 2 spaces.
• Naming: snake_case for variables and functions, PascalCase for class-like types (e.g., Config, Ribbon, Lantern.Wick).
• Type annotations: use LuaCATS @class, @param, @return, @field annotations for all public APIs. The documentation is auto-generated from these.
• Module pattern: modules typically create a local M = {} table, populate it, and return M.
• Lazy loading: prefer require inside functions for heavy dependencies, or use plugin-level cached discovery when a feature depends on filesystem scans.

Commit messages

This project uses Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types used in this project:

Type	Description	Appears in changelog
feat	New feature	Yes
fix	Bug fix	Yes
refactor	Code restructuring	Yes
perf	Performance improvement	Yes
style	Formatting, no logic change	Yes
docs	Documentation only	Yes
test	Adding or updating tests	Yes
ci	CI/CD changes	Yes
chore	Maintenance tasks	No
hotfix	Urgent fix	Yes
release	Release preparation	No

You can install cocogitto to validate your commits before pushing:

cog check

Project structure

See the Architecture page for a detailed module breakdown, config load order, and design patterns used throughout the project.