Contributing to Null Terminal¶

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

Code of Conduct¶

Be respectful, inclusive, and constructive. We're building something cool together.

Getting Started¶

Prerequisites¶

Python 3.12+
uv package manager
Git

Development Setup¶

# Clone the repository
git clone https://github.com/starhound/null-terminal.git
cd null-terminal

# Install dependencies
uv sync

# Run the application
uv run main.py

# Run tests
uv run pytest

How to Contribute¶

Reporting Bugs¶

Check existing issues to avoid duplicates
Use the bug report template
Include:
Null Terminal version
Python version
OS and terminal emulator
Steps to reproduce
Expected vs actual behavior
Relevant logs or screenshots

Suggesting Features¶

Check existing issues/discussions
Describe the use case clearly
Explain why existing features don't solve it
Propose implementation if possible

Submitting Code¶

1. Fork and Branch¶

# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/null-terminal.git
cd null-terminal
git checkout -b feature/your-feature-name

Branch naming conventions: - feature/ - New features - fix/ - Bug fixes - docs/ - Documentation changes - refactor/ - Code refactoring - test/ - Test additions/fixes

2. Make Your Changes¶

Follow the coding standards below. Commit often with clear messages.

3. Test Your Changes¶

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=. --cov-report=term-missing

# Run specific tests
uv run pytest tests/unit/ai/

# Lint your code
uv run ruff check .
uv run ruff format --check .

4. Submit a Pull Request¶

Push your branch to your fork
Open a PR against main
Fill out the PR template
Link related issues
Wait for review

Coding Standards¶

Python Style¶

Formatter: We use ruff format
Linter: We use ruff check
Type hints: Required for all public functions
Docstrings: Required for classes and public methods

async def my_function(param: str, count: int = 10) -> list[str]:
    """Brief description of what this does.

    Args:
        param: Description of param
        count: Description of count

    Returns:
        Description of return value
    """
    pass

Async Conventions¶

All I/O operations must be async
Use asyncio.create_subprocess_shell instead of subprocess
Use httpx.AsyncClient instead of requests
Never use time.sleep() - use asyncio.sleep()

TUI Conventions¶

Never use print() - use self.notify() or self.log()
Use TCSS classes for styling, not inline styles
Use self.post_message() for widget communication
Keep widget compose() methods simple

Testing Requirements¶

All new features need tests
All bug fixes need regression tests
Use the mock_home fixture to protect user data
Integration tests use the pilot pattern

import pytest

@pytest.mark.asyncio
async def test_feature(mock_home, mock_storage):
    """Test description."""
    # Arrange
    ...
    # Act
    ...
    # Assert
    assert result == expected

Commit Messages¶

Follow conventional commits:

type(scope): short description

Longer description if needed.

Fixes #123

Types: feat, fix, docs, style, refactor, test, chore

Examples: - feat(ai): add support for Gemini 2.0 Flash - fix(blocks): handle empty command output - docs: update provider configuration guide - test(mcp): add client connection tests

Architecture Guidelines¶

Adding a New AI Provider¶

See DEVELOPMENT.md

Create ai/newprovider.py inheriting from LLMProvider
Implement required methods
Register in ai/factory.py
Add tests in tests/unit/ai/
Update user/providers.md

Adding a New Command¶