Contributing¶

We welcome contributions to httptap! This guide will help you get started.

Code of Conduct¶

Please note that this project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Getting Started¶

Prerequisites¶

• Python 3.11 or higher (CPython)
• uv package manager
• Git

Setting Up Development Environment¶

1. Fork and clone the repository:

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

1. Install dependencies:

uv sync

1. Verify installation:

uv run httptap --version

Development Workflow¶

Running Tests¶

Run the full test suite:

uv run pytest

Run with coverage:

uv run pytest --cov --cov-report=html

View coverage report:

open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

Code Quality¶

Linting¶

Run Ruff linter:

uv run ruff check

Auto-fix issues:

uv run ruff check --fix

Formatting¶

Check formatting:

uv run ruff format --check

Auto-format code:

uv run ruff format .

Type Checking¶

Run mypy:

uv run mypy httptap

Running Benchmarks¶

Performance benchmarks use pytest-codspeed and run automatically in CI:

# Run benchmarks locally (validates correctness, no performance data)
uv run pytest tests/test_benchmarks.py --codspeed

# Measure wall-clock time locally, with a results table
uv run pytest tests/test_benchmarks.py --codspeed --codspeed-mode=walltime

# Run benchmarks without CodSpeed (as regular tests)
uv run pytest tests/test_benchmarks.py

Benchmarks cover pure-computation functions across models, formatters, utils, and exporter modules. CI measures CPU instructions (simulation) and memory allocations (memory).

Use --codspeed-mode=walltime to check an optimization locally without waiting for CI; it takes roughly two seconds per benchmark. Wall-clock numbers are inherently noisy on shared hardware, so CI relies on simulation instead — treat local walltime results as a directional signal, not as the value CI will report.

Running the End-to-End Tests¶

The suite in tests/e2e runs the httptap CLI as a subprocess against local HTTP, TLS, proxy, SOCKS5 and OTLP servers. A plain uv run pytest does not collect it; pass the directory explicitly:

# Against the source checkout (the otel extra is needed for the OTLP tests)
uv run --extra otel pytest tests/e2e --no-cov -n auto

# Against another build, such as an installed wheel
uv run pytest tests/e2e --no-cov -n auto --httptap /path/to/venv/bin/httptap

CI runs it against the built wheel and the container image, and the daily E2E matrix workflow repeats it on Linux, macOS and Windows with Python 3.11, 3.13, 3.14, 3.14t, 3.15 and 3.15t. See tests/e2e/README.md for running it against a Docker image and for all options.

Running Locally¶

Test your changes:

uv run httptap https://httpbin.io

Or install in editable mode:

uv pip install -e .
httptap https://httpbin.io

Making Changes¶

Branch Naming¶

Use descriptive branch names:

• feature/add-http2-support - New features
• fix/tls-timeout-issue - Bug fixes
• docs/update-api-reference - Documentation
• refactor/extract-parser - Code refactoring

Commit Messages¶

Follow conventional commits format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation changes
• refactor - Code refactoring
• test - Adding/updating tests
• chore - Maintenance tasks
• perf - Performance improvements

Examples:

feat(cli): add --timeout flag for request timeout

Add command-line option to specify custom timeout for HTTP requests.
Defaults to 20 seconds if not specified.

Closes #123

fix(tls): handle certificate expiry edge case

Fix crash when certificate expiry date is in the past.
Now properly reports negative days and warns user.

Fixes #456

Code Style¶

Follow the Google Python Style Guide:

• Use type hints for all function signatures
• Write docstrings for all public APIs
• Keep lines under 120 characters
• Use double quotes for strings
• Follow PEP 8 naming conventions

Example:

def resolve_hostname(host: str, timeout: float = 5.0) -> tuple[str, str]:
    """Resolve hostname to IP address.

    Args:
        host: Hostname to resolve.
        timeout: Maximum time to wait in seconds.

    Returns:
        Tuple of (ip_address, family).

    Raises:
        DNSError: If resolution fails.
    """
    pass

Testing Guidelines¶

• Write tests for all new features
• Maintain or improve code coverage
• Use descriptive test names
• Mock external dependencies (DNS, TLS, HTTP)
• Test both success and failure cases

Example:

def test_analyzer_follows_redirects(mock_http_client):
    """Test that analyzer follows redirect chains correctly."""
    analyzer = HTTPTapAnalyzer(follow_redirects=True)
    steps = analyzer.analyze_url("https://httpbin.io/redirect/3")

    assert len(steps) == 4  # Initial + 3 redirects
    assert steps[-1].response.status == 200

Pull Request Process¶

1. Create a feature branch:

git checkout -b feature/your-feature-name

1. Make your changes and commit:

git add .
git commit -m "feat: add awesome feature"

1. Push to your fork:

git push origin feature/your-feature-name

1. Create a Pull Request:

   • Go to the httptap repository
   • Click "New Pull Request"
   • Select your branch
   • Fill out the PR template

PR Checklist¶

Before submitting, ensure:

• Tests pass (uv run pytest)
• Code is formatted (uv run ruff format .)
• Linter passes (uv run ruff check)
• Type checks pass (uv run mypy httptap)
• Documentation is updated (if needed)
• Commit messages follow conventional format (CHANGELOG.md is generated from them by git-cliff at release time; do not edit it by hand)

Documentation¶

Updating Docs¶

Documentation is in the docs/ directory:

docs/
├── getting-started/
├── usage/
├── api/
├── development/
└── about/

Build docs locally:

uv sync --group docs
uv run mkdocs serve

View at: http://127.0.0.1:8000

Documentation Standards¶

• Use clear, concise language
• Include code examples
• Keep examples realistic and practical
• Use proper Markdown formatting
• Test all code examples

Areas for Contribution¶

Good First Issues¶

Look for issues labeled good first issue - these are beginner-friendly.

Help Wanted¶

Issues labeled help wanted are priorities we'd love assistance with.

Ideas for Contributions¶

These follow the in-scope themes of the roadmap, which also lists the non-goals (load testing, non-HTTP protocols such as WebSocket or gRPC, a GUI/TUI, a plugin loader):

• Timing accuracy - Refinements to trace hooks and the fallback estimates
• More export formats - Further machine-readable exporters driven by a concrete need (Prometheus and OpenTelemetry export already ship)
• SLO extensions - Relative budgets against a baseline, soft vs hard SLOs
• More TLS details - OCSP, certificate chain analysis
• HTTP/3 support - Once stable Python support lands upstream
• Documentation - Worked examples, troubleshooting recipes, integration cookbooks

Getting Help¶

• GitHub Issues - Bug reports and feature requests
• Discussions - Questions and general discussion
• Discord - Real-time chat (coming soon)

Recognition¶

Contributors are recognized in:

• CHANGELOG.md
• GitHub Contributors page
• Release notes

Thank you for contributing to httptap! 🎉