Contributing to ChukTerm

February 18, 2026 · View on GitHub

Thank you for your interest in contributing to ChukTerm! This document provides guidelines and instructions for contributing.

Code of Conduct
Getting Started
Development Setup
Making Changes
Testing
Code Quality
Submitting Changes
Release Process

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please be respectful and constructive in all interactions.

Getting Started

Prerequisites

Python 3.10 or higher
uv (recommended) or pip
Git

Finding Something to Work On

Check the Issues page for open issues
Look for issues labeled good first issue for beginner-friendly tasks
Look for issues labeled help wanted for tasks needing assistance
Feel free to propose new features or improvements by opening an issue first

Development Setup

Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/chuk-term.git
cd chuk-term

Install Dependencies

# Using uv (recommended)
uv sync --dev

# Or using pip
pip install -e ".[dev]"

Install Pre-commit Hooks

# Install pre-commit hooks for automatic code quality checks
uv run pre-commit install

# Optionally, run hooks on all files to verify setup
uv run pre-commit run --all-files

Verify Setup

# Run tests to ensure everything is working
make test

# Run all quality checks
make check

Making Changes

Branch Naming

Use descriptive branch names:

feature/add-progress-bars - For new features
fix/theme-switching-bug - For bug fixes
docs/update-api-reference - For documentation
refactor/output-system - For refactoring

Coding Standards

Follow PEP 8 with these specifics:
- Line length: 120 characters
- Use Black for formatting (will be auto-applied by pre-commit)
- Use type hints for all functions

Type Hints

def example_function(name: str, count: int = 0) -> str:
    """Example function with proper type hints."""
    return f"{name}: {count}"

Docstrings

Use Google-style docstrings
Document all public functions, classes, and modules

def format_output(text: str, color: str = "default") -> str:
    """Format text for terminal output.

    Args:
        text: The text to format
        color: Color name for the text (default: "default")

    Returns:
        Formatted text string

    Example:
        >>> format_output("Hello", "green")
        "\\033[32mHello\\033[0m"
    """
    pass

Import Organization
- Standard library imports first
- Third-party imports second
- Local imports last
- Alphabetically sorted within each group (handled by isort)

Theme Compatibility

IMPORTANT: All code must work with all 8 themes.

Never check theme.name in application code
Let the theme system handle formatting differences
Test your changes with all themes

# GOOD - Theme agnostic
output.info("Processing...")

# BAD - Theme-specific logic
if get_theme().name == "minimal":
    print("plain text")

Writing Tests

Test Coverage: Maintain 90%+ coverage
- All new features must include tests
- Bug fixes should include regression tests

Test Organization

tests/
�� ui/
   �� test_output.py
   �� test_prompts.py
   �� test_terminal.py
�� test_cli.py

Test Naming

def test_output_info_displays_message():
    """Test that output.info() displays the message."""
    pass

def test_theme_switching_preserves_state():
    """Test that switching themes preserves output state."""
    pass

Mock External Dependencies

from unittest.mock import patch, MagicMock

def test_terminal_width(monkeypatch):
    """Test terminal width detection."""
    monkeypatch.setattr('shutil.get_terminal_size', lambda: (80, 24))
    # Test code here

Testing

Running Tests

# Run all tests
make test

# Run with coverage report
make test-cov

# Run specific test file
uv run pytest tests/ui/test_output.py -v

# Run specific test
uv run pytest tests/ui/test_output.py::test_output_info -v

# Run with verbose output
uv run pytest -vv

Test Requirements

Tests must pass on Python 3.10, 3.11, and 3.12
Tests must work in both TTY and non-TTY environments
Tests should be fast (< 1 second per test typically)
Tests should be deterministic (no random failures)

Code Quality

All code must pass these quality checks before being merged:

1. Linting (Ruff)

# Check for issues
uv run ruff check src/ tests/

# Auto-fix issues
uv run ruff check --fix src/ tests/

2. Formatting (Black)

# Check formatting
uv run black --check src/ tests/

# Auto-format
uv run black src/ tests/

3. Type Checking (Mypy)

# Run type checking
uv run mypy src/

4. Run All Checks

# Single command to run everything
make check

Pre-commit Hooks

Pre-commit hooks will automatically run these checks when you commit. If they fail:

Review the errors
Fix them manually or let auto-fix handle them
Stage the changes: git add .
Commit again: git commit

Submitting Changes

Pull Request Process

Update Documentation
- Update relevant documentation in docs/
- Update docstrings
- Add examples if needed
Update CHANGELOG
- Add your changes to CHANGELOG.md under [Unreleased]
- Follow the existing format
- Categories: Added, Changed, Deprecated, Removed, Fixed, Security
Create Pull Request
- Write a clear PR title: "Add progress bar support" or "Fix theme switching bug"
- Fill out the PR template (if available)
- Reference related issues: "Fixes #123" or "Relates to #456"
- Include before/after examples for UI changes

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] New tests added
- [ ] Manual testing performed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] No breaking changes (or documented if necessary)

Review Process

Maintainers will review your PR
Address feedback constructively
Make requested changes in new commits (don't force-push)
Once approved, a maintainer will merge your PR

Release Process

(For maintainers)

Update version in pyproject.toml
Update CHANGELOG.md (move [Unreleased] to new version)
Create git tag: git tag v0.2.0
Push tag: git push origin v0.2.0
Build and publish: make publish

Development Tips

Useful Commands

# Run interactive demo
make demo

# Run specific example
uv run python examples/ui_demo.py

# Clean build artifacts
make clean

# Deep clean (including coverage reports)
make clean-all

# Show project info
make info

# Install pre-commit hooks
uv run pre-commit install

Working with Themes

# Test with different themes
from chuk_term.ui import set_theme, output

for theme in ["default", "minimal", "dark", "monokai"]:
    set_theme(theme)
    output.info(f"Testing with {theme} theme")

Debugging

# Enable verbose output
from chuk_term.ui.output import get_output
get_output().set_output_mode(verbose=True)

# Check terminal capabilities
from chuk_term.ui.terminal import get_terminal_info
print(get_terminal_info())

# Check current theme
from chuk_term.ui.theme import get_theme
print(get_theme().name)

Common Issues

Import Errors

Ensure you're running from project root
Use uv run to execute scripts
Check Python path includes src/

Tests Failing

Run make clean and try again
Check if you're using the right Python version
Ensure all dependencies are installed: uv sync --dev

Pre-commit Hooks Failing

Read the error messages carefully
Most issues are auto-fixable: uv run ruff check --fix src/ tests/
Format code: uv run black src/ tests/

Questions?

Open an issue for questions
Check existing issues and PRs
Review the documentation in docs/

License

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

Thank you for contributing to ChukTerm! <