Contributing

Thank you for considering contributing to Termy! This guide covers everything you need to get started.

Getting Started

Prerequisites

Development environment: Follow the Building from Source guide to set up Rust and dependencies.
Familiarity with:
- Rust programming language
- Terminal emulation concepts (VT100, ANSI escape codes)
- GPUI (Termy’s UI framework) - basic understanding helpful
Tools:
- Git for version control
- just task runner (optional but recommended)
- Code editor with Rust support (VS Code + rust-analyzer, RustRover, etc.)

Fork and Clone

Fork the Termy repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/termy.git
cd termy

Add upstream remote:

git remote add upstream https://github.com/lassejlv/termy.git

Development Setup

Build and Run

Verify your setup:

# Check all workspace crates
cargo check --workspace

# Run Termy in development mode
cargo run

# Run with logging
RUST_LOG=info cargo run

Enable Debug Features

Development builds include extra diagnostics:

# Render performance metrics (debug builds only)
RUST_LOG=info TERMY_RENDER_METRICS=1 cargo run

See Building from Source for more debug options.

Run Tests

# All workspace tests
cargo test --workspace

# Specific crate tests
cargo test -p termy_terminal_ui

# Integration tests (requires tmux >= 3.3)
just test-tmux-integration

Architecture Validation

Before submitting changes, run boundary checks:

./scripts/check-boundaries.sh

Or use just:

just check-boundaries

This ensures:

Dependency boundaries are respected (e.g., CLI crates don’t depend on GPUI)
Generated documentation is up-to-date

See Architecture for boundary rules.

Code Structure

Key Areas

Understand where to make changes:

Terminal Emulation & Rendering

Location: crates/terminal_ui/Covers:

Terminal process management (runtime.rs)
Grid rendering and caching (grid.rs)
PTY handling (Unix/Windows)
Tmux integration (tmux/)
Link detection (links.rs)

Testing: Unit tests + tmux integration tests

UI & User Experience

Location: src/Covers:

Terminal view component (terminal_view/)
Settings UI (settings_view/)
Menus and actions (menus.rs, commands.rs)
Window management (main.rs)
Input handling (text_input.rs)

Framework: GPUI components

Configuration System

Location: crates/config_core/, src/config/Covers:

Config data structures (config_core)
Config loading and parsing (src/config/)
Theme integration
Validation and defaults

Docs: Auto-generated via just generate-config-doc

Commands & Keybinds

Location: crates/command_core/, src/keybindings/Covers:

Command definitions (command_core)
Keybind resolution and parsing
Default keybind configuration
GPUI action integration (src/keybindings/)

Critical: Respect the command boundaryDocs: Auto-generated via just generate-keybindings-doc

Themes

Location: crates/theme_core/, crates/themes/Covers:

Theme data structures (theme_core)
Built-in themes (themes)
Theme validation

Adding themes: Add to crates/themes/src/

CLI Tool

Location: crates/cli/, crates/cli_install_core/Covers:

termy-cli binary commands
Config validation
Shell integration installation
TUI-based previews

Boundary: Must NOT depend on GPUI

Auto-Update System

Location: crates/auto_update/, crates/auto_update_ui/Covers:

Update checking (auto_update)
Download and installation
Update UI notifications (auto_update_ui)

Note: Uses termy_release_core for version metadata

See the Architecture guide for detailed crate descriptions.

Dependency Rules

Termy enforces strict dependency boundaries via CI: Forbidden dependencies (will fail CI):

termy_command_core → gpui
termy_command_core → termy_config_core
termy_config_core → termy_themes
termy_cli or termy_cli_install_core → gpui

Rationale: Keeps domain logic pure and enables CLI tools to work without GPUI. Check locally:

cargo tree -p termy_command_core | grep gpui  # Should be empty

Making Changes

Create a Branch

Branch from main with a descriptive name:

git checkout -b feature/add-split-pane-keybind
# or
git checkout -b fix/cursor-rendering-bug

Branch naming:

feature/ for new features
fix/ for bug fixes
refactor/ for refactoring
docs/ for documentation

Code Style

Termy follows standard Rust conventions:

# Format code
cargo fmt --all

# Lint with Clippy
cargo clippy --workspace --all-targets

Guidelines:

Use cargo fmt before committing
Address all cargo clippy warnings
Add comments for non-obvious logic
Write doc comments for public APIs
Follow existing patterns in the codebase

Testing Your Changes

Unit tests: Add tests in the same file or tests/ module
```
cargo test -p your_crate
```
Integration tests: For terminal features, consider tmux tests
```
just test-tmux-integration
```
Manual testing: Run Termy and verify behavior
```
cargo run --release
```

Render metrics: Check for performance regressions

RUST_LOG=info TERMY_RENDER_METRICS=1 cargo run

Update Generated Docs

If you modify commands or config:

# Regenerate documentation
just generate-keybindings-doc
just generate-config-doc

# Verify they're correct
just check-keybindings-doc
just check-config-doc

CI will fail if generated docs are stale.

Submitting a Pull Request

Before Submitting

Run the full validation suite:

# Format code
cargo fmt --all

# Lint
cargo clippy --workspace --all-targets -- -D warnings

# Test
cargo test --workspace

# Architecture checks
./scripts/check-boundaries.sh

Or use a single command:

just check && cargo test --workspace && ./scripts/check-boundaries.sh

