Contributing

Contributing to Fast Channels

Thank you for your interest in contributing to Fast Channels! This guide will help you set up the development environment and understand the tools and processes used in this project.

Prerequisites

Before starting development, ensure you have the following installed:

Docker and Docker Compose
uv for Python package management
Python 3.11+ (project supports 3.11, 3.12, and 3.13)

Install the library for development

Setting up your environment

Create your own virtual environment and activate it:

uv venv # or python -m venv .venv
source .venv/bin/activate

Then use uv to install all dev packages:

uv sync --all-extras

Using tox for complete environment testing

For testing across multiple Python versions and configurations, we use tox:

# Install tox following the official documentation
# https://tox.wiki/en/latest/installation.html
uv tool install tox

# Run tests on all supported Python versions
tox

# Run tests for a specific environment
tox -e py311

# Run only the linting checks
tox -e lint

# Run test coverage
tox -e coverage

Prepare the environment

Before running tests, ensure:

Docker is running
Run docker compose up to launch required services

Code quality tools

Fast Channels uses several tools to ensure code quality. You should run these tools before submitting a pull request.

Pre-commit hooks

We use pre-commit hooks to automatically check and format your code on commit. Install them with:

pip install pre-commit
pre-commit install

Linting and formatting

For manual linting and formatting:

# Run linting checks
bash scripts/lint.sh

# Fix linting issues automatically
bash scripts/lint.sh --fix

This runs:

Ruff for fast Python linting
Black for code formatting
toml-sort for TOML file formatting

Type checking

We use multiple type checking tools for maximum safety:

# Run mypy on the fast_channels package
bash scripts/mypy.sh

# Run pyright
pyright

The project uses strict type checking settings to ensure high code quality.

Docstring coverage

We aim for high docstring coverage. Check your docstring coverage with:

# Run interrogate to check docstring coverage
interrogate -vv fast_channels

The project requires at least 80% docstring coverage as configured in the project settings.

Testing

Running tests

# Run all tests
pytest tests

# Run tests with coverage report
pytest --cov-report term-missing --cov=fast_channels tests

Writing tests

When adding new features, please include appropriate tests in the tests directory. Tests should:

Verify the expected behavior of your feature
Include both success and failure cases
Use the fixtures and utilities provided by the testing framework

Redis Sentinel Testing

The project includes additional tests for Redis Sentinel compatibility in the tests_extra directory, run separately to verify fast-channels works correctly with Redis Sentinel clusters.

Running Redis Sentinel tests locally

# Run with Docker (full setup and teardown)
tests_extra/redis_sentinel/run_test.sh

# Run in cache mode (keeps cluster running for faster subsequent tests)
tests_extra/redis_sentinel/run_test.sh --cache

# Or using tox
tox -e extras

Test environment

The Redis Sentinel tests:

Use a separate test suite in tests_extra/redis_sentinel/tests/
Test compatibility and functionality, not coverage (coverage metrics are not collected)
Run against a real Redis Sentinel cluster via Docker Compose
Execute automatically in CI with GitHub Actions services

Validate your changes before submission

Before creating a pull request, please ensure your code meets the project’s standards:

1. Run the test suite

pytest --cov-report term-missing --cov=fast_channels tests

2. Run type checkers

bash scripts/mypy.sh
pyright

3. Lint and format your code

bash scripts/lint.sh --fix

4. Check docstring coverage

interrogate -vv fast_channels

5. Run the complete validation suite with tox

tox

Commit guidelines

For committing code, use the Commitizen tool to follow commit best practices:

cz commit

This ensures that all commits follow the Conventional Commits format.

Creating a Pull Request

When creating a pull request:

Make sure all tests pass and code quality checks succeed
Update the documentation if needed
Add a clear description of your changes
Reference any related issues

Development best practices

Keep changes focused: Each PR should address a single concern
Write descriptive docstrings: All public API functions should be well-documented
Add type annotations: All code should be properly typed
Test thoroughly: Include tests for all new functionality

These validation steps are also run automatically in the CI when you open the pull request.

Thank you for contributing to Fast Channels!