# Contributing

## Prerequisites

- Python 3.11+
- Node.js 20+ (for frontend bundle)
- Git

## Development Setup

```bash
git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
cd wled-screen-controller-mixed/server

# Python environment
python -m venv venv
source venv/bin/activate   # Linux/Mac
# venv\Scripts\activate    # Windows
pip install -e ".[dev]"

# Frontend dependencies
npm install
npm run build
```

## Running the Server

```bash
cd server
export PYTHONPATH=$(pwd)/src   # Linux/Mac
# set PYTHONPATH=%CD%\src      # Windows
python -m wled_controller.main
```

Open http://localhost:8080 to access the dashboard.

## Running Tests

```bash
cd server
pytest
```

Tests use pytest with pytest-asyncio. Coverage reports are generated automatically.

## Code Style

This project uses **black** for formatting and **ruff** for linting (both configured in `pyproject.toml` with a line length of 100).

```bash
cd server
black src/ tests/
ruff check src/ tests/
```

## Frontend Changes

After modifying any file under `server/src/wled_controller/static/js/` or `static/css/`, rebuild the bundle:

```bash
cd server
npm run build
```

The browser loads the esbuild bundle (`static/dist/`), not the source files directly.

## Commit Messages

Follow the [Conventional Commits](https://www.conventionalcommits.org/) format:

```
feat: add new capture engine
fix: correct LED color mapping
refactor: extract filter pipeline
docs: update API reference
test: add audio source tests
chore: update dependencies
```

## Pull Requests

1. Create a feature branch from `master`
2. Make your changes with tests
3. Ensure `ruff check` and `pytest` pass
4. Open a PR with a clear description of the change