Skip to content

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

  1. Fork the repo and create a feature branch.
  2. Follow the setup and testing steps above.
  3. Commit changes with clear messages and update tests.
  4. Open a pull request against main, ensuring all checks pass.

See CONTRIBUTING.md for detailed contribution guidelines.