Contributing

Contributing

Dev setup

git clone https://github.com/SpaceSquare640/PokeTrack-App.git
cd PokeTrack-App
python -m venv .venv && .venv\Scripts\activate     # Windows
pip install -r requirements.txt
pip install pytest

Optional, for the polyglot pieces (only needed to rebuild them — the compiled artifacts are committed, so plain Python/JS work doesn't require either):

# Rust native fast path
pip install maturin
pip install ./poketrack-native
python poketrack-native/benchmark.py

# TypeScript web front-end
cd web-frontend
npm install
npm run build     # type-check + emit poketrack/web/static/dist/app.js
npm run dev        # optional: Vite dev server

Running tests

python -m pytest -q

The suite is fully offline — a FakeSource and temp DB/config dirs, so it never touches your real config.json/data/ and never makes network requests. It runs in CI on every push across Python 3.11–3.13 (pure-Python matrix) and a separate native job (Python 3.12 + the Rust extension built and installed) so the native/Python parity test actually exercises both paths. A frontend CI job type-checks and builds the TypeScript bundle.

When adding a feature, prefer extending the existing test file (tests/test_poketrack.py) with a focused test near related tests, following the existing fixture patterns (service fixture, make_event() helper, FakeSource).

Conventions

• Every visible string goes through the translator (service.t("section.key")) — never hard-code UI text. Add the key to every language block in languages.json, not just en (fallback to English handles a temporarily-missing translation, but don't rely on that for new keys you're adding intentionally).
• Every colour comes from poketrack/gui/theme.py's MIDNIGHT_BLUE dict — the web layer injects the same values into Tailwind, so the two UIs stay pixel-identical. Don't hard-code a hex value in a template or widget.
• UI code never imports the parser or database directly — go through PokeTrackService. This is what keeps poketrack.core reusable and testable independent of either front-end.
• Optional dependencies degrade gracefully — the pattern used by Pillow, plyer, pystray, and the Rust extension: a guarded try/except import, a module-level AVAILABLE/_OK flag, and callers that check it rather than assuming the feature exists. Follow this pattern for any new optional dependency.
• Datetimes are timezone-naive local everywhere in core — see models._parse_dt. If you touch datetime handling, keep that invariant; breaking it previously caused "can't compare offset-naive and offset-aware datetimes" crashes.

Adding a language

1. Copy the "en" block in languages.json to a new top-level key (e.g. "fr").
2. Translate the values (keep {placeholder} tokens intact).
3. Add the language's display name (in its own script) under every languages.* block across all language sections, so the picker shows it correctly regardless of which language is currently active.
4. No code changes needed — Translator.available_languages() picks it up automatically from the catalog.

Extending the region map

Regional events aren't tagged in the feed, so PokéTrack infers a region from the event name/heading via an ordered keyword list in data/regions_map.json. To add a new regional event pattern:

1. Add a [keyword, region] pair to the keywords array. Order matters — the first matching keyword wins, so put more specific keywords before general ones.
2. Keywords are matched case-insensitively as a substring of f"{name} {heading}".lower().
3. If you also work on the Rust fast path, note classify() in poketrack-native/src/lib.rs mirrors this exact algorithm — the parity test (test_parser_native_matches_python) will catch a divergence.

Working on the Rust extension

cd poketrack-native
cargo fmt        # required — cargo fmt --check runs in spirit of CI hygiene
cargo clippy --release
maturin build --release
pip install --force-reinstall target/wheels/*.whl
python -m pytest -q      # from repo root — exercises the native/Python parity test

Any change to parse_feed/classify_region semantics must keep exact parity with the pure-Python path in poketrack/core/parser.py / poketrack/core/regions.py — that's what the parity test enforces.

Working on the TypeScript front-end

Source lives in web-frontend/src/; the compiled bundle (poketrack/web/static/dist/app.js) must be committed after any change — running the app reads the committed file, not the source. Always run npm run build (which type-checks first) before committing.

Pull requests

• Keep changes scoped — a bug fix doesn't need surrounding refactors.
• Run the full test suite (and, if relevant, cargo fmt/clippy or npm run build) before submitting.
• Update CHANGELOG.md under an [Unreleased] heading if your change is user-facing.

See Architecture for the layering rules a change is expected to respect, and Legal & Disclaimer — contributions must not introduce Pokémon trademarked assets (character art, official logos) into the repository.