# Headroom Coding Standards: Linting, Formatting, and Type Safety Rules

> Discover Headroom coding standards. Enforce PEP 8, type safety with Mypy, and conventional commits via pre-commit hooks. Ensure code quality and consistency.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: best-practices
- Published: 2026-06-21

---

**Headroom enforces coding standards through automated pre-commit hooks including Ruff for PEP 8 compliance with 100-character lines, Mypy for static type checking, and Commitlint for conventional commit messages, alongside Google-style docstrings and 80% test coverage requirements.**

The headroom repository maintains strict coding standards to ensure code quality and consistency across all contributions. These standards are defined in [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md) and enforced automatically through the pre-commit configuration found in [`.pre-commit-config.yaml`](https://github.com/chopratejas/headroom/blob/main/.pre-commit-config.yaml). Understanding these requirements is essential for anyone contributing to the headroom project.

## Automated Linting and Formatting with Ruff

All Python files must pass through **Ruff**, which serves as both the linter and auto-formatter for the project. The configuration enforces **PEP 8** standards with a maximum line length of **100 characters**, diverging from the traditional 80-character limit. The hooks `ruff` and `ruff-format` run automatically on every commit to fix style violations and ensure consistent formatting.

The specific rules and exclusions are configured in [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml), allowing the project to customize which PEP 8 guidelines to enforce while maintaining the 100-character limit across all source files.

## Mandatory Static Type Checking

Headroom requires **type hints** for all public functions, enforced by **Mypy** running with the `--ignore-missing-imports` flag. The type checker executes against the `headroom` package using the command `mypy headroom` to catch interface mismatches and type errors before they reach the main branch.

This strict typing requirement ensures that function signatures explicitly declare expected argument types and return values, creating a self-documenting codebase that catches errors at static analysis time rather than runtime.

## Conventional Commit Message Standards

The project uses **Commitlint** to validate commit messages before they are accepted into the repository. All commits must follow the **conventional commit** format with specific prefixes including `feat:`, `fix:`, and `docs:`.

This enforcement ensures that the repository history remains readable, automatable, and suitable for automated changelog generation. The validation runs as a pre-commit hook, preventing non-compliant commits from being created.

## Google-Style Docstring Requirements

All public APIs must include **Google-style docstrings** as specified in the "Coding standards" section of [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md). These docstrings require specific sections including `Args:` and `Returns:` to document parameters and return values explicitly.

For example, a compliant public function includes type hints and follows the Google format:

```python
def compress(messages: list[dict[str, str]], *, model: str = "gpt-4") -> list[dict]:
    """Compress a list of LLM messages.

    Args:
        messages: A list of message dictionaries as expected by the LLM API.
        model:   The identifier of the model to use for compression.

    Returns:
        A new list of messages where large payloads have been reduced.
    """
    # implementation …

```

## Test Coverage and Quality Gates

Every new feature must include accompanying tests that raise code coverage above **80%** for the changed module. Contributors must verify that all tests pass locally before pushing to CI, as the test suite serves as a mandatory quality gate.

This requirement ensures that new functionality comes with proper regression testing and maintains the project's overall reliability standards.

## Python Version Compatibility

The project targets **Python 3.10+**, with all code required to remain backward compatible with this minimum version. While newer Python versions are allowed for development, features cannot use syntax or standard library modules introduced after Python 3.10 unless properly gated.

## Running Pre-Commit Hooks Locally

Contributors should install the git hooks immediately after cloning to ensure all coding standards for headroom are checked automatically:

```bash

# Install the git hooks (run once after cloning)

make install-git-hooks

```

Once installed, the hooks run automatically on every commit. For example, when committing new code:

```bash
git add .
git commit -m "feat: add compress helper"

```

This triggers the complete validation pipeline: Ruff formats and fixes style issues, Commitlint validates the conventional commit prefix, and Mypy checks type annotations before the commit is finalized.

## Summary

- **Ruff** enforces PEP 8 with a 100-character line limit through automated pre-commit hooks defined in [`.pre-commit-config.yaml`](https://github.com/chopratejas/headroom/blob/main/.pre-commit-config.yaml).
- **Mypy** requires type hints for all public functions and runs with `--ignore-missing-imports` to ensure type safety.
- **Commitlint** validates conventional commit prefixes (`feat:`, `fix:`, `docs:`) to maintain readable repository history.
- **Google-style docstrings** are mandatory for all public APIs as documented in [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md).
- **Python 3.10+** is the minimum supported version, requiring backward compatibility in all contributions.
- **80% test coverage** is required for new modules, with local test execution mandatory before CI submission.

## Frequently Asked Questions

### What is the maximum line length allowed in headroom code?

Headroom enforces a maximum line length of **100 characters** through Ruff configuration, as defined in the project's [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml) and enforced via the pre-commit hooks. This provides more flexibility than the traditional 80-character limit while maintaining readability across different devices and editors.

### Are type hints mandatory for all functions in headroom?

Yes, according to the coding standards in [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md), all public functions must expose type hints, and the code must pass Mypy type checking under the `--ignore-missing-imports` flag. This requirement ensures interface contracts are explicitly defined and catches type mismatches during static analysis.

### How do I format my commit messages for headroom contributions?

All commit messages must follow the conventional commit format with specific prefixes such as `feat:`, `fix:`, `docs:`, `refactor:`, or `test:`. The Commitlint hook in [`.pre-commit-config.yaml`](https://github.com/chopratejas/headroom/blob/main/.pre-commit-config.yaml) automatically validates these prefixes before allowing the commit to complete, ensuring consistent changelog generation.

### What Python versions does headroom support?

The project targets **Python 3.10 and newer**, requiring all contributions to maintain backward compatibility with Python 3.10. While contributors may use newer Python versions for development, code cannot utilize features or syntax introduced in Python 3.11 or later unless properly version-gated.