Commit Messages

Write clear, descriptive commit messages: Good:

Add Cmd+D keybind for split-pane-right

Implements #123. Adds default keybind Cmd+D (macOS) and Ctrl+D (Windows/Linux)
for splitting the current pane vertically.

Less good:

fix bug

Tips:

Use imperative mood (“Add feature” not “Added feature”)
Reference issue numbers (“Fixes #123”)
Explain why if not obvious from what

Create the PR

Push your branch:

git push origin feature/your-branch-name

Open a pull request on GitHub
Fill out the PR template:
- Description: Explain what and why
- Screenshots/Videos: For UI changes (highly appreciated!)
- Related Issues: Link issues (“Closes #123”)
- Checklist: Confirm no overlapping PRs

PR Review Process

CI checks: Automated checks must pass:
- Rust formatting (cargo fmt)
- Architecture boundary validation
- Tmux integration tests (macOS)
Code review: Maintainers will review and may request changes

Iterate: Address feedback, push updates:

# Make changes
git add .
git commit -m "Address review feedback"
git push

Merge: Once approved, maintainers will merge your PR

Types of Contributions

Bug Fixes

Check existing issues for duplicates
Create an issue if one doesn’t exist (use bug report template)
Reference the issue in your PR (“Fixes #123”)
Include steps to reproduce + test that verify the fix

New Features

Discuss first: Open a feature request issue to discuss design
Wait for maintainer feedback before implementing (avoid wasted work)
Break large features into smaller PRs when possible
Update documentation as needed

Documentation

Documentation improvements are always welcome:

Fix typos or clarify existing docs
Add examples or tutorials
Document undocumented features
Improve API doc comments

Note: Don’t manually edit generated docs (docs/keybindings.md, etc.); instead, update the generator in crates/xtask/.

Themes

To contribute a new theme:

Add theme to crates/themes/src/
Follow existing theme structure

Test with:

cargo run -p termy_cli -- preview-theme your-theme-name

Include a screenshot in your PR

Tests

Improving test coverage helps everyone:

Add unit tests for edge cases
Add integration tests for complex features
Improve existing test clarity

Getting Help

Questions

Architecture questions: See Architecture guide
Build issues: See Building from Source
GitHub Discussions: For general questions
Issues: For bug reports or feature requests

Start with these files:

Entry point: src/main.rs
Terminal view: src/terminal_view/mod.rs
Terminal runtime: crates/terminal_ui/src/runtime.rs
Commands: crates/command_core/src/lib.rs
Config: crates/config_core/src/lib.rs

Use cargo doc --open to browse API documentation.

CI Failures

Common CI failures:

Formatting: Run cargo fmt --all
Boundary check: Run ./scripts/check-boundaries.sh locally
Stale docs: Run just generate-keybindings-doc && just generate-config-doc
Tmux tests: These only run on macOS CI; install tmux >= 3.3 to test locally

Code of Conduct

Be respectful and constructive:

Welcome newcomers and answer questions patiently
Provide constructive feedback in reviews
Respect maintainer decisions on scope and direction
Focus on technical merit, not personal preferences

Termy aims to be an inclusive and welcoming project.

Recognition

All contributors are valued! Contributions are recognized via:

GitHub contribution graph
Release notes for significant features
Community appreciation

Thank you for making Termy better!

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Next Steps

Architecture - Deep dive into codebase structure
Building from Source - Detailed build instructions
Configuration - Understand configuration system
GitHub Issues - Find issues to work on

Development

Contributing

Getting Started

Prerequisites

Fork and Clone

Development Setup

Build and Run

Enable Debug Features

Run Tests

Architecture Validation

Code Structure

Key Areas

Dependency Rules

Making Changes

Create a Branch

Code Style

Testing Your Changes

Update Generated Docs

Submitting a Pull Request

Before Submitting

Commit Messages

Create the PR

PR Review Process

Types of Contributions

Bug Fixes

New Features

Documentation

Themes

Tests

Getting Help

Questions

Codebase Navigation

CI Failures

Code of Conduct

Recognition

License

Next Steps

Build docs developers (and LLMs) love

Development

​Getting Started

​Prerequisites

​Fork and Clone

​Development Setup

​Build and Run

​Enable Debug Features

​Run Tests

​Architecture Validation

​Code Structure

​Key Areas

​Dependency Rules

​Making Changes

​Create a Branch

​Code Style

​Testing Your Changes

​Update Generated Docs

​Submitting a Pull Request

​Before Submitting

​Commit Messages

​Create the PR

​PR Review Process

​Types of Contributions

​Bug Fixes

​New Features

​Documentation

​Themes

​Tests

​Getting Help

​Questions

​Codebase Navigation

​CI Failures

​Code of Conduct

​Recognition

​License

​Next Steps

Build docs developers (and LLMs) love

Getting Started

Prerequisites

Fork and Clone

Development Setup

Build and Run

Enable Debug Features

Run Tests

Architecture Validation

Code Structure

Key Areas

Dependency Rules

Making Changes

Create a Branch

Code Style

Testing Your Changes

Update Generated Docs

Submitting a Pull Request

Before Submitting

Commit Messages

Create the PR

PR Review Process

Types of Contributions

Bug Fixes

New Features

Documentation

Themes

Tests

Getting Help

Questions

Codebase Navigation

CI Failures

Code of Conduct

Recognition

License

Next Steps