Thank you for your interest in contributing to Keymaster! This guide explains how to set up your development environment, run tests, adhere to code quality standards, and submit pull requests.
Keymaster consists of:
- Python / Home Assistant Backend: Custom integration targeting Python 3.14 standards.
- TypeScript / Lit Frontend: Custom Lovelace dashboard strategy in
lovelace_strategy/.
Ensure Python 3.14 is installed. Set up a virtual environment:
# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install development, test, and lint dependencies
# Requires pip >= 25.1 for --group support
pip install --group dev
# Or using uv pip:
uv pip install --group devEnsure Node.js and Yarn are installed:
# Install frontend dependencies
yarn installInstall pre-commit or prek hooks to automatically check lint and formatting on commit:
# Using pre-commit:
pre-commit install
# Or using prek (fast Rust-based drop-in runner):
prek installNote: prek is a fast local runner that reads .pre-commit-config.yaml.
GitHub CI automatically runs prek.
Before submitting any code, all quality gates must pass cleanly. Adhere to the 100-character line length limit enforced across Python files.
Keymaster uses tox in CI to run tests and linter suites:
# Run all CI test and lint environments
tox
# Run only the lint suite
tox -e lint
# Run only the Python 3.14 pytest suite
tox -e py314You can also run individual tools directly:
-
Formatting & Linting:
# Check and fix lint issues ruff check --fix . # Format python files ruff format .
-
Type Checking:
mypy . -
Spell Checking:
codespell custom_components/keymaster tests
-
Async Hygiene: Use
async_create_taskand Home Assistant async helpers. Never perform blocking synchronous I/O on the event loop.
-
Linting & Formatting:
yarn lint yarn lint:fix
-
Building Strategy Bundle:
yarn build
Keymaster enforces automated testing with a minimum of 80% code coverage
(configured in pyproject.toml under [tool.coverage.report] fail_under = 80).
# Run standard test suite (excludes slow and perf tests)
pytest
# Run tests with terminal coverage report
pytest --cov=custom_components/keymaster --cov-report=term-missing
# Run a specific test file (use --cov-fail-under=0 for targeted runs)
pytest tests/test_coordinator.py --cov-fail-under=0
# Run all tests including slow and perf markers
pytest -m ""# Run Vitest test runner
yarn test
# Run frontend tests with coverage
yarn test:coveragepython3 scripts/compare_lovelace_output.py- Focus on a Single Change: Keep PRs focused. If your work addresses multiple unrelated topics, please split them into separate pull requests.
- Mandatory PR Template: All PR descriptions must follow
.github/PULL_REQUEST_TEMPLATE.md. - Select One Change Type: In the PR template checklist, check exactly
one box:
Dependency upgradeBugfix (non-breaking change which fixes an issue)New feature (which adds functionality)Breaking change (fix/feature causing existing functionality to break)Code quality improvements to existing code or addition of tests
- Link Relevant Issues: Reference any corresponding issue numbers
(
fixes #123orrelated to #123). - Passing CI: Ensure all GitHub Actions workflows (Tox, Pytest, Prek, Codecov, Yarn) pass.