kitty/CONTRIBUTING.md

Reporting bugs

Please first search existing bug reports (especially closed ones) for a report that matches your issue.

When reporting a bug, provide full details of your environment, that means, at a minimum, kitty version, OS and OS version, kitty config (ideally a minimal config to reproduce the issue with).

Note that bugs and feature requests are often closed quickly as they are either fixed or deemed wontfix/invalid. In my experience, this is the only scalable way to manage a bug tracker. Feel free to continue to post to a closed bug report if you would like to discuss the issue further. Being closed does not mean you will not get any more responses.

Contributing code

Install the dependencies using your favorite package manager. Build and run kitty from source.

Make a fork, submit your Pull Request. If it's a large/controversial change, open an issue beforehand to discuss it, so that you don't waste your time making a pull request that gets rejected.

If the code you are submitting is reasonably easily testable, please contribute tests as well (see the kitty_tests/ sub-directory for existing tests, which can be run with ./test.py).

That's it.

Commands

• Build: ./dev.sh build or python3 setup.py build --debug
• Tests: ./test.py (or --module <name> for specific)
• Type check: ./test.py type-check (mypy)
• Linting: ruff check . for Python, gofmt/gofmt for Go
• Regenerate config types: ./gen-config.py after editing definition.py
• CI runs: GCC + Clang on Python 3.11/3.12/3.13 (ASAN enabled), ruff linting, mypy, go vet

Key files to know first when working on the project

• boss.py — central runtime controller
• screen.c — VT terminal emulation core
• kitty/options/definition.py — all config options in one place (~3700 lines)
• child-monitor.c — child process/PTY management