Contributing to Navigator

Thanks for contributing! This file covers how to build, test, and verify changes to the Navigator web app before opening a PR or pushing.

Project layout (quick map)

scripts/osm-data.mjs     # Overpass API data fetch -> static/data/<area>.geojson
scripts/osm-dump.mjs     # .osm.pbf dump ingestion -> POIs + routable road graph
src/lib/routing.ts       # pure routing math (A*, POI avoidance, turn-by-turn)
src/lib/routing.worker.ts# Web Worker entry that runs route() off the UI thread
src/lib/prefs.ts         # unit-system preference (localStorage)
src/lib/savedPoints.ts   # browser-local Saved Points store + export/import (merge)
src/lib/components/      # MapView, DirectionsPanel, LocationDialog, …
src/routes/+page.svelte  # top-level page (loads the manifest)

Setup

npm install

# Fetch & build all static data (Overpass + dump). Uses committed data if you
# only need the frontend; see below for data-only commands.
npm run build

# For frontend work without re-fetching over the network:
npm run build:static     # rebuilds just the static site from existing static/data
npm run dev              # Vite dev server

Data-only commands (they hit Overpass / download .pbf — be mindful of rate limits):

npm run build:data       # Overpass fetch -> static/data/*.geojson
npm run build:dump       # .osm.pbf ingestion -> *-poi.geojson + *-graph.json

Running the automated checks

Run all three before considering a change done:

npm run check            # svelte-check (types + Svelte diagnostics) — 0 errors/warnings
npm test                 # 33k+ offline regression checks (data, routing, saved points)
npm run build:static     # static site must build cleanly

These run offline (no Overpass/Nominatim) and are exactly what CI runs on every push. If any of these fail, fix before pushing.

Continuous Integration

CI runs on every push/PR via Gitea Actions (.gitea/workflows/ci.yml).
It runs npm ci, npm run check, npm test, npm run build:static, and verifies build/index.html + build/data exist.
Requires a registered runner with the host label (host-mode, no Docker).

Manual QA checklist

The automated tests cover the data and routing logic. Because this sandbox's browser tooling only reaches public URLs (and cloud browsers are intentionally not used), the visual/interaction layer needs a manual local pass. Open the app locally (npm run dev, or serve build/ with any static server) and verify:

Empty-map click opens a context dialog with "Save point…" — it does not auto-save or auto-start routing.
Existing-point click (a POI/zone/path) opens the dialog showing its info and a "Directions from here" action.
"Directions from here" pins the origin, opens the Directions panel, and lets you pick a destination.
Second-point click offers "Directions to here", which sets it as the destination.
The Directions top-bar button and the top "Data sources" bar are gone (routes start only via the context dialog).
Saved Points toggle in the legend shows/hides the purple saved-point pins.
Preferences → Export / Import round-trips saved points; import merges (dedupes by id) rather than replacing.
Route computation shows a live progress bar and the UI stays responsive (Web Worker is off the main thread).
Drive mode shows turn-by-turn steps (Head north / Turn right / Arrive at destination); Walk mode shows distance + time without turn steps.

Reporting an issue

If a checklist item fails, note:

The step number and what you did.
Expected vs. actual behavior.
Any console errors (browser dev tools → Console).
Screenshot if helpful.

Then either file it or paste the details here for a fix.

Commit conventions

Angular-style, e.g.:

feat(directions): run route in a Web Worker with live progress
fix(ui): open context dialog on map click instead of auto-saving
refactor(prefs): drop redundant unit override
docs: document the context-dialog interaction

Commit small, logical units (often one per task) and keep CI green on each.

4.1 KiB Raw Blame History