0 Fork 0

Files

T

simonandClaude Opus 5.5 0e21730b9f Document coding agents and give them a sandbox image

Agents work on this repository in the agent-envs sandbox: a container
whose only way out is an egress proxy with an allowlist, which also adds
the Gitea bot token. docs/contributing/agents.md covers setting it up
for Politrack (1Password item, .env, commit identity), what it can reach
and its limits; AGENTS.md tells agents how to recognise the sandbox and
behave in it.

backend/tests/Dockerfile.debian gains a `sandbox` target: the agent-envs
agent image plus the backend's dependencies from Debian packages, the
same list as the PyPI-free test image (still the default target). The
sandbox runs `pytest` without PyPI, which the owner's PC can't reach. A
new invariant in AGENTS.md keeps that list in step with pyproject.toml.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-28 23:59:01 +01:00

3.2 KiB

Raw Permalink Blame History

Contributing to Politrack

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

Every fact has a source. No claim without evidence; the UI and the API always show it.
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.
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
derive facts from existing data (linking, detection)	docs/contributing/enrichers.md
add an API endpoint or MCP tool	docs/contributing/api.md
add a page or show a new claim type in the UI	docs/contributing/frontend.md
run or write tests	docs/contributing/testing.md
work on this repository with a coding agent	docs/contributing/agents.md
understand the design	docs/architecture/01-design-from-scratch.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

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.
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 COMMENTs 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.