Development Guide
This guide covers setting up a local development environment, running the application, and maintaining code quality.
🔧 Prerequisites
- Python 3.15 recommended (3.13 and 3.14 are supported)
- Git
🛠️ Setup Local Environment
Step 1 - Clone the repository
git clone https://github.com/MVladislav/bumper.git
cd bumper
Step 2 - Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
Step 3 - Install uv inside the virtual environment
python3 -m pip install uv
Step 4 - Install project dependencies
uv sync --active --python 3.15 --all-groups --upgrade
🚀 Running the Application
./scripts/certs/create-cert.sh
WEB_SERVER_HTTPS_PORT=8443 uv run --active bumper
The web UI will be available at https://127.0.1.1:8443 by default.
✅ Code Quality and Testing
Linting & Static Analysis
Run prek hooks
prek run --all-files
Type checking with mypy
uv run --active --frozen mypy bumper/
Linting with pylint
uv run --active --frozen pylint bumper/
Unit Tests
Run tests
uv run --active pytest tests
Tests with coverage report
uv run --active pytest --cov=./ tests --cov-report xml --junitxml=pytest-report.xml
Generate HTML coverage report
uv run --active pytest --cov=./ tests --cov-report html:tests/report
The HTML report is located at tests/report/index.html.
📖 Understanding the Code
Refer to the How It Works guide for an overview of the core architecture and data flows.
For route registration, response envelopes, and choosing a template for a new endpoint, see Web API Endpoints.
🔄 Updating Static Ecovacs Data
Bumper ships with pre-fetched Ecovacs data under bumper/web/static_api/.
See Static Data Update Guide.
🤝 Contributing Changes
- Fork the repo and create a feature branch.
- Follow the setup and testing steps above.
- Commit changes with clear messages and update tests.
- Open a pull request against
main, ensuring all checks pass.
See CONTRIBUTING.md for detailed contribution guidelines.