# Contributing to Politrack

Thanks for helping make Austrian politics more transparent. Three principles guide every change:

1. **Every fact has a source.** No claim without evidence; the UI and the API always show it.
2. **Only legal access.** Official APIs and open data first; robots.txt, terms of service and TDM
   reservations are respected – enforced by the framework, documented per source.
3. **Fairness.** Neutral wording, the procedural stage and the presumption of innocence for legal
   matters, connections are not accusations, data about people only in their public role.

## Where to start

| I want to … | Read |
|---|---|
| add a data source (scraper/API) | [docs/contributing/adapters.md](docs/contributing/adapters.md) |
| derive facts from existing data (linking, detection) | [docs/contributing/enrichers.md](docs/contributing/enrichers.md) |
| add an API endpoint or MCP tool | [docs/contributing/api.md](docs/contributing/api.md) |
| add a page or show a new claim type in the UI | [docs/contributing/frontend.md](docs/contributing/frontend.md) |
| run or write tests | [docs/contributing/testing.md](docs/contributing/testing.md) |
| work on this repository with a coding agent | [docs/contributing/agents.md](docs/contributing/agents.md) |
| understand the design | [docs/architecture/01-design-from-scratch.md](docs/architecture/01-design-from-scratch.md), [docs/data-model.md](docs/data-model.md) |
| add a social account or party channel | `backend/config/social_accounts.yaml` (comments explain the fields) |
| add a news feed | `backend/config/feeds.yaml` (+ a `SourceSpec` in `sources/news.py`) |

## Development setup

```bash
cp .env.example .env
docker compose up -d db && docker compose run --rm migrate
# Docker Desktop on Windows: the first start of `db` takes a few minutes (fsync on a bind mount is slow).

# backend
cd backend
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
export POLITRACK_DATABASE_URL=postgresql://politrack:<password>@localhost:5433/politrack POLITRACK_RAW_DIR=./data/raw
pytest
politrack run parlament.persons --max-requests 20
politrack api            # http://localhost:8000/api/docs

# frontend
cd ../web
npm install
API_INTERNAL_URL=http://localhost:8000 npm run dev
```

## Pull requests

* One topic per PR. Explain *what data* and *why it matters*; for new sources, answer the legal checklist
  in [adapters.md](docs/contributing/adapters.md#0-before-writing-code-the-legal-checklist).
* Tests: `pytest` green; new parsers come with golden fixtures; `npm run typecheck` for frontend changes.
* Changed response models → regenerate `web/src/lib/api-types.ts` (`politrack openapi --ts …`).
* New texts in both `web/messages/de.json` and `en.json`.
* Style: Python formatted/linted with `ruff` (line length 110); TypeScript strict.
* Schema changes: a new numbered file in `backend/migrations/` (never edit an applied migration), with
  `COMMENT`s on new tables/columns – agents read them.

## Reporting errors in the data

Wrong or outdated claim? Open an issue with the claim id (shown in the API) and a source for the
correction. Claims are never silently deleted: they are corrected, marked as disputed with the
contradicting source, or rejected in review.