# Contributing

Issues and merge requests on
[git.b4l.co.th](https://git.b4l.co.th/B4L/Northern-Thailand-Ping-River-Monitor).
The repository has two halves: the service in Rust (`rust/`, see
[rust/README.md](rust/README.md)) and the model training/evaluation stack in Python
(`src/ml`, see [docs/FLOOD_FORECASTING.md](docs/FLOOD_FORECASTING.md)).

## Setup

- Python 3.11 and [uv](https://docs.astral.sh/uv/) (3.12+ has no pandas 2.0.3 wheels)
- Rust >= 1.88 from [rustup](https://rustup.rs), plus `pkg-config` and `libssl-dev` on Linux
- Docker (or any PostgreSQL 16) for the database tests

```bash
git clone https://git.b4l.co.th/B4L/Northern-Thailand-Ping-River-Monitor.git
cd Northern-Thailand-Ping-River-Monitor
make install                     # uv sync + pre-commit hooks
docker run -d --name ping-pg -e POSTGRES_PASSWORD=ping -e POSTGRES_DB=ping -p 55432:5432 postgres:16
export TEST_DATABASE_URL=postgres://postgres:ping@localhost:55432/ping
make check                       # format check, flake8, clippy, pytest, cargo test, Rust 1.88
```

Without `TEST_DATABASE_URL` the database tests are skipped, the rest still run.

## Before a merge request

- `make format`, then `make check` green. CI runs the same (`.gitea/workflows/`).
- One logical change per commit, imperative subject (`fix(collector): ...`,
  `feat(web): ...`, `docs: ...`).
- Dashboard changes (`src/static/dashboard.html`): every visible string in English
  and Thai (`t()` table); a screenshot in the merge request.
- API changes: keep existing fields and formats; external clients read them. New
  parameters go into the route's declaration in `rust/collector/src/web/params.rs`,
  which also documents them at `/docs`.
- Model changes: evaluate with `scripts/evaluate_variants.py` (rolling origin, judged
  on first-alert lead and false alarms) and record the result in
  `docs/FLOOD_FORECASTING.md` section 5, whether it helped or not. A feature change
  must be ported to `rust/forecast` in the same change (see CLAUDE.md for the
  fixture and config regeneration steps).
- Never commit credentials, `.env`, trained models (`models/*.joblib`,
  `models/*.json.gz`) or the server's private addresses.

## Useful commands

```bash
make build && make serve          # the website/API from your database on 127.0.0.1:8001
uv run python scripts/dev_proxy.py  # the working-copy dashboard against the live API
uv run python scripts/evaluate_variants.py --stations P.1
uv run python -m src.ml.export --config   # after changing thresholds or notifier settings
```